General installation instructions¶
Cloning the repository¶
BatCommon is available on GitLab and requires a GitLab user account with access to the SuperCDMS project in order to clone the package.
It is highly recommended to add ssh keys
to your account following the instructions posted here.
After that, the project can be cloned from an ssh session on a computing site via the following command:
$ git clone git@gitlab.com:supercdms/Reconstruction/BatCommon.git
Dependencies¶
BatCommon requires common UNIX base packages to be build upon, but also depends on some packages, which need to be set up by the cluster maintainers or the users themselves. This concerns in particular:
- ROOT (CERN analysis package)
- BOOST (C++ source libraries)
- BLAS (linear algebra libraries)
- IOLibrary (CDMS I/O library)
For ROOT version v6.14+ is known to work; earlier releases may work. For BOOST version v1.64+ is required to ensure proper python bindings.
There are many different implementations of the BLAS library.
The "reference" version, libblas.so, is the most common, but also the least optimized.
The suggested package to use is openblas
(e.g. openblas-devel
on yum), which is not the most optimized but is widely available.
If it is installed as a system package, cmake
will be able to find it during the configuration step.
Otherwise it should be sufficient to have the directory with the library file in your LD_LIBRARY_PATH.
However, for the latter case it may be needed to provide additional cmake flags to locate the respective header files during the configuration.
There are three ways for cmake
to find IOLibrary:
- Set the environment variable CDMS_IOLIBRARY to the top-level directory of IOLibrary.
- Have libcdmsio.so in a directory contained in LD_LIBRARY_PATH.
- Use the argument "-D CMAKE_LIBRARY_PATH=" in the
cmake
configuration.
Note that all of these options assume a default build of IOLibrary, i.e. the library itself is in a folder "lib" which is parallel to the include files.
Building procedure¶
BatCommon supports both in- and out-of source builds.
Out-of-source builds are generally recommended for all cmake
builds.
This allows for a clean git repository state while it is possible to maintain multiple parallel builds for e.g. different feature branches.
The following guide assumes a directory structure as follows:
../soft/<PackageName>/
git_source
build_dir
install_dir
with three relevant directories: source (i.e. BatCommon.git), build and install.
-
Create build and install directories in parallel to the git repository.
$ cd /path/to/<PackageName>
$ mkdir build install
-
Enter build directory and configure the build step.
$ cd build
$ cmake ../BatCommon.git -DCMAKE_INSTALL_PREFIX=../install
-
Compile and install the package.
$ cmake --build .
$ cmake --build . --target install
-
Export environment variable needed for CDMSBats.
$ export CDMS_BATCOMMON=/path/to/BatCommon/install
Optionally, the build process can be executed with multiple cores.
For that the cmake
build command above can be replaced with
$ cmake --build . -- -jN
where N indicates the number of cores (e.g. -j4
for 4 cores).
However, errors in the build process might not be recognized immediately by the user as parallel running processes will not be interrupted and may run to completion.
Identifying the root cause for an incomplete build could be more complicated that way.
Note about cmake versions¶
Note that on some systems (e.g. SLAC Centos7), cmake
may point to an old cmake
version 2.X,
while this build requires version 3.X. Usually there is an additional cmake3
version on those systems. In that case you should either define an alias alias cmake=cmake3
or replace cmake
with cmake3
in all the commands above.