.\" $NetBSD: pkg_alternatives.8,v 1.7 2020/01/10 12:20:50 leot 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 10, 2020
.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 ~/.pkg_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