ApVSys : Application Versioning System

      Copyright (C) 2002 Arnaud BERTRAND
      web-site: http://www.apvsys.org

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License. ( see LICENSE.TXT file )

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Contact the author: e-mail: info@apvsys.org


TABLE OF CONTENTS

  1. What is ApVSys ?

  2. What does this release contain ?

  3. How to install/update ApVSys ?
    1. What is needed to use/install ApVSys ?

    2. Installation

    3. Update

  4. How to manage it as ApVSys administrator ?
    1. How to prepare a tool to be registered ?

    2. How to register a new tool ?

    3. How to write an ap-environment file ?

    4. How to configure the documentation ?

  5. How to use it ?
    1. How to setup ApVSys ?

    2. How to select another version in ApVSys ?

    3. How to debug the environment in ApVSys ?

    4. Other related scripts/commands

    5. Revision history


1. What is ApVSys ?

The answer of this question is probably the most difficult point I had for ApVSys ! So, let's try to answer:

For a lot of good reasons, it is often necessary to keep simultaneously different versions of the same tool on a system. This is typically the case in an EDA environment (where ApVSys is born).

Who never dreamt of changing the gcc version just by changing a
small flag/file ?

Who never dreamt of a system where the installation of every application is fully separated. ?

Who never dreamt of a system that provides a default version for every tool without any user settings ?

Who never dreamt of installing a new version of a tool without any risk of crashing the previous version ?

Unfortunately, there is (was) currently no system to manage such an environment. ApVSys is the answer to that problem. A packaging system is also foreseen in the near future.

ApVSys is born from some important requirements in a EDA environment.

Furthermore ApVSys provides other features as:


2. What does this release contain ?

This release contains all you need to start with ApVSys:

A nice perl package is also provided with this release: Getopt::Mixed 1.008 - Copyright 1995 Christopher J. Madsen Only the Getopt/Mixed.pm is provided in ApVSys distribution and is installed locally. You can download the latest full version of this package on: http://cpan.valueclick.com/authors/id/C/CJ/CJM to integrate it properly in your perl installation.


3. How to install ApVSys ?

3.1. What do you need to install ApVSys ?

3.2. Installation ( max 5 min. )

3.3. Update ( max 1 min. )


4. How to manage it as administrator ?

The registration of a new tool is necessary to make it available. The standard location of a tool in the ApVSys hierarchy is: $APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion where OsName is the output of uname -s and OsVersion is the output of uname -r ( please note the ``v'' before OsVersion )

4.1. How to prepare a tool to be registered ?

ApVSys is based on a the fact that every tool has roughly the same structure on its root directory: it has at least a bin directory and optionally a man, lib and info directories.

To get ApVSys running, these directories (bin, lib, man and info have to be in the root of the installation directory of each tool.

In other words, the installation must respect the following structure:

 APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion/bin
 APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion/man
 APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion/info
 APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion/lib

There are 2 possibilities:

So, in the last situation, some additional operations are required: You can performs these operations by using the provided script: apv-linktool which will do everything for you ;-). Here are the operations (if you want to do it manually):

1. Creation of the tool directories in the ApVSys hierarchy:


 > mkdirhier  $APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion
 > mkdir  $APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion/bin
 > mkdir  $APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion/lib

