6 Setting Up the Shell Environment

Facility is provided for setting environment variables necessary both for building the software and for using it. Both Bourne-shell-like and C-shell-like shells are supported, but real testing has only been done with bash and tcsh. In the following all examples will be appropriate for bash. Note that whenever a script like is mentioned, there is also a foo.csh in the build-scripts directory.

6.1 Low-Level Environment Set-Up: gluex_env.(c)sh

The gluex_env.(c)sh script will define all environment variables needed to run and build GlueX software. It takes as input the home directories of each package as found in the environment variables listed in Table [*].

Table: Packages and their home directories.
Package Home Directory Variable
sim-recon SIM_RECON_HOME
Geant4 G4ROOT
hd_utilities HD_UTILITIES_HOME
gluex_root_analysis ROOT_ANALYSIS_HOME
halld_sim HALLD_SIM_HOME
halld_recon HALLD_RECON_HOME

Given the home directory of a package, there may or may not be other environment variables that need to be set, those variables derived from the value of home. gluex_env.(c)sh takes care of this. For example, XERCES_INCLUDE is used in the build system and must be defined as $XERCESCROOT/include. Directories containing binaries must be added to the PATH variable and similarly for LD_LIBRARY_PATH, and PYTHONPATH. For these path variables directories are always added at the front with any pre-existing directories maintained on the list.

6.1.1 Pre-Defined Home Variables and Defaults

If GLUEX_TOP is defined in advance, the pre-defined value will be used. If not it will be defined as /usr/local/gluex.

If BUILD_SCRIPTS is defined in advance, again the pre-defined value will be used. If not defined it will be defined as $GLUEX_TOP/build_scripts.

If any of the home directories are defined before sourcing gluex_env.(c)sh, those values will be respected. If any are not defined, then a default will be provided, usually the prod directory in the package container directory. Because of this behavior, the user can define as many or as few of the home directories as desired in advance of sourcing gluex_env.(c)sh, letting the script finish the environment settings keying off of the user definitions (or lack thereof). The user is thus only responsible for setting the values of desired home directories. A side effect of this behavior is that the environment that results is non-deterministic in the sense that the result depend on the values of pre-existing home directory variables. Different initial conditions will give different environments.

6.1.2 Consistency Checking

The final step in gluex_env.(c)sh is to check the resulting environment for consistency using the prerequisites system. Each home directory is checked for a prerequisites version set file. Those files list versions of prerequisite packages used at build time. The build-time version are checked against the versions used in the just-set-up environment and warnings are printed when mismatches are detected. See Section [*] for the details.

6.1.3 Cleaning the Environment: gluex_env_clean.(c)sh

Since gluex_env.(c)sh is sensitive to definitions hanging around in the environment, there is a script provided that will undo all GlueX-related definitions:
gluex_env_clean.(c)sh. Sourcing it will eliminate unintended consequences from previously made definitions. For the path variables the script only removes the GlueX-related elements leaving all others present in the path.

6.2 High-Level Environment Set-Up

6.2.1 Custom Scripts

The most common reason to have a custom script is when you want to use a package that is outside the standard directory structure. Since gluex_env.(c)sh will respect a pre-defined value of any of the home directories, this can be done without making a private version of gluex_env.(c)sh. See Fig. [*] for an example. Here a version of sim-recon built in a non-standard location (the user's home directory) will be used in the resulting environment.

Figure: Example of a custom set-up script. The build of sim-recon in the user's home directory will be used. All other packages be set up to use with their default builds under /home/gluex/gluex_top. Note that GLUEX_TOP and BUILD_SCRIPTS are defined explicitly rather than letting them default.
\begin{figure}\begin{verbatim}export GLUEX_TOP=/home/gluex/gluex_top
export ...
source $BUILD_SCRIPTS/\end{verbatim}

6.2.2 Using the Versioning System

Another way to get a non-default environment is to use the versioning system to set home directory locations which in turn are respected by gluex_env.(c)sh. The versioning system is described in detail in Section [*], but an example set-up script is shown in Fig. [*]. In this example, package version information is contained in the XML file my_versions.xml in the user's home area. An example version set file is shown in Fig. [*]. Alternate combinations of package versions can be tried by making alternate versions of the version set file.

Figure: Example of a set-up script driven by a private version file. See Section [*] for the format of the file.
\begin{figure}\begin{verbatim}export GLUEX_TOP=/home/gluex/gluex_top
export ... \

6.2.3 Default Environment at JLab

At JLab there is script that packages the steps shown in Fig. [*], with the appropriate values of GLUEX_TOP and BUILD_SCRIPTS. It uses the current default version set file, version.xml. It can also be used as an example for using a custom version of version.xml. To use it, for bash:

        source /group/halld/Software/build_scripts/
and for tcsh:
        source /group/halld/Software/build_scripts/gluex_env_jlab.csh
Optionally, these commands will take an argument naming a version set file to use rather than the current default. For example, for bash:
        source /group/halld/Software/build_scripts/ \

6.2.4 Simple Environment Set Up

The simplest (and recommended) form of environment set-up under BUILD SCRIPTS is the gxenv command. To define this command, use gluex_env_boot_jlab.(c)sh (at JLab) and gluex_env_boot.(c)sh (for gluex_install builds). These scripts also define the gxclean command. gxenv is used to set up the GlueX environment and gxclean is used to reverse the set up. The scripts also provide an environment variable, HALLD_VERSIONS, that points to the directory containing all of the official version set files (the version_*.xml files).

How to use the scripts to define the commands.

For tcsh, include the following line in your .cshrc, .login, or .tcshrc:

  source /group/halld/Software/build_scripts/gluex_env_boot_jlab.csh
at JLab and
  source /path/to/gluex_top/gluex_env_boot.csh
for gluex_install builds.

For bash, include the following line in your .bashrc, .profile, or .bash_profile:

  source /group/halld/Software/build_scripts/
at JLab and
  source /path/to/gluex_top/build_scripts/
for gluex_install builds.

Note that these “boot” scripts do not set up the GlueX environment. They merely define the command that will do the set up.

How to use the commands.

Usage is the same for both tcsh and bash, JLab and gluex_install.

To Set-Up the Environment: gxenv

  • To get the default environment:
  • To get the environment for a particular official version set, say version_3.5_jlab.xml, use the HALLD_VERSIONS environment variable:
      gxenv $HALLD_VERSIONS/version_3.5_jlab.xml
  • To get the environment for an arbitrary xml file, use its path:
      gxenv /path/to/my_version.xml

To Take-Down the Environment: gxclean

To clear all of the GlueX-specific parts of the environment, including GlueX-specific path elements (i.e., those in PATH, LD_LIBRARY_PATH, and PYTHONPATH):

This is not guaranteed to completely clean all gluexy things in all circumstances, but should work well when using gxenv to do the set-up.

Why implement things this way and not just do the set-up in the `.*rc` file? The underlying set-up command, `gluex_env_jlab.(c)sh,` has become a bit heavy. You may not want to have it executed everytime you start a new sub-shell. Also having the version set hard-wired in your initial environment can be confusing if you change version sets depending on what you are working on. For these reasons, putting the set-up in the global shell set-up is not recommended. Sourcing these scripts is very fast and once sourced, it is easy to switch from one version set to another, even from the command line.