Installation Instructions for CbmRoot

The easiest way to install CbmRoot is described in Chapter 3 which introduces a scripts for automatic installation of CbmRoot and its dependencies. If you are unsure how to install CbmRoot please follow the instructions in this chapter. If you are running CbmRoot please consider using the preinstalled FairSoft and FairRoot versions on CVMFS.

1. Dependencies

1.1 Compiler

To be able to compile CbmRoot, the used compiler must support the C++17 standard. A GCC beginning from version 7 and clang beginning from version 6 should be okay. Normally the rule of thumb is "newer is better".

1.2 FairSoft

To install, compile, and run CbmRoot, several external programs are required. These are for example Root, Geant3 or Geant4 and many others. Installing these is the first step of the CbmRoot installation. As the individual installation of each of these programs is very time consuming, the FairRoot team provides a software bundle known as FairSoft, which contains all the needed packages, and also provides tools for its automated installation on several platforms. The most up-to-date information regarding the installation of FairSoft, together with a complete list of the contained packages, can be found on the project's GitHub page:

https://github.com/FairRootGroup/FairSoft

This page should be considered the primary source of information regarding FairSoft, which takes precedence over any others (which may in some cases be outdated). Additional information, for instance regarding older versions, can be found on CBM Redmine:

https://redmine.cbm.gsi.de/projects/cbmroot/wiki/Install_External_Packages

We recommend to always use the default FairSoft release version specified in this document. This version was thoroughly tested. Currently the default version is "nov22p3". If you already have an installation of "nov22p1" or "nov22p2" you can use this version as well. The only difference between the versions are minor. Compared to "nov22p1" the version "nov22p2" only corrects a meanwhile wrong download URL. The version "nov22p3" adds some fixes which are needed to allow compilation also with gcc13 and gcc14 as well as with python > 3.13.0. The package versions itself are identical for all three mentioned versions. Different other combinations of older or newer versions of FairSoft, FairRoot and CbmRoot may work in principle, but are not endorsed or actively supported.

To install all needed system dependencies there are scripts for all major Linux systems. Please follow the instructions at

https://github.com/FairRootGroup/FairSoft/blob/nov22p3/legacy/dependencies.md

to install all system dependencies. This is the only step where administrator privileges are needed.

The complete installation of FairSoft (and likewise FairRoot and CbmRoot) doesn't need any administrative privileges and an installation into system paths is strongly discouraged, as this may create conflicts with existing system software. So please make sure that you do the installation as normal user.

For an installation which is to be shared between users on a MacOS or linux system it is recommended to use the opt/ folder. Consider also using the auto installer (see section 3).

The compilation of FairSoft is the most time-consuming part of the CbmRoot installation and can take several hours, depending on your system. If you are working at GSI there are always ready-to-use versions of FairSoft available. For detailed information please check the following wiki page

https://redmine.cbm.gsi.de/projects/cbmroot/wiki/RunCbmGSI

1.3 FairRoot

CbmRoot is based on FairRoot, a simulation, reconstruction and analysis framework which is based on the ROOT data analysis framework, which by now is also used by several other experiments as base for their developments. So beside FairSoft you need also to install FairRoot to be able to compile CbmRoot.

Detailed instructions how to get and compile FairRoot can be found on the project's GitHub page at:

https://github.com/FairRootGroup/FairRoot

We again recommend this official repository as the primary source of information, and recommend using the proposed default version which currently is v18.8.0. For this version extensive tests were performed.

Other information can be found at:

https://redmine.cbm.gsi.de/projects/cbmroot/wiki/InstallFairRoot

In order to compile FairRoot, you must set the environment variable SIMPATH to contain the path to your FairSoft installation, i.e.:

export SIMPATH=[path_to_fairsoft]

After installing FairRoot the environment variable SIMPATH can be unset since it isn't needed any longer for the CbmRoot installation

unset SIMPATH

2. Installing CbmRoot

After installing FairSoft and FairRoot, to install CbmRoot first create a local clone of the official Git repository using:

