Alternatives system.
~~~~~~~~~~~~~~~~~~~~

What is it?
~~~~~~~~~~~
Best description you can find is in manual page of Debian's update-alternatives package
"
It  is  possible  for  several  programs fulfilling the same or similar
functions to be installed on a single system at  the  same  time.   For
example,  many  systems  have  several  text editors installed at once.
This gives choice to the users of a system, allowing each to use a 
different editor, if desired, but makes it difficult for a program to make
a good choice of editor to invoke if the user has not specified a  particular
preference.

The  alternatives system aims to solve this problem.  A generic name in
the filesystem is shared by all files providing  interchangeable  functionality.
The  alternatives  system  and  the  system  administrator together determine 
which actual file  is  referenced  by  this  generic name.
For  example,  if  the  text  editors ed(1) and nvi(1) are both installed on the system,
the alternatives system will cause the generic name /usr/bin/editor to refer to 
/usr/bin/nvi by default.  The system administrator can override this 
and cause it to  refer  to  /usr/bin/ed instead, and the alternatives system 
will not alter this setting until explicitly requested to do so.
...
It  is often useful for a number of alternatives to be synchronised, so that 
they are changed as a group; for example, when several versions of the   vi(1)
editor   are   installed,  the  man  page  referenced  by /usr/share/man/man1/vi.1
should correspond to the executable referenced by  /usr/bin/vi.
update-alternatives  handles this by means of master and slave links;
when the master is changed, any associated slaves  are changed  too.
A  master link and its associated slaves make up a link group.

Each link group is, at any given time, in one of two  modes:  automatic or  manual.
When a group is in automatic mode, the alternatives system will automatically decide,
as  packages  are  installed  and  removed, whether  and how to update the links.
In manual mode, the alternatives system will not change the links;
it will leave all  the  decisions  to the system administrator.
"

What is the ALT Linux alternatives?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Original Debian alternatives implementation has some limitations and problems, so
we (ALT Linux Team) rewrite this subsystem. What changes we have made?

At first, you don't need to give special generic name for altenatives file. This name is
 autogenerated now.

At second, this version is written in shell, awk and sed , so we reduce a number of dependencies,
therefore,  number of the packages in basesystem.

At third, we use different update model. Original alternatives system maintains its own database, by 
creating/removing files in system. 
In our alternatives (rpm) packages contains it's configs and places them 
into generic directory during package installation.
After package removal its config is automatically removed. It works like
Debian menu subsystem, and it's more stable.

New feature: now we have not any limitations for master-slave hieracly depth.
New alternatives system works with no groups, but with each item. You can turn into 
manual mode any available item. There are only one difference between master and slave:
weight calculation algorithm. Slave alternative have same weight as a master alternative.

Another useful improvements: alternatives-update script corrects invalid manual 
alternatives, by switching them into auto mode. In original alternatives was situations 
with broken symlinks. Also new system doesn't create symlinks if 
target file does not exist. As a result, we also reduce number of broken symlinks.

Alternatives architecture
~~~~~~~~~~~~~~~~~~~~~~~~~
* general engine:
alternatives-auto - turn into auto mode some alternatives item
alternatives-manual - turn into manual mode some alternatives item
alternatives-update - update current state of alternatives symlinks

* special scripts for the packages:
alternatives-install - register new alternatives config, for use in %post package script
alternatives-uninstall - unregister some alternatives config, for use in %preun package script

* ALT Linux specific:
alternatives-helper - helper script to use in package scripts
alternatives-upgrade - tool to upgrade from old config format (XML based) to new.

* directories:
/usr/bin - all scripts live here
/etc/alternatives/packages.d - all package configs
/etc/alternatives/auto - symlinks to registered configs
/etc/alternatives/manual - list of alternatives in manual mode
/etc/alternatives/links - for internal use only, alternatives symlinks lives here
/usr/share/alternatives - directory with some helper functions and scripts

Config file format
~~~~~~~~~~~~~~~~~~
Format is very simple. There are three tab separated fields.
<generic	name>	<candidate's name> <weight or name of the master>
Example config for master alternative /usr/bin/links with slave 
alternatives /usr/share/man/man1/links.1.gz
---------
/usr/bin/links  /usr/bin/links1 10
/usr/share/man/man1/links.1.gz  /usr/share/man/man1/links1.1.gz /usr/bin/links1
---------

Sample rpm package with alternatives support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is a package variant with alternative /usr/bin/variant. 
All rpm macros I use in this spec you can find in alternatives.spec.

--------variant.spec-------
Name: variant1
Version: 1.0
Release: alt1

Summary: alternatives test file
License: GPL
Group: System/Base
BuildArch: noarch

PreReq: alternatives

%description
alternatives test file #1

%install
install -d $RPM_BUILD_ROOT/%_bindir

cat>$RPM_BUILD_ROOT/%_bindir/%name<<EOF
#!/bin/sh
echo "variant 1"
EOF
chmod 755 $RPM_BUILD_ROOT/%_bindir/%name

install -d $RPM_BUILD_ROOT/%_altdir

cat >$RPM_BUILD_ROOT/%_altdir/%name<<EOF
%_bindir/variant	%_bindir/%name	10
EOF

%post
%register_alternatives %name

%preun
%unregister_alternatives %name

%files
%_bindir/*
%_altdir/*
---------------------------

Building and installing
~~~~~~~~~~~~~~~~~~~~~~~

To build this package you need only extra help2man utility to generate manual pages for utilites

Just run "make install" to install alternatives to your system.

Authors
~~~~~~~~
Stanislav Ievlev <inger@altlinux.ru>
with big help from:
	Fr. Br. George <george@altlinux.ru>
	Alexey Voinov <voins@altlinux.ru>
	Kid Pogi <kidpogi@spymac.com>
	Jeff Pitman <symbiont@berlios.de>
	Ivan Zakharyaschev <imz@altlinux.ru>
	etc.

Bug reporting
~~~~~~~~~~~~~
Please report all bugs you find in the program directly to authors.
