Installing R3BRoot & Co.

Preparing the environment

Using a sane system

The system used to install r3broot is exceptionally important. Outdated or missing software and libraries will break the installation process and result in a lot of frustration.

I recommend the latest Ubuntu, CentOS, Debian, or similar, even though FairSoft might not have updated their recommendations. If you have no control over the installed system, i.e., when using a shared server with many cores, there is a limited number of things to mitigate issues as discussed below - but you should loudly demand an up-to-date system by default.

Environment variables

Environment variables determine most things in Linux. For example, "installing" in Linux mostly means either putting executables and libraries in directories listed in specific environment variables, PATH and LD_LIBRARY_PATH, or adding the respective path to those variables.

The system will look through the paths in an environment variable one by one, and the first match will take precedence. This does work as expected in most cases, but sometimes remnants of older stuff can slip through - so it's best to keep the environment variables as clean as possible.

All environment variables can be shown with env or echo $PATH and changed with export. A common pattern is export PATH=/my/new/path:${PATH}.

Thus, many versions of one program can be "installed" and switched between with environment-setting macros or, better, virtual environments.

A modern compiler (gcc >= 10)

At the time of writing, gcc version 11 is current. That might not be available everywhere, but version 10 should be. If not, installing the compiler from its source is not a good idea for a beginner. Instead, many systems provide modern compilers as devtoolset or gcc-toolset that can be installed and activated with scripts that set the environment variables, e.g., with source /opt/rh/devtoolset-10/enable.

Python (>= 3.8)

All classes and functions build with the ROOT system are usable from Python! That means you can steer performant C++ code with easy-to-use Python scripts instead of gnarly ROOT macros! Amazing!

Python is included in the FairSoft/FairRoot if installing with spack. So if you install with spack, you don't need to worry about anything.

If you can't install with spack, I strongly recommend having a modern Python installed and activated to build FairSoft/FairRoot. Check if an up-to-date version is already installed and active: python --version should give version 3.8 or later. If this is not the case, there are several options. Note that you must build it with shared libraries and fPIC.

• Sometimes, several python versions are installed in the PATH and suffixed with the respective version number, e.g., python3 or python3.8. In this case, use those to create a venv.
• Similar to the devtoolset, additional packages are sometimes installed but not activated, e.g. source /opt/rh/rh-python38/enable.
• Install from source manually.
• Install from source via pyenv and pyenv-virtualenv. Installing would look like PYTHON_CFLAGS=-fPIC PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.9.6

A modern code editor

The neutrality of this section is disputed. Comment Philipp:

In my opinion, there are both upsides and downsides of using an IDE instead of a text editor. While a well-configured IDE can save time in the long run, configuring an IDE can also be time-consuming. Plenty of R3BRoot users use Visual Studio Code, but plenty also use vim or emacs or other plain text editors with syntax highlighting. If you are proficient in a text editor, to keep using it may be the correct choice.

End Comment Philipp.

Do not use vim or some other plain text editor. It is much easier to use an IDE that understands what is going on and can help you code and provide automation.

• Visual Studio Code is currently the most prominent free editor. It can be installed on any system easily. If you don't have admin rights, download and extract the Linux .tar.gz. Several plugins are available, e.g., CMake Tools.
• CLion is a full-blown commercial IDE that is free for educational use. Use your university email to sign up.

Setting these up and fully integrating FairSoft, FairRoot, and R3BRoot is well worth your time.

GitHub Account and SSH-Key

FairSoft, FairRoot, and R3BRoot are managed on GitHub. While you can download all Code without access control using the https-Links, creating a GitHub Account and an SSH key is necessary to contribute your changes.

The basic git setup itself looks like this. Use the same email as your GitHub account.

git config --global user.name "Your Name"
git config --global user.email [email protected]
git config --global pull.ff only

(Do not run this on the land account. In fact, do not use the land account outside beam times. See https://wiki.r3b-nustar.de/misc/git .)

See the GitHub documentation for Generating a new SSH key and Adding a new SSH key to your GitHub account.

Installing FairSoft and FairRoot

Use Spack: Currently, you can install FairSoft either with the legacy (cmake) based method or the modern spack package manager. As the spack method also installs all the required libraries, including Python, you should use it - even though it might still be marked experimental.

Use the latest named version: As the versioning scheme of FairSoft is bad, you have to scan through the list to see which version is the latest. At the time of writing, aug21 was not released yet but should be soon. I would recommend a defined version so you can better reference it in your publications.

Follow these commands for the basic installation.

git clone -b dev https://github.com/FairRootGroup/FairSoft
cd FairSoft
source thisfairsoft.sh --setup
spack env create aug21 env/aug21/sim/spack.yaml
spack env activate aug21
spack install
cd ..
spack view --dependencies true symlink -i FairSoft-aug21 fairroot

spack install can take hours. For me, spack installs 145 packages and libraries, including Python.

Note: If you encounter a Permission Denied error when installing Geant4 data, in the file spack/lib/spack/llnl/util/filesystem.py, function copy_tree, change shutil.copy2 to shutil.copyfile.

spac view will create a folder that from now on acts both as SIMPATH and FAIRROOTPATH, which is needed for the installation of R3BRoot. Get the full path with cd FairSoft-aug21 && pwd.

Note: Setting the respective paths in your environment might lead to other software not working correctly.

Installing R3BRoot

First, get the latest dev version of R3BRoot. Currently, you also need another thing that, for no good reason, is not included in the repository.

git clone -b dev [email protected]:R3BRootGroup/R3BRoot.git
cd R3BRoot
git clone -b dev [email protected]:R3BRootGroup/macros.git

You should fork R3BRoot on GitHub and add this remote code location:

git remote add mine [email protected]:yourusername/R3BRoot.git

Check that both are active:

$ git remote -v
mine    [email protected]:yourusername/R3BRoot.git (fetch)
mine    [email protected]:yourusername/R3BRoot.git (push)
origin  [email protected]:R3BRootGroup/R3BRoot.git (fetch)
origin  [email protected]:R3BRootGroup/R3BRoot.git (push)

As you will be compiling R3BRoot over and over again, using a script is recommended. Place it in the R3BRoot folder as build-r3broot.sh and change the BASEPATH to match your installation:

#!/bin/bash
set -e

BASEPATH=/full/path/to/your/stuff
export SIMPATH=${BASEPATH}/FairSoft-aug21
export FAIRROOTPATH=${BASEPATH}/FairSoft-aug21

source ${SIMPATH}/bin/geant4.sh
source ${SIMPATH}/bin/thisroot.sh

# requires UCESB in ${BASEPATH}/ucesb and UPEXPS in ${BASEPATH}/upexps
# export UCESB_DIR=${BASEPATH}/ucesb

mkdir -p build
cd build
cmake .. -DUSE_DIFFERENT_COMPILER=TRUE
make -j4

And run:

chmod +x build-r3broot.sh
./build-r3broot.sh

After the build is completed, enable the environment macro and run the tests:

cd build
. ./config.sh
ctest