diff --git a/README.md b/README.md index 36833b6050d56f3d259d473652f91f549796836e..bfa9edaeb146bfbf338c5af2fdca213bbb30d706 100644 --- a/README.md +++ b/README.md @@ -5,25 +5,35 @@ Installation Instructions for for CbmRoot ## 1.1 Compiler -To be able to compile CbmRoot a compiler with full C++11 support is needed. +To be able to compile CbmRoot, a compiler with full C++11 support is needed. GCC since version 4.8 and clang since version 3.4 are known to work without problems. ## 1.2 FairSoft -To install, compile, and run CbmRoot several external programs are required. -This are for example Root, Geant3 or Geant4. The complete list can be found -on the FairRoot webpage (fairroot.gsi.de). Since most of these programs can't -be installed using the package manager of the used Linux distribution, or at -least can't be installed in the required version, the FairRoot team provides -a GIT repository with all needed packages and some scripts to automatically -build and install these so called external packages. +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: -Detailed instructions how to get and compile FairSoft (aka external packages) -can be found at the following webpage + 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 latest FairSoft relase version. Currently this is +"apr21p2", which is compatible with the latest version of CbmRoot. Different +combinations of older versions of FairSoft, FairRoot and CbmRoot may work in +principle, but are not endorsed or actively supported. + Please make sure SQLite is installed on your system before compiling FairSoft, as this is required by CbmRoot. Failing compile FairSoft with SQLite support will lead to a crash during the CbmRoot compilation. @@ -43,50 +53,103 @@ existing software. 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). -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 +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 package which meanwhile serves several +CbmRoot is based on FairRoot, a simulation, reconstruction and analysis +framework based on the ROOT system, which by now is used by several experiments as base for their developments. Beside FairSoft you need also -to install FairRoot to be able to compile CbmRoot +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 -Detailed instructions how to get and compile FairRoot can be found at the -following webpage +We again recommend this official repository as the primary source of +information, and recommend using the latest release version. + +Other information can be found at: https://redmine.cbm.gsi.de/projects/cbmroot/wiki/InstallFairRoot -# 2. Recommended versions +In order to compile FairRoot, you must set the environment variable SIMPATH +to contain the path to your FairSoft installation, i.e.: -GCC : >= 4.8 - or -Clang: >= 3.4 + export SIMPATH=[path_to_fairsoft] + +Not setting this variable (or FAIRROOTPATH, defined below) properly is a common +source of problems. + +# 2. Installing CbmRoot + +After installing FairSoft and FairRoot, to install CbmRoot first +create a local clone of the Git repository using: + + git clone git@git.cbm.gsi.de:computing/cbmroot.git + +Subsequently, create a build directory: + + mkdir build_cbmroot + +To proceed, you must set the environment variables SIMPATH and FAIRROOTPATH, +to the folders of your FairSoft and FairRoot installations, i.e. -FairSoft: jun19p2 + export SIMPATH=[path_to_fairsoft] + export FAIRROOTPATH=[path_to_fairroot install] -FairRoot: v18.2.1 +From your build directory, then call + + cmake [path_to_cbmroot] + make -j[number_of_cores] + +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. If you are using +a Bash shell, we recommend adding the following line to .bashrc to further automate +this step: + + source ~/build_cbmroot/config.sh > /dev/null 2>&1 # 3. Automatic installation To make the installation more easy we provide a script which automatically -gets and installs FairSoft, FairRoot, and CbmRoot in one go. The script -always take the correct FairSoft and FairRoot versions. -The full description of this process is at +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 -The one line command which has to be executed inside the CbmRoot source +The one-line command which has to be executed inside the CbmRoot source directory is - ./autoinstall_framework.sh 1 1 1 + ./autoinstall_framework.sh 1 1 1 + +The same scipt can be used to only install any subset of the three packages. See +the Redmine page or the script itself for further details. + +**(The auto-install script currently doesn't work with the latest version of FairSoft)** + +# 4. Recommended versions + +GCC : >= 4.8 + or +Clang: >= 3.4 + +FairSoft: apr21p2 + +FairRoot: v18.6.6 -# 4. Further remarks +# 5. Further remarks Compiling CbmRoot with multicore support using "make -j", without -specifying the number of threads is known to cause MacOS and Ubuntu +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.