git clone https://git.cbm.gsi.de/computing/cbmroot

After downloading the complete repository one needs to choose the correct branch or tag. If one wants to work with the current release this steps are needed

cd cbmroot
git checkout -b tag_JUL24 JUL24

To start the generation of the build sysem files and finally the compilation of CbmRoot use the following command

From your CbmRoot source directory call

cmake -S . -B build -DCMAKE_CXX_STANDARD=17 -DSIMPATH=#FairSoft_Installation_Directory# -DFAIRROOTPATH=#FairRoot_Installation_Directory#
cmake --build build -j[number_of_cores]

The first command used the current directory . as source directory and creates a subdirectory build for the compilation. The two parameters SIMPATH and FAIRROOTPATH needs to point to the installation directories of FairSoft and FairRoot. The C++ standard is defined as C++17. The second command finally starts the compilation. The parameter j allows to specify the number of used processes which are executed in parallel.

After your build is complete, before running any part of CbmRoot from a shell, a large number of environment variables must be set, which contain various library and include paths. This is done automatically by executing the "config.sh" or "config.csh" script from your CbmRoot build directory.

Please note, that you must supply the argument "-p" (prepend), "-a" (append) or "-o" (overwrite) to these scripts, depending on whether you wish to add the new entries at the front or back of existing environment variables or to overwrite them. As security measure the variables are appended when no parameter is specified. The overwrite option may be desired in some special cases but normally append is a good choice.

If you are using a Bash shell, you can add the following line to .bashrc to further automate this step:

source ~/build_cbmroot/config.sh -a > /dev/null 2>&1

The problem with this automatisation is that it frequently results in problems if you use more than one combination of FairSoft/FairRoot/Cbmroot. If this isn't the case for you please proceed but keep in mind to unset this automatism before installing any new versions of FairSoft, FairRoot.

3. Automatic installation

To make the installation easier we provide a script which automatically compiles and installs FairSoft, FairRoot, and CbmRoot in one go. The script always combines the correct FairSoft and FairRoot versions. The full description of this process is at

https://redmine.cbm.gsi.de/projects/cbmroot/wiki/InstallCbmRootAuto

To get the script and the needed CbmRoot source code to your local computer you need to clone the CbmRoot repository from out Git repository using:

git clone https://git.cbm.gsi.de/computing/cbmroot

You still need to install all system dependencies which are descroibed at

https://github.com/FairRootGroup/FairSoft/blob/nov22p3/legacy/dependencies.md

The needed skript is then available in the CbmRoot source directory and can be executed from there by a one-line command

./autoinstall_framework.sh --fairsoft --fairroot --cbmroot

The command automatically install the defined production versions of FairSoft and FairRoot. If you want to check for the avaible options you can get the complete list with

./autoinstall_framework.sh --help

If any problems appear and the script stops with an error message please redo the installation step by step to see where the problem appears.

./autoinstall_framework.sh --fairsoft
./autoinstall_framework.sh --fairsoft --fairroot
./autoinstall_framework.sh --fairsoft --fairroot --cbmroot

The same script can be used to only install any subset of the three packages. See the Redmine page or the script itself for further details.

3.1 Tested systems

The current version of the script was tested for the following systems and combinations of FairSoft and FairRoot. Probably other versions work as well.

4. Recommended versions

GCC : >= 7 or Clang: >= 6

FairSoft: nov22p3 for new installations FairSoft: existing installations of 'nov22p1' and 'nov22p2' can be used

FairRoot: v18.8.0

Clang-format: v11.0

Boost archives being only ensured to be backward compatible (and therefore not necessarily forward compatible), care must be taken when writing data and/or parameter files with it that the versions used when writing and when using/reading are compatible.
More information in the following document.

5. Further remarks

Compiling CbmRoot with multicore support using "make -j", without specifying the number of threads, is known to cause MacOS and Ubuntu 20.04 LTS systems to freeze. Please explicitly choose a number of cores which is suitable for your system.

6. CI and Code formatting

For information about our Merge-Request CI chain, including code formatting, please refere to this description page