The Wire Cell Toolkit (WCT) should be easy to build on any POSIX’y system with a recent C++ compiler. This section describes how to build releases and development branches, it gives guidance for supplying the few software dependencies, and documents how releases are made.
Installation requires four steps:
- get the source
- configure the source
- build the code
- install the results
WCT source is composed of several packages (see section Packages) and all source is available from the Wire Cell GitHub organization. Releases of each package are made and documented on GitHub (eg here) and can be downloaded as archives. However, using git to assemble a working source area is recommended and easier. Releases and development branches are handled slightly differently.
To obtain a release requires no GitHub authentication:
$ git clone --branch 0.5.x \
https://github.com/WireCell/wire-cell-toolkit.git
This gets the tip of a release branch (the 0.5.x series in this example).
A specific point release can then be checked out:
$ git checkout -b 0.5.0 0.5.0
To contribute new development to the toolkit, even as a “core”
developer, it’s recommended to fork the wire-cell-toolkit repository
on GitHub, do your work there and make GitHub Pull Requests (PR).
This gives an opportunity for other developers to give a quick check
on new code.
Core developers can nonetheless directly push to the central repository. It’s suggested to do so via an SSH authenticated clone:
$ git clone [email protected]:WireCell/wire-cell-toolkit.git wct
Prior to building, the source must be configured to specify an installation location and provide options to direct how to find external software dependencies and/or to select which optional dependencies. More details on the build system are in ./waftools.org.
On systems where software dependencies can be auto-detected, the configuration step may be as simple as:
$ ./wcb configure \ --prefix=/path/to/install
This will print the results of the attempts to detect required and optional dependencies. Missing but optional dependencies will not cause failure. See below for guidance on installing dependencies if this step fails or if desired optional dependencies are not found.
Dependencies may be automatically located if pkg-config is available and possibly by suitably setting the PKG_CONFIG_PATH environment variable. If automatic location fails then missing locations can be explicitly specified. The following shows an example where all externals are installed at a single location identified by the WCT_EXTERNALS environment variable (not, this variable has no other special meaning other than to make this example brief).
$ ./wcb configure \ --prefix=/path/to/install \ --boost-includes=$WCT_EXTERNALS/include \ --boost-libs=$WCT_EXTERNALS/lib --boost-mt \ --with-root=$WCT_EXTERNALS \ --with-fftw=$WCT_EXTERNALS \ --with-eigen=$WCT_EXTERNALS \ --with-jsoncpp=$WCT_EXTERNALS \ --with-jsonnet=$WCT_EXTERNALS \ --with-tbb=$WCT_EXTERNALS
If the externals are not all in one directory then their locations must be accordingly specified individually.
It is suggested to first build the code before running tests.
$ ./wcb -p --notests
If there are build failures more information can be obtained by repeating the build with more verbosity:
$ ./wcb -vv
To install the build results into the location given by --prefix simply issue:
$ ./wcb install --notests
Tests are run by default by ./wcb unless --notests is given. Running
the tests can take a while but should be run on new installations and
after any significant development. The developers should not leave
broken tests so any failure should be treated as important. However,
some tests require proper user environment to run correctly. In
particular, tests need to find some Wire-Cell configuration files and
the executable programs and shared libraries of the external software
dependencies need to be located. Below shows an example:
$ export WIRECELL_PATH=$HOME/dev/wct/wire-cell-data:$HOME/dev/wct/wire-cell-toolkit/cfg
$ export LD_LIBRARY_PATH=$HOME/dev/wct/install/lib:$HOME/opt/jsonnet/lib
$ ./wcb -p --alltests
...
execution summary
tests that pass 83/83
...
tests that fail 0/83
'build' finished successfully (15.192s)
These other commands may be useful:
$ ./wcb clean # clean build products
$ ./wcb distclean # also clean configuration
# build with debug symbols
$ ./wcb configure --build-debug=-ggdb3 [...]
# to save some time, just
# rebuild the given test
# and don't run any tests
$ ./wcb --notests --target=test_xxx
$ ./wcb --help # see more options.
Managing environment is usually a personal choice or computer facility policy and WCT does not place any significant requirements on this. The usual setting of PATH like variables will likely be needed.
Internally, WCT requires a minimum of environment variables:
WIRECELL_PATH- a list of directories to search when locating configuration files. More information is in the section Configuration.
The WCT depends on a number of third-party “external” software packages which are not expected to be provided by a typical unix-like system:
- Boost
- various functions
- Eigen3
- matrix representation, interface to FFTW
- FFTW3
- for fast Fast Fourier Transforms
- JsonCPP
- basis for configuration and input data files
- Jsonnet
- structured configuration files.
Additional, optional package are needed for additional functionality:
- ROOT
- for the
root/sub-package, not required for core code - TBB
- for parallel, multi-threaded data flow programming paradigm support
- CUDA
- support for some GPU technologies
The following subsections gives some guidance for obtaining these “external” packages.
In the DIY mode, the installer is free to provide the third-party packages in any convenient way. Many of them are available on well supported operating systems such as Debian/Ubuntu. Homebrew for Mac OS X is not a core developer platform but may provide many. Redhat derived Linux distributions may find suitable package on EPEL. Most of the required packages are fairly easy to build from source.
However the installer decides to build in DIY-mode the WCT build system should be able to be given proper installation locations via the --with-* flags as described above. If it seems not to be the case, please contact the developers.
One mostly “turn key” sway to provide an environment for WCT development and running is to use Singularity containers possibly augmented with CVMFS. Instructions and support can be found in the wire-cell-singularity package.
Spack is a “meta build system” that runs the individual build systems that come with packages. It allows one to manage an ever growing installation area which can accommodate multiple versions of a package. It also comes with support for Environment Modules to handle your users’ setup of these packages or can make targeted release “views” of its package tree.
WCT provides a package wire-cell-spack which collects instructions and an Spack “repo” that builds WCT and its third-party dependencies. This leverages Spacks built-in “repo” to provide dependencies needed by WCT’s direct dependencies. Using it will tend to build packages that one may already have installed through the OS (eg, Python). However, this duplication should not add much to the overall build time which is automatic nor lead to any problems.
An installer that wishes to use wire-cell-spack to provide the dependencies should begin by following its README file.
Fermi National Accelerator Lab (FNAL) uses a user environment system similar to Environment Modules. It is typical to download binaries provided by FNAL, either manually of automatically via a CVMFS mount, and then use the UPS shell function setup to configure a user environment with many environment variables. For each package (“UPS product”) that is so setup there is a variable that gives the installation location. These can be used to provide suitable values for the --with-* flags to wcb as described above. The source provides a script waftools/wct-configure-for-ups.sh which may help run ./wcb configure in such an environment.
Releases are made by developers as needed and as described in this section.
WCT label releases are made following a fixed procedure. Releases are labeled with the common three-number convention: X.Y.Z. These take the following semantic meanings:
- X
- a major release is made when developers believe some substantial milestone has been achieved or to being wholly new or a globally breaking development path.
- Y
- a minor or feature release is made when substantial new and in particular any breaking development is made.
- Z
- a bug release fixes problems without otherwise substantial changes.
Any new major or minor releases produce a new Git branch in each package. Only bug fixes are made to this branch. Where applicable, release bug fixes should be applied to master. Nominally, all development is on the master branch however developers are free to make their own feature branches. They are encourage to do this if their development is expected to be disruptive to other developers.
To make releases, the above details are baked into two test scripts make-release.sh and test-release.sh. See comments at the top of each for how to run them. These scripts can be used by others but are meant for developers to make official releases.