Program Version Switch (pvswitch) installation guide
===================================================

Building and installing
-----------------------

The well known installation procedure is

	./configure
	make
	make install

Of course you can add configure options as wanted. Very common would be

	./configure --sysconfdir=/etc

To install the configuration file in /etc instead of /usr/local/etc.

After installation as described here you will need to configure pvswitch
so that it actually manages the program you want to switch.

Configuring a program to be controlled by pvswitch
---------------------------------------------------

The distribution includes a script called pvconfig which can be used to 
initially configure a program to be managed by pvswitch.

	./pvconfig  []

If you want to manage for example perl you would call (as root)

	./pvconfig perl

If the perl version you have currently installed is 5.8.1 use
 
    ./pvconfig perl 5.8.1

to tell pvswitch that the version currently reachable via PATH
is 5.8.1 (if the key is not specified the string 'default' will
be used).  

The script will perform the following tasks:
	
1.	make an entry for program (version: either the specified key or 
    default) to the pvswitch configuration file. The default version 
    will be called program.pvswitch in the directory where program 
    is installed.  The next step will place program there.
2.	rename the program binary (in that case perl) to program.pvswitch
	(perl.pvswitch for example).
3.	make a symlink from the original location where the program was found
	to pvswitch so that pvswitch is executed instead of the program.
4.	make a second symlink so that programver (program name suffixed by ver)
	links to pvswitch as well (e.g. if you call perlver you will actually
	call pvswitch).
5.	create a wrapper script pvwrap.program (e.g. pvwrap.perl) which
	can be sourced to set the environment variable PVSWITCH_program_VERSION
	so that you can change the used program version in a convenient manner.
6.	Ask you to add two lines into the global profile so that each user
	has the alias to configure the program version (e.g. perlver) in the same
	shell (sources the wrapper script).

Not all of this tasks are mandatory, but it is the suggested way to use pvswitch.

Checking the configuration and making a fist test
--------------------------------------------------

If you call pvswitch directly (not through one of the symlinks), 
pvswitch will read and check its configuration and report possible errors.

So just try:
	pvswitch

to check the configuration. On success you should get this line

pvswitch: config /usr/local/etc/pvswitch.conf OK

followed by the copyright notice.

If this succeeds try to run the managed program (in this example perl) and see 
which version you get:

	perl --version

This should be the version which was previously installed as default.

If you have already set the alias suggested by pvconfig (e.g. relogin) you 
should be able select the version (in this example perl):

	perlver

This should display you the list of installed perl version (at this stage only 
one) and wait for an input. You can now select the perl version by entering
the version (the default pvconfig setup will call the version 'default').

Alternatively you can pass the version you want to use as argument:

	perlver default

You should still be able to call perl

	perl --version

and get the default version.


Configuring another program version for a pvswitch controlled program
----------------------------------------------------------------------

After you have installed another version of the program somewhere you will
just need to add an additional entry to the pvswitch.conf file.

See the pvswitch.conf(5) manpage for details.

Controlling more programs with one setting
------------------------------------------

Sometimes it is required to switch not only the version of one single program,
but a set of programs. Most prominent example is GCC where you most likley
want to switch several programs (gcc, gpp, c++, ...) with one setting. This
can be accomplished by setting the envname for multiple programs to the same string:

Consider this pvswitch.conf example:

gcc|gcc 3.4.0
cpp|gcc 3.4.0
c++|gcc 3.4.0

This example configures three binaries (gcc, cpp and c++) which will all be switched
by the PVSWITCH_GCC_VERSION environment variable. This means if you change to
the version of gcc beeing used, you will automatically change the version for c++ as well.
Have a look into the pvswitch.conf(5) manpage for details.