2. Linking of the installation directory to the ApVSys hierarchy

 > cd  APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion
 > ln -s $TOOL_INSTALL_DIR/* .
 > ln -s $TOOL_INSTALL_DIR/.* .

3. Linking the binaries and the libraries in the ApVSys hierarchy:

 > ln -s $TOOL_INSTALL_DIR/bin/* bin
 > ln -s $TOOL_INSTALL_DIR/lib/* lib

4. Optionally, if other bin or lib directories are present in the tool hierarchy, these directories can be combined.

e.g.

 > ln -s $TOOL_INSTALL_DIR/sunos5/bin/* bin 
 > ln -s $TOOL_INSTALL_DIR/sunos5/lib/* lib

Note: each binary/library is linked individually in the bin/lib directory. This is of course NOT mandatory ( you can proceed like for the other directories, by linking directly the bin directory instead of bin/* ) but it gives the possibility to combine multiple bin/lib directories.

4.2. How to register a new tool ?

When the structure is prepared, the registration is done with apv-regtool command. Typically:

 > apv-regtool -t ToolName -v Version -L YourRealUserName

Please try apv-regtool -h to see the options of <apv-regtool>.

4.3 How to write an ap-environment file ?

The ap-environment file is OPTIONAL and allows you to set some variables or to tune the environment before the execution of any command registered for a tool. This file must be placed in the root of the tool: $APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion/ap-environment.pl

Typically, you can reference the license file, set some variables needed to start the tool, ...

You can even load another tool environment ( in case of dependent tools )

This ap-environment can be written in C, perl, sh, csh, bash, tcsh or ksh

Here is an example:

 FILE ap-environment.pl

 &loadenv("mychildtool", "v1.0") 
 $ENV{MYTOOL_ROOT}="/ap/mytool";
 $ENV{PATH}="/ap/mytool/binpath/which/cant/be/moved:" . $ENV{PATH};
 $ENV{LM_LICENSE_FILE}="1717\@mylicensehost";

Please, note that the extension is REALLY IMPORTANT and the accepted extensions are .so, .pl, .sh, .csh, .bash, .tcsh, .ksh.

For more details, you can read the ap-environment documentation

4.4 How to configure the documentation ?

ApVSys provides the possibility to configure the documentation to give a standard way to the user to start the documentation of any tool (with the command apv -d cmd). The command apv will detect the version and will start the perl script: ap-docstart.pl. This file is, of course optional and must be placed in the root of the tool: $APVSYS_ROOT/OsName/vOsVersion/ToolName/vToolVersion/ap-docstart.pl for example: /ap/apvroot/SunOS/v5.8/ncsim/v3.4/ap-docstart.pl.


5. How to use it ?

5.1. How to setup ApVSys ?


It should take 1 minute maximum ;-)

First of all, you have to know if the ApVSys administrator has created the ``O.S. independent'' link ( see the last point of Installation section).

If this is the case, life is beautiful, just modify your startup script (.cshrc, .profile or ...): to set /apv/bin as the first element of your PATH variable.

Otherwise, life is also beautiful, but just a little more difficult. You have to modify the startup script ( .cshrc, .profile or ...) to set $APVSYS_ROOT/`uname -s`/v`uname -r`/etc/links/bin as the first element of your PATH variable. Note that you can also create your own apv link e.g. /tmp/apv to have your ``O.S. independent link'' and put /tmp/apv/bin in the head of your PATH.

Now you can check if it is working by trying the command ``apv -a apv''. You can also try ``apv -V'' to see all the tools/versions available in your environment. ( not so many if you have just installed ApVSys ;-) ).

Note that without doing anything else, you have access to the default version of every tool. You can list these versions with ``apv -D''. You can also execute ``apv --help'' to see the options of the apv command.

5.2. How to select another version in ApVSys ?

To select the tool version to start, ApVSys uses a simple decision rule:

5.3. How to debug the environment in ApVSys ?

It is sometimes necessary to debug the environment. To try to understand what's happening, apvsys provides a debug mode. The debug mode will print some debug messages giving the status of the current operation.

To switch to debug mode, you just have to set the variable APVSYS_DEBUG to 1. When you run a command you will get this kind of output: (some comments are placed between '{}' )

 # APVSYS-DEBUG: Wrapper called
 # APVSYS-DEBUG: apvexpl -ls    { the command received by the wrapper }
 # APVSYS-DEBUG: found version: apv-example/vc [ apv-example/vc in APVSYS_TOOLSPEC ]
 # APVSYS-DEBUG: loading /ap/apvroot/Linux/v2.4.18-6mdk/apv-example/vc/ap-environment.so
 --- C environment setting ---
 --- END C environment setting ---
 # APVSYS-DEBUG: Before exec     { status of PATH & LD_LIBRARY_PATH before the execution }
 # APVSYS-DEBUG: PATH = /ap/apvroot/Linux/v2.4.18-6mdk/apv-example/vc/bin:.:/home/arn/util:/apv/bin:/bin:/usr/bin:/usr/ucb:/usr/sbin:/usr/X11R6/bin:/usr/dt/bin:/usr/ccs/bin
 # APVSYS-DEBUG: LD_LIBRARY_PATH = /ap/apvroot/Linux/v2.4.18-6mdk/apv-example/vc/lib:/usr/lib:/usr/X11R6/lib:/ap/X11R4/sun4/usr/lib:/ap/tools/lib
 # APVSYS-DEBUG: APVSYS_ENV_apv_example = vc
 # APVSYS-DEBUG: exec apvexpl apvexpl    { argument passed to exec }

This mode only prints some information on stderror but does not modify the execution of the command.

There is another possibility: by setting APVSYS_DEBUG to shell, everything is done BUT instead of launching the command, a shell ( sh ) is started.


6. Other related scripts/commands:

Some others scripts/commands are also available to administrate and use ApVSys.

Here is a short description of all these subcommands. Please, read the dedicated documentation for more details.

The end-user commands

The administation commands


SEE ALSO

apvsys-intro(1) ap-environment(1) apv(1) apv-linktool(1) apv-regtool(1) apv-setdefault(1) apv-osmirror(1) apv-nativeoscheck(1) apv-dbcheck(1) apv-lib(1) apv-xcheck(1)


Revision history

The latest revision: 2004-01-02 : Version 1.12a: bug #868448 is now solved. apv command is now compatible with strict mode of perl 5.8

2003-09-21 : Version 1.12: A feature is added. There is now the possibility to prefix commands by setting the APVSYS_PREFIXCMD variable. This variable can only be set *IN an ap-environment file*.

For details about previous revisions, please read the file CHANGELOG


Thanks:

 - Thanks to Walter Doyle to have reviewed the documentation.
 - Thanks to Alcatel and Thomson to use the system.