README.md 7.88 KB
Newer Older
Administrator's avatar
Administrator committed
1
Installation Instructions for for CbmRoot
2
=========================================
3

4
5
6
7
8
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.

9
# 1. Dependencies
10

11

12
## 1.1 Compiler
13

14
15
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.
Administrator's avatar
Administrator committed
16

17

18
## 1.2 FairSoft
19

Administrator's avatar
Administrator committed
20
To install, compile, and run CbmRoot, several external programs are required.
Dominik Smith's avatar
Dominik Smith committed
21
These are for example Root, Geant3 or Geant4 and many others. Installing these
Administrator's avatar
Administrator committed
22
23
24
25
26
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
Dominik Smith's avatar
Dominik Smith committed
27
the contained packages, can be found on the project's GitHub page:
28

Administrator's avatar
Administrator committed
29
  https://github.com/FairRootGroup/FairSoft
Dominik Smith's avatar
Dominik Smith committed
30
31

This page should be considered the primary source of information regarding FairSoft,
Administrator's avatar
Administrator committed
32
33
which takes precedence over any others (which may in some cases be outdated).
Additional information, for instance regarding older versions, can be found on
34
CBM Redmine:
35
36
37

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

Administrator's avatar
Administrator committed
38
We recommend to always use the latest FairSoft release version. Currently this is
Dominik Smith's avatar
Dominik Smith committed
39
"apr21p2", which is compatible with the latest version of CbmRoot. Different
Administrator's avatar
Administrator committed
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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 to compile FairSoft
with SQLite support will lead to a crash during the CbmRoot compilation
which results in a complete reinstallation of FairSoft and FairRoot after
the package was installed.
There have also been reports about problems with other missing packages.
Mainly these were the Threading Building Blocks (tbb) and the GNU Scientific
Library.
Since these packages may be missing in the instructions from the FairRoot
webpage please install them using the following commands depending on your
OS.
54
55
56
57

Debian/Ubuntu:

    sudo apt install sqlite3 libsqlite3-dev
Administrator's avatar
Administrator committed
58
59
    sudo apt install libgsl-dev
    sudo apt install libtbb-dev
60
61
62
63

OpenSuse:

    sudo zypper install sqlite3 sqlite3-devel
Administrator's avatar
Administrator committed
64
65
66
67
68
69
70
71
    sudo zypper install gsl-devel
    sudo zypper install tbb-devel

Fedora:

    sudo dnf install sqlite-devel
    sudo dnf install gsl-devel
    sudo dnf install tbb-devel
72

Administrator's avatar
Administrator committed
73
74
75
76
77
78
79
80
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 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).
81

Dominik Smith's avatar
Dominik Smith committed
82
The compilation of FairSoft is the most time-consuming part of the CbmRoot installation
Administrator's avatar
Administrator committed
83
84
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
Dominik Smith's avatar
Dominik Smith committed
85
the following wiki page
86
87
88

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

89
## 1.3 FairRoot
90

Administrator's avatar
Administrator committed
91
92
93
94
CbmRoot is based on FairRoot, a simulation, reconstruction and analysis
framework based on the ROOT system, which by now is also used by several other experiments
as base for their developments. Beside FairSoft you need also to install FairRoot to be able
to compile CbmRoot.
Dominik Smith's avatar
Dominik Smith committed
95
96
97
98
99

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

  https://github.com/FairRootGroup/FairRoot
100

Dominik Smith's avatar
Dominik Smith committed
101
We again recommend this official repository as the primary source of
Administrator's avatar
Administrator committed
102
information, and recommend using the latest release version.
Dominik Smith's avatar
Dominik Smith committed
103

Administrator's avatar
Administrator committed
104
Other information can be found at:
105
106
107

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

Dominik Smith's avatar
Dominik Smith committed
108
109
In order to compile FairRoot, you must set the environment variable SIMPATH
to contain the path to your FairSoft installation, i.e.:
110

Dominik Smith's avatar
Dominik Smith committed
111
112
113
    export SIMPATH=[path_to_fairsoft]

Not setting this variable (or FAIRROOTPATH, defined below) properly is a common
Administrator's avatar
Administrator committed
114
source of problems.
Dominik Smith's avatar
Dominik Smith committed
115
116
117
118

# 2. Installing CbmRoot

After installing FairSoft and FairRoot, to install CbmRoot first
Administrator's avatar
Administrator committed
119
120
create a local clone of the Git repository using:

121
    git clone https://git.cbm.gsi.de/computing/cbmroot
Dominik Smith's avatar
Dominik Smith committed
122
123
124
125

Subsequently, create a build directory:

    mkdir build_cbmroot
Administrator's avatar
Administrator committed
126

Dominik Smith's avatar
Dominik Smith committed
127
To proceed, you must set the environment variables SIMPATH and FAIRROOTPATH,
Administrator's avatar
Administrator committed
128
to the folders of your FairSoft and FairRoot installations, i.e.
129

Dominik Smith's avatar
Dominik Smith committed
130
131
    export SIMPATH=[path_to_fairsoft]
    export FAIRROOTPATH=[path_to_fairroot install]
132

Dominik Smith's avatar
Dominik Smith committed
133
134
135
136
137
From your build directory, then call

    cmake [path_to_cbmroot]
    make -j[number_of_cores]

Administrator's avatar
Administrator committed
138
After your build is complete, before running any part of CbmRoot from a shell,
Dominik Smith's avatar
Dominik Smith committed
139
140
141
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
Administrator's avatar
Administrator committed
142
a Bash shell, you can  add the following line to .bashrc to further automate
Dominik Smith's avatar
Dominik Smith committed
143
144
145
this step:

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

Administrator's avatar
Administrator committed
147
148
149
150
151
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.

152
# 3. Automatic installation
153
154

To make the installation more easy we provide a script which automatically
Dominik Smith's avatar
Dominik Smith committed
155
compiles and installs FairSoft, FairRoot, and CbmRoot in one go. The script
Administrator's avatar
Administrator committed
156
157
always combines the correct FairSoft and FairRoot versions. The full description
of this process is at
158
159
160

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

161
162
163
164
165
166
167
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

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

Administrator's avatar
Administrator committed
169
170
    ./autoinstall_framework.sh --fairsoft --fairroot --cbmroot

171
172
173
174
175
176
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

Administrator's avatar
Administrator committed
177
178
179
180
181
182
183
184
185
186
187
188
189
190
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
Dominik Smith's avatar
Dominik Smith committed
191

Administrator's avatar
Administrator committed
192
193
194
195
196
| OS            | FairSoft   | FairRoot |
|---------------|------------|----------|
| Ubuntu 20.04  | apr21p2    | v18.6.7  |
| OpenSuse 15.4 | apr21p2    | v18.6.7  |
| Fedora 35     | apr21p2    | v18.6.7  |
Dominik Smith's avatar
Dominik Smith committed
197
198
199

# 4. Recommended versions

Administrator's avatar
Administrator committed
200
GCC  : >= 7
Dominik Smith's avatar
Dominik Smith committed
201
  or
Administrator's avatar
Administrator committed
202
Clang: >= 6
Dominik Smith's avatar
Dominik Smith committed
203
204
205

FairSoft: apr21p2

Administrator's avatar
Administrator committed
206
FairRoot: v18.6.7
207

Dominik Smith's avatar
Dominik Smith committed
208
# 5. Further remarks
209

Administrator's avatar
Administrator committed
210
211
212
213
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.