Welcome to the Wire-Cell Toolkit source repository.
See http://wirecell.bnl.gov/ for documentation including user manual and news “blog”.
Wire-Cell Toolkit provides simple and automatic installation which gives you, the installer, some options.
The WCT dependency tree:
Anything that the WireCellUtil package depends on is required. The
rest are optional. Missing optional dependencies will cause the
dependent WCT package to not be built.
Some external dependencies have explicit minimum required versions:
- TBB (oneAPI) 2021.1.1
- Boost 1.75.0
You may provide the necessary external software dependencies in a manner of your own choosing and some options include:
- Spack-based install automatically builds all (non-OS) externals and WCT itself
- Some WCT releases are built at FNAL as a UPS product named
wirecell. - Exploit the above with a Singularity container and CVMFS (currently recommended)
Developers check out master branch via SSH.
$ git clone git@github.com:WireCell/wire-cell-toolkit.git wct
Users typically should build a release branch, either the tip or a tagged release on that branch. Tagged releases are shown on the this GitHub release page.
Users may also anonymously clone in the usual way:
$ git clone https://github.com/WireCell/wire-cell-toolkit.git wct
On well-behaved systems, configuring the source may be as simple as:
$ ./wcb configure --prefix=/path/to/install
Software dependencies which can not automatically be located in system
areas or via pkg-config can be manually specified. For a list of
options run:
$ ./wcb --help
Here is an example where some packages are found automatically and some need help and others are explicitly turned off:
$ ./wcb configure \
--prefix=$HOME/dev/wct/install \
--with-jsonnet=$HOME/opt/jsonnet \
--with-root=no
...
Removing submodule "dfp" due to lack of external
Removing package "tbb" due to lack of external dependency
Removing package "root" due to lack of external dependency
Removing package "cuda" due to lack of external dependency
Configured for submodules: apps, cfg, gen, iface, img, pgraph, ress, sigproc, sio, util
'configure' finished successfully (5.683s)
It is suggested to first build the code before running tests.
$ ./wcb -p --notests
To install the built toolkit and its configuration support files while still avoiding the tests do:
$ ./wcb -p --notests install
Optionally, the reference configuration and data files for one or more
supported experiments may be installed by giving naming them with the
--install-config option. A name matches a sub-directory under
cfg/pgrapher/experiment/ or the special all name will install all.
$ ./wcb -p --notests --install-config=<name> install
Running the tests can take a while but should be run on new installations and after any significant development. The developers try not to leave broken tests so any test failure should be treated as important. However, some tests require proper environment to run successfully. In particular, tests need to find Wire-Cell configuration and the 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)
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.
A new wcb build script is made from waf source via:
$ cd waf-tools $ ./refresh-wcb -o /path/to/wire-cell-toolkit/wcb $ cd /path/to/wire-cell-toolkit/ $ git commit -am "update wcb" && git push