Difference between revisions of "HOWTO use the Hall-D environment setup facility"

Revision as of 14:23, 9 December 2013

Introduction

A centralized facility for modifying an existing c-shell environment to use alternative software packages has been installed and is being maintained on the Hall-D gluon cluster. The primary use would be to allow a new version of a software package to be installed and used without having to change the existing default. For example, if a new version of EPICS came out that we wished to build and test on the gluon cluster, this could be done and a setup script added to allow developers to simply type "setup epics3.14XXX" to set their environment properly to use it. Having the setup scripts in a central location makes it easy for developers to find alternate or test packages someone else has installed. It also should make it easy to switch an environment back and forth between two versions of a package while developing and testing software for online systems.

Using the setup facility

The setup facility is accessed by sourcing the file setup_init.csh. This is done in the /gluex/etc/hdonline.csh file which is automatically sourced from both the hdops and hdsys login scripts. Thus, for most cases, the setup alias is already in your PATH. If it is not, then simply do the following while on one of the gluon machines:

> source /gluex/etc/setups/setup_init.csh

A usage statement along with a list of available packages can be obtained by running setup with no arguments:

> setup

Hall-D environment setup facility

Usage:

   setup <package>

  The setup command is an alias that will attempt to
source a setup script specified by <package> in the
/gluex/etc/setups/csh directory. If no file exists with
the specified package name, this usage statement is 
printed. (This usage statement is also printed if no
<package> argument is given.) The list of available
package setup scripts is given below. The alias is
defined in /gluex/etc/hdonline.cshrc

gcc4_4_7  gcc4_8_0  USAGE

As indicated in the usage statement, the setup alias will simply source a specific file in the directory /gluex/etc/setups/csh. So, to use the 4.8.0 compiler for example, one simply needs to issue this:

> setup gcc4_8_0

To switch back to the gcc4.4.7 compiler, one would do this:

> setup gcc4_4_7

filter_path

Another feature of the setup facility is that it provides a path filtering alias/script that will remove duplicate entries in any PATH-like environment variable (the PATH and LD_LIBRARY_PATH being the main ones). This is useful in keeping these variables from growing if one switches back and forth repeatedly between two versions of a package. It is expected that the filter_path command will be used primarily at the end of the setup scripts themselves. However, one can use it on its own. Just pass it the name of the variable you want it to compact:

> filter_path PATH

If you wish to remove a specific path or paths from the variable, give them as additional arguments to the command:

> filter_path PATH /usr/local/xerces_test/bin

Adding a setup script

To add a new package, simply add a c-shell script file to the directory /gluex/etc/setups/csh. Note that this directory is linked to the repository so if you add a file, you should also do an svn add and svn commit on it in order to copy it into the repository. Look at existing setup scripts for examples.

Advanced

Here, I just explain some of the details of the system in case anyone is interested. If you are just using the system, then you don't need to read this.

The big trick of this setup facility is to use an alias to source the setup script so that it modifies the calling shell's environment. Otherwise, the caller would have to source the setup script directly therefore, requiring that they know where it lives. This could be done with an environment variable to make it easier to remember, but it would still lead to a command such as this:

> source $SETUP_SCRIPTS/gcc4_4_7

as opposed to

> setup gcc4_4_7

Note that the first command actually *will* work because the environment variable "SETUP_SCRIPTS" is set and used by the facility. However, users would have to remember the name of this variable when typing the slightly longer first command.

This system also allows one to see what scripts are there by just typing "setup" instead of something like "ls $SETUP_SCRIPTS". Again, there is no need to remember the environment variable.

The filter_path tool uses similar alias trickery to modify a PATH environment variable of the calling shell. This is to keep the PATH variables more compact in case one wishes to repeatedly call setup. For example, if they were testing with two different versions of a software package and constantly flipping back and forth. The filter_path alias actually uses a Python script at ${SETUP_SCRIPTS}/../filter_path to do the heavy lifting. The alias is there so that the caller's environment can be modified (as opposed to a copy of it if this were done as a straight script.)