path: root/pkgtools/pkg_alternatives/files/pkg_alternatives.8

.\" $NetBSD: pkg_alternatives.8,v 1.2 2005/01/25 16:27:37 jmmv 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 25, 2005
.Dt ALTERNATIVES 8
.Os
.Sh NAME
.Nm pkg_alternatives
.Nd generic wrappers for programs with similar interfaces
.Sh SYNOPSIS
.Nm
.Op Fl sw
.Op Fl p Ar prefix
action
.Ar arg1 ... argN
.Sh DESCRIPTION
.Nm
is a tool to manage the
.Em alternatives system
provided by The NetBSD 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
.Sq 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
.Em package
they belong to.
In other words, a concrete package contains a list of all the wrappers it
affects by providing alternatives to them.
This makes things easier to the end user and/or the administrator who has
to deal with them, as they can manually select a package rather than a
bunch of wrappers.
.Pp
Wrappers are identified by its file name 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
.Sq 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
.Sq wrapper
word with the wrapper's absolute file name):
.Bl -tag -width XXXX
.It ~/.alternatives/wrapper
This is called the
.Em user configuration file
and is only read when not running as
.Sq @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
.Sq manual
action described below.
.It @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
.Sq manual
action described below.
.It @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 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 wrappers rather than on packages.
This affects the behavior of all actions.
.El
.Ss Actions in package mode
The following table describes each available action and its behavior when
working in package 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 the command.
.Bl -tag -width XXXX
.It auto Ar package
Removes any manual configuration from each wrapper associated to the given
package.
This means that all the affected wrappers are then free to choose whichever
alternative they prefer.
.It 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 list
Lists which of the installed packages provide alternatives.
Any of the packages shown by this command can then be fed back to the
.Sq auto
and
.Sq manual
actions.
.It manual Ar package
Manually selects all the alternatives that belong to
.Ar package
to be the default for their respective wrappers.
.It 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
.Sq 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 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 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 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 package mode.
.Bl -tag -width XXXX
.It auto Ar wrapper
Removes any manual configuration created for the given
.Ar wrapper .
That is, if running as
.Sq @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 manual Ar wrapper alternative arguments
Manually selects the
.Ar alternative
for the given
.Ar wrapper .
If running as
.Sq @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 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 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 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
.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 @DATADIR@/
System-wide configuration database.
.El
.Sh DIAGNOSTICS
.Nm
exists 0 on success and 1 if an error occurred.
.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 jmmv@NetBSD.org