Skip to content

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:

  1. ROOT (CERN analysis package)
  2. BOOST (C++ source libraries)
  3. BLAS (linear algebra libraries)
  4. 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:

  1. Set the environment variable CDMS_IOLIBRARY to the top-level directory of IOLibrary.
  2. Have libcdmsio.so in a directory contained in LD_LIBRARY_PATH.
  3. 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.

  1. Create build and install directories in parallel to the git repository.

    $ cd /path/to/<PackageName>
    $ mkdir build install

  2. Enter build directory and configure the build step.

    $ cd build
    $ cmake ../BatCommon.git -DCMAKE_INSTALL_PREFIX=../install

  3. Compile and install the package.

    $ cmake --build .
    $ cmake --build . --target install

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