390 lines
12 KiB
Groff
390 lines
12 KiB
Groff
.\" $NetBSD: pkg_alternatives.8,v 1.6 2013/07/20 21:50:53 wiz Exp $
|
|
.\"
|
|
.\" pkg_alternatives - Generic wrappers for programs with similar interfaces
|
|
.\" Copyright (c) 2005 Julio M. Merino Vidal <jmmv@NetBSD.org>
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\" 3. Neither the name of author nor the names of its contributors may
|
|
.\" be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd January 30, 2005
|
|
.Dt PKG_ALTERNATIVES 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pkg_alternatives
|
|
.Nd generic wrappers for programs with similar interfaces
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl gsw
|
|
.Op Fl p Ar prefix
|
|
.Cm action
|
|
.Ar arg1 ... argN
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a tool to manage the
|
|
.Em alternatives system
|
|
provided by The
|
|
.Nx
|
|
Packages Collection, also known as pkgsrc.
|
|
It creates, configures, and destroys generic wrappers used to run
|
|
programs with similar interfaces.
|
|
.Pp
|
|
Consider, for example, the
|
|
.Xr vi 1
|
|
editor.
|
|
Both
|
|
.Xr nvi 1
|
|
and
|
|
.Xr vim 1
|
|
provide very similar functionality, although neither of them is named
|
|
.Pa vi .
|
|
In this situation, it may be useful to have a
|
|
.Em wrapper
|
|
in place of the generic name which points to one of the multiple
|
|
.Em alternatives
|
|
available.
|
|
.Pp
|
|
The alternatives are classified according to the package they belong to,
|
|
forming
|
|
.Em groups
|
|
of alternatives.
|
|
In other words, a concrete package contains a list of all the wrappers it
|
|
affects by providing alternatives to them.
|
|
This makes things easier for the end user and/or the administrator who has
|
|
to deal with them, as they can manually select a group (package) rather than a
|
|
bunch of wrappers.
|
|
.Pp
|
|
Wrappers are identified by their filename relative to the installation
|
|
prefix, i.e.,
|
|
.Pa @PREFIX@
|
|
if the
|
|
.Fl p
|
|
option is not used.
|
|
In the example above, the wrapper could be identified by the
|
|
.Pa bin/vi
|
|
string.
|
|
The identifier is the string used as the
|
|
.Dq wrapper
|
|
argument in all the actions that require it.
|
|
.Pp
|
|
The generic wrapper scans a list of available alternatives and tries to
|
|
execute them in order; the first one that succeeds is the one used for
|
|
that run.
|
|
This list of alternatives is read from multiple configuration files.
|
|
Each one contains a list of possible alternatives, one per line, with
|
|
optional arguments to them.
|
|
Lines starting with
|
|
.Sq #
|
|
are considered comments and are ignored.
|
|
.Pp
|
|
The following configuration files are read, in strict order, for each
|
|
wrapper (replace the
|
|
.Dq wrapper
|
|
word with the wrapper's absolute file name):
|
|
.Bl -tag -width XXXX
|
|
.It Pa ~/.alternatives/wrapper
|
|
This is called the
|
|
.Em user configuration file
|
|
and is only read when not running as
|
|
.Dq @ROOT_USER@ .
|
|
Otherwise, tools such as
|
|
.Xr sudo 8
|
|
could be used to execute any program in the system.
|
|
This file can be freely edited by the user, either by hand or by using
|
|
the
|
|
.Cm manual
|
|
action described below.
|
|
.It Pa @CONFDIR@/wrapper
|
|
This is called the
|
|
.Em system configuration file
|
|
and is read if found.
|
|
This file can be freely edited by the administrator, either by hand or
|
|
by using the
|
|
.Cm manual
|
|
action described below.
|
|
.It Pa @DATADIR@/wrapper
|
|
This is called the
|
|
.Em database configuration file
|
|
and is always read.
|
|
This file must not be edited by hand; packages providing alternatives
|
|
will take care to (un)register themselves from them when (de)installed.
|
|
.El
|
|
.Ss Options
|
|
The following options are available:
|
|
.Bl -tag -width XpXprefixX
|
|
.It Fl g
|
|
Operate on groups of wrappers rather than individual files.
|
|
This is the opposite of
|
|
.Fl w
|
|
and is currently the default behavior.
|
|
Affects the behavior of all actions.
|
|
.It Fl p Ar prefix
|
|
Set installation prefix.
|
|
This affects where wrappers and their manual pages are looked for.
|
|
The prefix defaults to
|
|
.Pa @PREFIX@
|
|
if this flag is not given.
|
|
.It Fl s
|
|
Run in silent mode: no output except for errors.
|
|
.It Fl w
|
|
Operate on individual wrappers rather than on groups.
|
|
This is the opposite of
|
|
.Fl g .
|
|
Affects the behavior of all actions.
|
|
.El
|
|
.Ss Actions in group mode
|
|
The following table describes each available action and its behavior when
|
|
working in group mode.
|
|
All these actions are at a higher level than the same actions in wrapper
|
|
mode.
|
|
They always end up using the later at some point, so you should also
|
|
read the next section to be aware of the exact effect of each command.
|
|
.Bl -tag -width XXXX
|
|
.It Cm auto Ar package
|
|
Removes any manual configuration from each wrapper associated with the given
|
|
package.
|
|
This means that all affected wrappers are then free to choose whichever
|
|
alternative they prefer.
|
|
.It Cm destroy
|
|
Removes the alternative database, found in
|
|
.Pa @DBDIR@ ,
|
|
and all its associated wrappers and manual pages.
|
|
This action is intended to be used by the
|
|
.Nm
|
|
package.
|
|
.It Cm list
|
|
Lists which of the installed packages provide alternatives.
|
|
Any of the packages shown by this command can then be fed back to the
|
|
.Cm auto
|
|
and
|
|
.Cm manual
|
|
actions.
|
|
.It Cm manual Ar package
|
|
Manually selects all the alternatives that belong to
|
|
.Ar package
|
|
to be the default for their respective wrappers.
|
|
.It Cm rebuild
|
|
Rebuilds the alternatives database, found in
|
|
.Pa @DBDIR@ ,
|
|
based on the contents of the package database, usually available in
|
|
.Pa @PKG_DBDIR@ .
|
|
Basically, it scans the later looking for packages with an
|
|
.Pa +ALTERNATIVES
|
|
file in them, and, for each of those, the
|
|
.Cm register
|
|
action is called with the appropriate file name.
|
|
This action is intended to be used by the
|
|
.Nm
|
|
package or in case of database corruption.
|
|
.It Cm register Ar package wrapper alternative arguments
|
|
Registers a new
|
|
.Ar alternative
|
|
for the given
|
|
.Ar wrapper
|
|
in the specified
|
|
.Ar package .
|
|
If the package does not exist in the database, it is created.
|
|
.Pp
|
|
This action must not be used directly; packages providing alternatives
|
|
will take care to execute it at installation time.
|
|
.It Cm status Ar package
|
|
For each wrapper that belongs to
|
|
.Ar package ,
|
|
shows which alternative will be used by it in the next run.
|
|
It also displays all available candidates for each of them.
|
|
.It Cm unregister Ar package
|
|
Removes the
|
|
.Ar package
|
|
from the database.
|
|
All alternatives associated to it are also removed.
|
|
.Pp
|
|
This action must not be used directly; packages providing alternatives
|
|
will take care to execute it at deinstallation time.
|
|
.El
|
|
.Ss Actions in wrapper mode
|
|
The following table describes each available action and its behavior when
|
|
working in wrapper mode.
|
|
Note that these actions work at a very low level as they are used to manage
|
|
wrappers and alternative commands directly.
|
|
In most situations, you will want to use these actions in group mode.
|
|
.Bl -tag -width XXXX
|
|
.It Cm auto Ar wrapper
|
|
Removes any manual configuration created for the given
|
|
.Ar wrapper .
|
|
That is, if running as
|
|
.Dq @ROOT_USER@ ,
|
|
the system configuration file is deleted; otherwise, the user configuration
|
|
file is removed.
|
|
The effect of this action is that the wrapper is then free to choose any
|
|
alternative it wants.
|
|
.It Cm manual Ar wrapper alternative arguments
|
|
Manually selects the
|
|
.Ar alternative
|
|
for the given
|
|
.Ar wrapper .
|
|
If running as
|
|
.Dq @ROOT_USER@ ,
|
|
the system configuration file is modified; otherwise, the user configuration
|
|
file is changed.
|
|
The effect of this action is that the wrapper will try to use your preferred
|
|
alternatives, regardless of what is installed on the system.
|
|
.It Cm register Ar wrapper alternative arguments
|
|
Registers a new
|
|
.Ar alternative
|
|
for the given
|
|
.Ar wrapper .
|
|
If the wrapper did not exist before, it is created.
|
|
You may optionally pass several
|
|
.Ar arguments
|
|
to the
|
|
.Ar alternative
|
|
program.
|
|
.Pp
|
|
This action should not be used directly; packages providing alternatives
|
|
will take care to execute it at installation time.
|
|
.It Cm status Ar wrapper
|
|
Shows which alternative will be used by the
|
|
.Ar wrapper
|
|
in the next run.
|
|
It also displays all available candidates for it.
|
|
.It Cm unregister Ar wrapper alternative
|
|
Removes the
|
|
.Ar alternative
|
|
from the given
|
|
.Ar wrapper .
|
|
If there are no more alternatives available, the wrapper is removed.
|
|
.Pp
|
|
This action should not be used directly; packages providing alternatives
|
|
will take care to execute it at deinstallation time.
|
|
.El
|
|
.Ss Filtering wrappers
|
|
.Nm
|
|
lets you choose which wrappers you want on your system and which ones should
|
|
simply be ignored.
|
|
This is accomplished by a filter matched against every wrapper, which is
|
|
defined in the
|
|
.Pa @CONFDIR@/filter.conf
|
|
file.
|
|
.Pp
|
|
A filter is composed of multiple entries.
|
|
Each entry contains an action and a regular expression, separated by a
|
|
.Em single space .
|
|
The action can be either
|
|
.Dq accept
|
|
or
|
|
.Dq ignore .
|
|
The former specifies that, if the regular expression is matched against a
|
|
wrapper name, processing should stop and the wrapper should be created.
|
|
The later is exactly the opposite: if the name matches the expression, the
|
|
wrapper is ignored and processing stops.
|
|
.Pp
|
|
Please note that, after modifying the filter configuration file, the
|
|
wrappers database
|
|
.Em must be rebuilt
|
|
using the
|
|
.Dq rebuild
|
|
action.
|
|
Otherwise your changes will take no effect.
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width PKG_DBDIR
|
|
.It Ev PKG_DBDIR
|
|
Location of the package database directory.
|
|
Defaults to
|
|
.Pa @PKG_DBDIR@ .
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width XXXX
|
|
.It Pa ~/.pkg_alternatives/
|
|
User-specific configuration directory.
|
|
.It Pa @CONFDIR@/
|
|
System-wide configuration directory.
|
|
.It Pa @CONFDIR@/filter.conf
|
|
Wrapper filter.
|
|
.It Pa @DATADIR@/
|
|
System-wide configuration database.
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
.Nm
|
|
exists 0 on success and 1 if an error occurred.
|
|
.Sh EXAMPLES
|
|
.Ss Managing wrapper groups
|
|
The following command tells all Vim related wrappers (which include
|
|
.Xr ex 1 ,
|
|
.Xr vi 1
|
|
and
|
|
.Xr view 1 )
|
|
to always prefer Vim in favour of any other program:
|
|
.Bd -literal -offset indent
|
|
# pkg_alternatives manual vim
|
|
.Ed
|
|
.Pp
|
|
And the following command reverts the previous change, configuring the
|
|
affected wrappers to use whichever alternative is available:
|
|
.Bd -literal -offset indent
|
|
# pkg_alternatives auto vim
|
|
.Ed
|
|
.Ss Managing individual wrappers
|
|
Suppose that you want to use Sun's Java 1.5 by default for all Java-related
|
|
wrappers, except for
|
|
.Xr appletviewer 1 ,
|
|
because you want to use Kaffe in that case.
|
|
The following commands do this, by first selecting Sun's Java 1.5 and later
|
|
overriding the exact wrapper to refer to Kaffe:
|
|
.Bd -literal -offset indent
|
|
# pkg_alternatives manual sun-jre15
|
|
# pkg_alternatives manual sun-jdk15
|
|
# pkg_alternatives -w manual bin/appletviewer \\
|
|
/usr/pkg/bin/kaffe-appletviewer
|
|
.Ed
|
|
.Ss Applying filters
|
|
Let us consider a very typical situation: you have just installed a Python
|
|
interpreter and you want the
|
|
.Pa bin/python
|
|
wrapper to be created, but you do not want to pollute your system with any
|
|
other wrapper (such as those coming from Vim).
|
|
You can achieve this by using a filter that first accepts the Python wrapper
|
|
and then ignores everything else.
|
|
The following lines could be added to
|
|
.Pa @CONFDIR@/filter.conf
|
|
to achieve this:
|
|
.Bd -literal -offset indent
|
|
accept ^bin/python$
|
|
ignore .*
|
|
.Ed
|
|
.Pp
|
|
Don't forget to run the following command after doing the above changes:
|
|
.Bd -literal -offset indent
|
|
# pkg_alternatives rebuild
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr pkg_add 1 ,
|
|
.Xr pkg_delete 1
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in pkgsrc-2005Q1.
|
|
.Pp
|
|
This utility was inspired by the alternatives system found in the Debian
|
|
operating system.
|
|
.Sh AUTHORS
|
|
.An Julio M. Merino Vidal Aq Mt jmmv@NetBSD.org
|