![[*]](crossref.png)
), BUILD SCRIPTS will be installed under $GLUEX_TOP/build_scripts. You will have to contact your local expert to find the location of $GLUEX_TOP. Once that is known the BUILD_SCRIPTS environment variable to point to $GLUEX_TOP/build_scripts.
GlueX-Doc-2793-v17
Mark M. Ito
Jefferson Lab
September 16, 2019
They are all related, aspects of one affects aspects of each of the others.
Having a standard system makes collaborative work more efficient, especially when one needs help from others to solve a problem.
This section give concise instructions for performing a few common tasks with BUILD SCRIPTS.
There are several sources.
At JLab, BUILD SCRIPTS is installed in /group/halld/Software/build_scripts. You can start by defining an enviroment variable:
Outside JLab, when the gluex_install procedure has been followed (see section ), BUILD SCRIPTS will be installed under $GLUEX_TOP/build_scripts. You will have to contact your local expert to find the location of $GLUEX_TOP. Once that is known the BUILD_SCRIPTS environment variable to point to $GLUEX_TOP/build_scripts.
The latest version of BUILD SCRIPTS is available from GitHub at
Set your BUILD_SCRIPTS environment variable to the full path of the build_scripts-latest directory that results from untar'ing the file.
You can clone the Git repository:
There are several software components that are needed to build and use GlueX software. Most of them are assumed to be provided by the native operating system or distribution, but there are some that have to be built by the GlueX user. They are:
Detailed description of these packages will not be given here; please see the GlueX Offline Software wiki page for more information.
There are in general multiple versions (releases) of each of these packages and it is often convenient to have access to more that one version of a package built and available for use. In addition some packages depend on one or several others for libraries and include files.
The BUILD SCRIPTS directory structure supports multiple versions of each
package. For an example see Fig. . In the
figure, ``gluex_top'' is a generic name, each installation may choose
a different directory name. BUILD SCRIPTS looks for the name of this directory
in the environment variable GLUEX_TOP.
Under gluex_top, each package has its own container directory ( e. g., JANA, hdds, sim-recon) and for each package container directory one or more specific versions of that package are built.
All scripts and makefiles to support BUILD SCRIPTS are found the in the build_scripts directory. At JLab, the full path is
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.
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 .
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.
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.
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.
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.
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.
 |
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.
 |
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 latest version of
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/gluex_env_jlab.sh
and for tcsh:
source /group/halld/Software/build_scripts/gluex_env_jlab.csh
The simplest (and recommended) form of environment set-up under BUILD SCRIPTS is the gxenv command. gluex_env_boot_jlab.(c)sh (at JLab) and gluex_env_boot.(c)sh (for gluex_install builds) are short scripts that provide two commands (aliases for tcsh, functions for bash) that facilitate setting up and tearing down the GlueX software environment. The commands provided are: gxenv and gxclean. By defining these commands, the scripts ``boot-up'' environment setting.
The scripts also provide an environment variable, DIST, that points to the directory containing all of the official version set files (the version_*.xml files).
For tcsh, include the following line in your .cshrc, .login, or .tcshrc:
source /group/halld/Software/build\_scripts/gluex_env_boot_jlab.cshat JLab and
source /path/to/gluex_top/gluex_env_boot.cshfor gluex_install builds.
For bash, include the following line in your .bashrc, .profile, or .bash_profile:
source /group/halld/Software/build\_scripts/gluex\_env\_boot\_jlab.shat JLab and
source /path/to/gluex_top/build\_scripts/gluex\_env\_boot.shfor gluex_install builds.
Usage is the same for both tcsh and bash, JLab and gluex_install.
gxenv
gxenv $DIST/version_3.5_jlab.xml
gxenv /path/to/my\_version.xml
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):
gxcleanThis 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.
Each of the packages have their own native build system and each build system has its own set of details that have to be understood. In addition, the technology used to do the build varies from system to system. It may be make, imake, cmake, SCons, or something else. The BUILD SCRIPTS system makes a choice of build options for each package so that the user need not master these details.
The BUILD SCRIPTS build system is implemented in GNU Make. These makefiles
invoke the native package-specific build system. The top-level
makefile builds packages into the standard directory structure
described in Section . It in turn uses a
``package
makefile'' for each package (e. g., Makefile_jana,
Makefile_sim-recon). Invoking make with a package makefile will
build that package with the home directory placed in the current
working directory. In other words, the package makefiles have no knowledge of
the directory structure within which they are used; they just build
locally. Only the top-level makefile knows about the directory structure.
Complete builds are orchestrated by Makefile_all. The highest-level targets of Makefile_all, shown with their dependencies are:
all: gluex_pass2 gluex_pass1: xerces_build lapack_build cernlib_build root_build \ geant4_build evio_build sqlite_build sqlitecpp_build \ rcdb_build ccdb_build gluex_pass2: gluex_pass1 jana_build hdds_build amptools_build \ hepmc_build photos_build evtgen_build halld_recon_build \ halld_sim_build hd_utilities_build hdgeant4_build \ gluex_root_analysis_build mcwrapper_build
The all target builds all officially supported packages. These are broken into two sets, gluex_pass1 and gluex_pass2 to solve the issue of packages that can only be set-up after they are built. This is a problem when starting from scratch. In that case the build must proceed in four steps.
make -f $BUILD_SCRIPTS/Makefile_all gluex_pass1
make -f $BUILD_SCRIPTS/Makefile_all gluex_pass2
Makefile_all should always be invoked from the $GLUEX_TOP directory.
If you would like the build to proceed in parallel (for those packages that support parallel builds), set an environment variable (eight threads in this example):
export NTHREADS=8or set the variable on the make commmand line. For example:
make -f $BUILD_SCRIPTS/Makefile_all gluex_pass2 NTHREADS=8
Each of the individual package targets (e. g., evio_build
and hdds_build) use the corresponding package
makefile. Directories are created and the package makes are executed
in way that gives the directory structure described in
Section . To do this, the package container
directory is created if it does not exist and the requested package
makefile is invoked from within the package container directory.
Of course, each individual package build target can be invoked
directly. More on this in Section
The target cernlib_debug is non-standard. If this target is invoked, it well create a separate container directory cernlib_debug for the debug versions. Also it does not have its own package makefile, rather on 64-bit machines, it invokes Makefile_cernlib_Vogt with command line options that cause appropriate debug compiler flags to be used.
To use the resulting debug version of CERNLIB, the CERN variable
must be set to point to the cernlib_debug directory, either explicitly as an environment variable (as described in Section or by using the home attribute in the package element of a version set file (as described in Section .
Each of the package makefiles is sensitive to environment variables that control which version of the package to build. The makefiles themselves take care of obtaining the source code. In general, there are two ways to get the code: downloading a tarball or checking the code out from a version control repository, although the later option is not available for all packages.
Each packages respects a version-specifying environment variable. Here is an example of how they might be set in the C-shell:
setenv JANA_VERSION 0.7.2 setenv SIM_RECON_VERSION 1.2.0 setenv HDDS_VERSION 3.2 setenv CERNLIB_VERSION 2005 setenv XERCES_C_VERSION 3.1.1 setenv CLHEP_VERSION 2.0.4.5 setenv ROOT_VERSION 5.34.26 setenv CCDB_VERSION 1.05 setenv RCDB_VERSION 0.00 setenv EVIO_VERSION 4.3.1
In each case there is standard system for distributing tarballs marked
with the version name. Each package has different conventions, but the
package makefiles have that knowledge of the appropriate convention
coded in. Also, the name of home directory created depends on the name
that appears in the tarball (with exceptions as mentioned in
Section . Note that the version variable
can be set on the make command line as well.
Some packages can be checked out from a Subversion or Git repository. If that is the desired source of the code, the version variable should not be set. Instead a URL variable should be used to specify the location of the repository. For example:
setenv HDDS_URL https://github.com/jeffersonlab/hdds
will cause the HDDS package makefile to check out the master branch of the HDDS Git repository at GitHub. The names of the variables for other packages are JANA_URL (Subversion), CCDB_URL (Git), RCDB_URL (Git), and SIM_RECON_URL (Git) respectively.
For packages that use a Git repository, there are two additional variables that can be used to control the checkout. SIM_RECON_BRANCH is used to check-out a specific branch and SIM_RECON_HASH is used to check-out a specific commit of sim-recon. If one is set, the other should not be. There are analogous variables for CCDB, RCDB, and HDDS.
For the sim-recon package, there is a variable, SIM_RECON_SCONS_OPTIONS that can be defined, either in the shell environment on on the make command line, that will supply optional arguments to the scons command invoked by make. For example,
make -f $BUILD_SCRIPTS/Makefile_sim-recon \
SIM_RECON_SCONS_OPTIONS='SHOWBUILDS=1'
will cause SCons to show the compiler commands explicitly.
The LAPACK and BLAS libraries are needed by CERNLIB. They are downloaded and build automatically, but rather than being installed in their own home directory, The ``install'' target of Makefile_lapack adds them to the lib directory of your CERNLIB build.
There are two ways:
After setting the desired values of the version environment variables
and/or the URL environment variables (see
Section you can invoke Makefile_all with the target(s) needed or with a high-level target
like gluex,
cd $GLUEX_TOP
make -f $BUILD_SCRIPTS/Makefile_all gluex
If some of the versions of individual packages requested already
exist, then make will do the usual thing: try to remake them and find
that there is nothing to do.
Since the individual package makefiles build in the local directory, they can be used directly by going to the appropriate container directory. For example,
cd $GLUEX_TOP/sim-recon make -f $BUILD_SCRIPTS/Makefile_sim-recon SIM_RECON_VERSION=1.4.0Note that in this example the version is specified on the make command line rather than through an environment variable. That is not necessary; it is an option supported by make and defining SIM_RECON_VERSION in the environment would work as well. Also note that doing the build in the sim-recon container directory is not necessary for the build to succeed; any directory will work. In this example however we are adding to an existing standard directory structure so we cd to the standard directory.
The versioning system uses an XML-formatted version set file to specify
both package version information and package home directory definition
in the shell environment. An example file is shown in
Fig. .
There is only one type of element, the package. Attributes are:
As we saw in Section ,
environment setting via gluex_env.(c)sh is sensitive to the
definition of the package home variables. In
Section , we saw that the package
makefiles are sensitive to either the version-defining environment
variables or the URL-defining environment variables, using them to choose the
version of code to build. The version set file can be used to define both
classes of variables. In this way it can be used to both build a
consistent set of packages and to set-up the environment to use the
build. Executing
$BUILD_SCRIPTS/version.pl version_1.7.xml
where for the purposes of this example version_1.7.xml is the
file shown in Fig. and GLUEX_TOP is
/home/gluex/gluex_top, creates the output shown in
Fig. .
Since you would want these commands applied to the current shell level, in practice you use
eval `$BUILD_SCRIPTS/version.pl version_1.7.xml`
Following this step, one normally would invoke gluex_env.(c)sh
to complete the set-up of the environment.
In this example, the variable definitions come (mostly) in pairs, a
version variable and a home directory variable. The version variable
affects only the build process since the corresponding package
makefile keys off it (see
Section ). The home directory variable
affects the build as well in that it tells the package makefile where
to find any prerequisite packages and in addition it affects use of a
build via its effect on path variables.
Finally, the script gluex_env_version.(c)sh combines use of
version.pl and gluex_env.(c)sh to more conveniently set
up the environment. We have already seen an example of its use in
Fig. . The script uses version.pl as
shown above to set the stage for an invocation of gluex_env.(c)sh.
We saw in Section that a URL variable
can be used to instructed the package makefiles to get the source code
from a version control repository rather downloading a tarball. The
url attribute in the package element calls out the value of the
URL to use directly. In a particular package element, either the
version attribute or the url attribute should
appear; if both appear then the version attribute will
be used (i. e., tarball).
If the url attribute is used, each package makefile
will interpret the URL as is appropriate for that package, either as a
Subversion repository or a Git repository; there can be only one
answer and it is coded into the package makefile. For Git
repositories, the optional branch attribute controls which
branch is checked out. If it is absent, the master branch is
used. For example, to clone sim-recon and checkout the branch
test_stuff, use
<package name="sim-recon"
url="https://github.com/jeffersonlab/sim-recon"
branch="test_stuff"/>
This will cause the SIM_RECON_BRANCH variable to be set in
the environment. Similarly the hash attribute can be used to
specify the hash of the particular commit to be checked-out.
<package name="sim-recon"
url="https://github.com/jeffersonlab/sim-recon"
hash="22fe917"/>
Note that for Subversion repositories, the branch specification is encoded in the URL itself and the branch and hash attributes are ignored.
The dirtag attribute can be used to distinguish different builds of a package where the only difference between them is the version(s) of one or more prerequisite packages. The string used is arbitrary. A directory tag can be attached to either a source directory made from a tarball or one from a source code repository. The tag name is appended after a caret symbol (^), for example,
<package name="hdds" version="3.3" dirtag="xerces_test"\>in a version set file would cause version.pl to add an additional variable to the environment:
setenv HDDS_DIRTAG xerces_testand Makefile_hdds would then produce a directory named hdds-3.3^xerces_test, with source code obtained from the standard tarball, hdds-3.3-src.tar.gz in this case.
The corresponding home directory variable will also reflect the directory tag, of course.
There are a lot possible meanings for the directory tag. It could mark different combinations of prerequisites as well as designating packages where the source code does not come from a standard source (tarball or repository). Because of the large number of possibilities, the form of the tag string is left to the user; no assumption is made about it meaning.
Often one wants to use a build of a specific package that lies outside of the standard directory structure. This can be put into the environment by setting the home attribute of the corresponding package element. For example
The public version set files are stored in a GitHub repository, JeffersonLab/halld_versions, available at
At JLab the repository is checked out in
The names of the files are of two main types, (1) version sets that correspond to a periodic package update release and (2) version sets that correspond to a ``launch'' over GlueX data.
Each package may or may not have a build dependency on other packages managed by BUILD SCRIPTS. For example a particular version of sim-recon can be built against any of a number of versions of HDDS, including custom versions provided by the user. To insure that the environment being set-up has a consistent set of package versions, a facility is provided to warn the user if possible inconsistencies are detected.
At build time, a version xml file is created in the home directory of
a package if that package has dependencies on others in the
system. For example, $HALLD_HOME will have the file
sim-recon_prereqs_version.xml, listing the versions used to build
sim-recon. An example is shown in Fig.
At set-up time, when gluex_env.(c)sh is invoked, if a version file with prerequisites is found in the package home directory, then each package in that file is checked for version consistency. A match is sought between the version number specified in the version set file and the version number encoded in the home directory for the prerequisite package, i. e., the directory defined as home in the environment being set-up. Here the version from the home directory is extracted in two ways depending on how the package was built:
There are cases where the home directory does not contain any information about the source of its source code. For example, the code could have come via the svn export command or the git archive command. If a such a build (for example HDDS) is a prerequisite of another package (for example, sim-recon), then the dependent package (sim-recon) will usually have listed the prerequisite (HDDS) with neither a version nor a url attribute defined in its (sim-recon's) prerequisite file. In that case, a warning will be issued noting the absence of both version and url attributes.
The gluex_install system uses build_scripts to create a complete install of GlueX software from scratch. This is especially useful for new machines.
No interaction from the user should be required to get a successful build. The only assumption made is that the basic packages that come in a minimal install are present. The definition of minimal depends on the installation. In all cases, the distribution was tested by first installing from a DVD or CD ISO image. Typically, the ``live DVD'' version was chosen since that installs the smallest number of packages.
The scripts have been tested on the following distributions listed in
Table .
Root access is required for steps (1) and (3).
distribution
.sh. The
prerequisites script installs packages from the distribution
repository necessary for the GlueX build. As such, it must be
executed by root. In addition it makes some symbolic links in system
directories that are necessary for the cernlib build. These scripts
are specific to particular distributions. You must run this
script from inside the ``gluex_install'' directory created when you
get the scripts (see Get the Scripts, step 2).
Note that if parallel builds are desired (for the packages that
support them) set the NTHREADS environment to the number parallel
processes desired. Since gluex_install.sh invokes Makefile_all, the value will be used. See
Section .
After the build is complete, there are two files in the gluex directory, setup.sh and setup.csh, that can be used to set-up the complete GlueX environment under Bourne-like shells or C-like shells respectively.
GlueX-Doc-2793-v17
This document was generated using the LaTeX2HTML translator Version 2012 (1.2)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -local_icons -split 0 -show_section_numbers build_scripts_web
The translation was initiated by Mark Ito on 2019-09-16
