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:

• ApVSys is general wrapper for any tool.

• It is a way to get a clear and standard environment without interaction between tools and also between versions of tools.

• It is a way to get an access to every installed tool with only ONE PATH !

• ApVSys is not a tool itself but it is a tools organizer which provides easy access to every tool and a safe way for the user to select the version of the tool(if different from the default).

• ApVSys gets automatically the version corresponding to the operating system.

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.

• reduce the support requirements

• centralize the setup of the tools

• provide an easy access to every tool

• provide an easy way to select the version of the tools.

Furthermore ApVSys provides other features as:

• Synchronization between documentation ( info, manpages, ... ) and the executed version of a command.

• automatic O.S. version selection

• automatic update of LD_LIBRARY_PATH (SHLIB_PATH) to point first to the libraries of the executed version of a tool.

• possibility to easily define tool dependencies.

• A three level system administration

  • System admin ( ROOT ) as usual.

  • ApVSys admin : This administrator, has the responsibility of the ApVSys database. It does not have to be root ( it's even better to avoid this for security reasons ). Because ApVSys can be used locally, it can be a "normal" user too. The normal and the best situation is to make a dedicated "ApVSys" username.

  • Normal user

2. What does this release contain ?

This release contains all you need to start with ApVSys:

• the installation script

• the C code of the system

• some perl scripts

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 ?

• gcc must be in your path ( version 2.7 to 8.3.0 are successfully tested ).

• perl must be in your path ( version must be >= 5.0 )

3.2. Installation ( max 5 min. )

3.3. Update ( max 1 min. )

• To update apvsys to the new version, the installation script must be used. It should detect all the previous parameters and reuse them. If some changes have to be done, the option -f MUST be used.

• To update the apvsys parameters (with the same version), the installation script must be used with the option -f to force the new parameters.

• To change the version of ApVSys,the installation script of the selected version must be used.

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:

• The tool is already installed in the standard place in the ApVSys hierarchy and already has the directories bin, lib, man and info on its root: You are happy, nothing special has to be done.

• The tool is installed elsewhere or doesn't have the bin, man, lib or info directories on its root. In this case symbolic links have to be created to emulate the situation expected by ApVSys.

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.

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 ;-)

5.2. How to select another version in ApVSys ?

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

• Parse the APVSYS_TOOLSPEC variable. This feature was added for debug reasons and it is strongly recommended to AVOID using this way to configure the version you want.

  Example:

   setenv APVSYS_TOOLSPEC "apvsys/v1.0:gcc/v8.2.0"

• Parse the files pointed by the APVSYS_TOOLSPEC_FILES variable. Extremely useful to configure the tool versions used for an individual project.

  Example:

   setenv APVSYS_TOOLSPEC_FILES /myproject/tool-spec:./tmptoolspec:$HOME/tool-spec

  The syntax of each file is simple: one line per tool "tool/version"

  Example of tool-spec file:

   gcc/v8.2.0
   apvsys/v1.15

• If APVSYS_TOOLSPEC_FILES does not exist, parse the file ./tool-spec and $HOME/tool-spec.

  The first entry matching a tool containing the command you have typed will define the version.

  IMPORTANT NOTE: It is important to understand that, in the line "gcc/v8.2.0", "gcc" is the name of the tool and not the name of the command. Every related command ( c++, c++filt, chill, cpp, g++, g77, gcc, gcj, gcjh, gcov, ... ) will also be controlled by this line !

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.

5.4. Other special variable ?

Since version v1.15, the behaviour, in case of command exists in a version of a tool but does not exists in the version selected by the toolspec, apvsys will continue to parse the toolspec and any command but will warn the user about the fact that the command version could be different than the expected one.

It is possible to disable this warning by setting the APVSYS_NO_VERSION_MISMATCH_WARNING environment variable.

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

• apv ( = version ) : This is the most important command because it provides all the information related to the ApVSys database like "The available versions of a tool", "The version executed for a tool and the rule to select this version", "The environment set for a tool", "The toolspec parsed to select the version", "the root directory of a tool", "commands related to a tool", and it also provides a way to make some actions like "setting the environment of a tool and starting a shell",... PLEASE, take the time to read all the options in the apv documentation.

• apv-xcheck : this command, also accessible via apv -c, checks the collisions between tools specified in the tool-spec. It detects when different tools specified in the toolspec contain commands with the same name.

• apv-lib : this command was done to facilitate the usage of ./configure scripts. It expands the library names to the full path (including the version and the suffix /lib or /include).

The administation commands

• apv-linktool : This is an optional command to prepare a tool to be registered by creating symbolic links in the ApVSys directory structure.

• apv-regtool : The most important admin command. This is the command to use to register (and unregister) a tool in the database (see above). PLEASE take the time to read the apv-regtool manpage.

• apv-setdefault : This command will change the default version of a specific tool.

• apv-dbcheck : This has to be used when some tools were removed before their unregitration. This script parses the database and removes the obsolete information.

• apv-osmirror : This command can be used when 2 O.S. are really close to each other and some tools, registered on an O.S. have also to be registered for another one. It is extremely interesting when a new minor version of an O.S. is installed and you want to mirror the installed base.

• apv-nativeoscheck : This script will automatically check if some commands registered in the apvsys database are also native commands of the operating system. The default version chosen for these commands must, of course, always be the O.S. native version (somebody using the system but who didn't specify any particular version expects to use the command of the operating system!).

• apv-envCompile : this script can be used to compile properly an ap-environment.c file to produce the ap-environment.so.

SEE ALSO