PKG_ALTERNATIVES(8)

NAME
pkg_alternatives - generic wrappers for programs with similar interfaces

SYNOPSIS
pkg_alternatives [-gsw] [-p prefix] action arg1 ... argN

DESCRIPTION
pkg_alternatives is a tool to manage the 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.

Consider, for example, the vi(1) editor. Both nvi(1) and vim(1) provide very similar functionality, although neither of them is named vi. In this situation, it may be useful to have a wrapper in place of the generic name which points to one of the multiple alternatives available.

The alternatives are classified according to the package they belong to, forming 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.

Wrappers are identified by their filename relative to the installation prefix, i.e., /opt/local if the -p option is not used. In the example above, the wrapper could be identified by the bin/vi string. The identifier is the string used as the “wrapper” argument in all the actions that require it.

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 ‘#’ are considered comments and are ignored.

The following configuration files are read, in strict order, for each wrapper (replace the “wrapper” word with the wrapper's absolute file name):

~/.pkg_alternatives/wrapper
    This is called the user configuration file and is only read when not running as “root”. Otherwise, tools such as 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 manual action described below.

/opt/local/etc/pkg_alternatives/wrapper
    This is called the system configuration file and is read if found. This file can be freely edited by the administrator, either by hand or by using the manual action described below.

/opt/local/share/pkg_alternatives/wrapper
    This is called the 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.

  Options
The following options are available:

-g  Operate on groups of wrappers rather than individual files. This is the opposite of -w and is currently the default behavior. Affects the behavior of all actions.

-p prefix
    Set installation prefix. This affects where wrappers and their manual pages are looked for. The prefix defaults to /opt/local if this flag is not given.

-s  Run in silent mode: no output except for errors.

-w  Operate on individual wrappers rather than on groups. This is the opposite of -g. Affects the behavior of all actions.

  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.

auto 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.

destroy
    Removes the alternative database, found in /opt/local/libdata/pkg_alternatives, and all its associated wrappers and manual pages. This action is intended to be used by the pkg_alternatives package.

list
    Lists which of the installed packages provide alternatives. Any of the packages shown by this command can then be fed back to the auto and manual actions.

manual package
    Manually selects all the alternatives that belong to package to be the default for their respective wrappers.

rebuild
    Rebuilds the alternatives database, found in /opt/local/libdata/pkg_alternatives, based on the contents of the package database, usually available in /opt/local/pkg. Basically, it scans the later looking for packages with an +ALTERNATIVES file in them, and, for each of those, the register action is called with the appropriate file name. This action is intended to be used by the pkg_alternatives package or in case of database corruption.

register package wrapper alternative arguments
    Registers a new alternative for the given wrapper in the specified package. If the package does not exist in the database, it is created.

    This action must not be used directly; packages providing alternatives will take care to execute it at installation time.

status package
    For each wrapper that belongs to package, shows which alternative will be used by it in the next run. It also displays all available candidates for each of them.

unregister package
    Removes the package from the database. All alternatives associated to it are also removed.

    This action must not be used directly; packages providing alternatives will take care to execute it at deinstallation time.

  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.

auto wrapper
    Removes any manual configuration created for the given wrapper. That is, if running as “root”, 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.

manual wrapper alternative arguments
    Manually selects the alternative for the given wrapper. If running as “root”, 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.

register wrapper alternative arguments
    Registers a new alternative for the given wrapper. If the wrapper did not exist before, it is created. You may optionally pass several arguments to the alternative program.

    This action should not be used directly; packages providing alternatives will take care to execute it at installation time.

status wrapper
    Shows which alternative will be used by the wrapper in the next run. It also displays all available candidates for it.

unregister wrapper alternative
    Removes the alternative from the given wrapper. If there are no more alternatives available, the wrapper is removed.

    This action should not be used directly; packages providing alternatives will take care to execute it at deinstallation time.

  Filtering wrappers
pkg_alternatives 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 /opt/local/etc/pkg_alternatives/filter.conf file.

A filter is composed of multiple entries. Each entry contains an action and a regular expression, separated by a single space. The action can be either “accept” or “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.

Please note that, after modifying the filter configuration file, the wrappers database must be rebuilt using the “rebuild” action. Otherwise your changes will take no effect.

ENVIRONMENT

PKG_DBDIR
    Location of the package database directory. Defaults to /opt/local/pkg.

FILES

~/.pkg_alternatives/
    User-specific configuration directory.

/opt/local/etc/pkg_alternatives/
    System-wide configuration directory.

/opt/local/etc/pkg_alternatives/filter.conf
    Wrapper filter.

/opt/local/share/pkg_alternatives/
    System-wide configuration database.

DIAGNOSTICS
pkg_alternatives exists 0 on success and 1 if an error occurred.

EXAMPLES

  Managing wrapper groups
The following command tells all Vim related wrappers (which include ex(1), vi(1) and view(1)) to always prefer Vim in favour of any other program:

    # pkg_alternatives manual vim

And the following command reverts the previous change, configuring the affected wrappers to use whichever alternative is available:

    # pkg_alternatives auto vim

  Managing individual wrappers
Suppose that you want to use Sun's Java 1.5 by default for all Java-related wrappers, except for 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:

    # pkg_alternatives manual sun-jre15
    # pkg_alternatives manual sun-jdk15
    # pkg_alternatives -w manual bin/appletviewer \
      /usr/pkg/bin/kaffe-appletviewer

  Applying filters
Let us consider a very typical situation: you have just installed a Python interpreter and you want the 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 /opt/local/etc/pkg_alternatives/filter.conf to achieve this:

    accept ^bin/python$
    ignore .*

Don't forget to run the following command after doing the above changes:

    # pkg_alternatives rebuild

SEE ALSO
pkg_add(1), pkg_delete(1)

HISTORY
The pkg_alternatives utility first appeared in pkgsrc-2005Q1.

This utility was inspired by the alternatives system found in the Debian operating system.

AUTHORS
Julio M. Merino Vidal <jmmv@NetBSD.org>