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 foo.sh 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
ROOT	ROOTSYS
JANA	JANA_HOME
sim-recon	SIM_RECON_HOME
HDDS	HDDS_HOME
CERNLIB	CERN_ROOT
Xerces-C	XERCESCROOT
CCDB	CCDB_HOME
Geant4	G4ROOT
EVIO	EVIOROOT
RCDB	RCDB_HOME
HDGeant4	HDGEANT4_HOME
hd_utilities	HD_UTILITIES_HOME
gluex_root_analysis	ROOT_ANALYSIS_HOME
AmpTools	AMPTOOLS_HOME
SQLiteC++	SQLITECPP_HOME
SQLite	SQLITE_HOME
gluex_MCwrapper	MCWRAPPER_CENTRAL
halld_sim	HALLD_SIM_HOME
halld_recon	HALLD_RECON_HOME
LAPACK	none
HepMC	HEPMCDIR
PHOTOS	PHOTOSDIR
EvtGen	EVTGENDIR
Diracxx	DIRACXX_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 ... ...sername/sim-recon source $BUILD_SCRIPTS/gluex_env.sh\end{verbatim} \end{figure}$

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 ... ...luex_env_version.sh \ /home/username/my_versions.xml\end{verbatim} \end{figure}$

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:

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

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.