Project

General

Profile

Installation » History » Version 3

Ole Hansen, 03/03/2018 11:35 AM

1 1 Ole Hansen
h1. Hall A C++ Analyzer Installation Guide
2
3
h2. General
4
5
The C++ Analyzer is a general-purpose data analysis framework built on top of ROOT. Because of the large number of possible combinations of ROOT versions and compilers, which are often not compatible at the binary level, it is easiest and least prone to error to build the Analyzer from source. (A precompiled version is installed in the Hall A counting house, however.) To build the Analyzer, please download the latest source distribution and follow the instructions below.
6
7
h2. System Requirements
8
9 2 Ole Hansen
* Linux or macOS.
10 3 Ole Hansen
* Reasonably powerful hardware (2GHz CPU, 2GB RAM). Less will work, but it won't be fun.
11 2 Ole Hansen
* 50 MB disk space to build the Analyzer. GBs of disk space for raw data files.
12 1 Ole Hansen
13
h2. Prerequisites
14
15
The following software must be installed and set up prior to unpacking and compiling the analyzer:
16
17
* "ROOT":https://root.cern.ch 5 or 6. Release 6.12/06 or higher recommended.
18
* Compilers: "gcc/g++":http://gcc.gnu.org C/C++ compiler 4.0 or higher, or "clang":https://clang.llvm.org 2.8 or higher, including Apple clang.
19
Important: this compiler must produce code that is binary-compatible with the installed version of ROOT!
20
* "SCons":http://scons.org 2.1 or later, or GNU make 3.76 or later
21
* gzip/gunzip.
22
* wget or curl (for downloading EVIO)
23
* Optional: "EVIO":https://coda.jlab.org/drupal/content/event-io-evio (any version). Make sure that the CODA environment variable points to the location of your installation. 
24
25
h2. Getting the analyzer source code
26
27
Source distributions can be downloaded from "here":http://hallaweb.jlab.org/podd/download/. Unpack the archive as usual:
28
<pre>
29
% tar xzf analyzer-1.6-beta3.tar.gz
30
</pre>
31
The sources will be unpacked into the subdirectory "analyzer-1.6". Go there
32
<pre>
33
% cd analyzer-1.6
34
</pre>
35
36
h2. Compilation
37
38
First, ensure that ROOT is properly set up. root-config must be in your PATH. Check this:
39
<pre>
40
% which root-config
41
/opt/ROOT/PRO/bin/root-config
42
</pre>
43
Also, check if you can start ROOT:
44
<pre>
45
% root
46
</pre>
47
If any of these checks fail, investigate. Consult your system administrator.
48
49
If you don't have EVIO installed already, the build system will download and build a local version of EVIO for you. You will need Internet connectivity to "GitHub":https://github.com/JeffersonLab/hallac_evio for this.
50
51
To build the analyzer, you can either use the traditional make system or the new SCons system. With make, Linux and macOS platforms should be detected and configured automatically. On these platforms, simply run
52
<pre>
53
% make -j
54
</pre>
55
56
(The "-j" flag instructs make to do a parallel build using all available CPU cores of your machine. This will greatly speed up the build on modern systems. You can omit the "-j" if you prefer. Please see the make documentation for more information.)
57
58
On other Unices (e.g. Solaris), you will have to provide an appropriate "ARCH" section in these two Makefiles:
59
<pre>
60
Makefile
61
hana_decode/Makefile
62
</pre>
63
64
SCons builds should in principle work on all Unix-like platforms where SCons is available. Note that SCons requires python >= 2.7. First, ensure that SCons is installed:
65
<pre>
66
% which scons
67
</pre>
68
If this returns nothing, you will have to install the appropriate package via your package manager (on Linux) or by some other means. SCons for macOS is available via "Homebrew":https://brew.sh/ (recommended), "MacPorts":https://www.macports.org/ or as a "standalone graphical installer":https://github.com/richard-viney/scons-mac-installer. You will need at least version 2.1. You can check the version with
69
<pre>
70
% scons --version
71
</pre>
72
73
To build with SCons, do
74
<pre>
75
% scons -j
76
</pre>
77
78
h2. Build problems
79
80
On rare occasions, your build may fail with weird error messages. For example, this may happen because ROOT wasn't set up correctly, you switched to a different ROOT version or to a ROOT installation in a different location, or you moved or copied your build directory. In such cases, try building again with a clean slate:
81
<pre>
82
% find . -name '*.d' -exec rm {} \;
83
% make realclean
84
% make
85
</pre>
86
or
87
<pre>
88
% scons -c
89
% scons
90
</pre>
91
92
Only if this fails, assume that there may be a real problem with the source code. Our releases are tested on RedHat and Ubuntu-based Linux distributions and recent macOS versions, so whatever problem there may be, it is likely due to a quirk of your particular setup. Please contact us with a bug report.
93
94
h2. Installation
95
96
To run the analyzer in an arbitrary directory, a number of environment variables need to be set up. Assuming you built the Analyzer in ~/analyzer-1.6, the setup would be as follows:
97
98
For bash (Linux default):
99
<pre>
100
% export LD_LIBRARY_PATH=~/analyzer-1.6:$ROOTSYS/lib
101
% export DB_DIR=~/analyzer-1.6/DB
102
% export PATH=~/analyzer-1.6:$PATH
103
</pre>
104
105
For tcsh (JLab CUE default):
106
<pre>
107
% setenv LD_LIBRARY_PATH ~/analyzer-1.6:${ROOTSYS}/lib
108
% setenv DB_DIR ~/analyzer-1.6/DB
109
% set path = ( ~/analyzer-1.6 $path )
110
</pre>
111
112
You probably want to put these definitions in your login script: ~/.bash_profile or ~/.login.
113
114
h2. Running
115
116
Go to your working directory and type:
117
<pre>
118
% analyzer
119
</pre>
120
or, if you did not modify the PATH:
121
<pre>
122
% ./analyzer
123
</pre>
124
You should see the startup message:
125
<pre>
126
  ************************************************
127
  *                                              *
128
  *            W E L C O M E  to  the            *
129
  *       H A L L A   C++  A N A L Y Z E R       *
130
  *                                              *
131
  *  Release     1.6.0-beta3         Dec 10 2015 *
132
  *  Based on ROOT  5.34/32          Jun 23 2015 *
133
  *                                              *
134
  *            For information visit             *
135
  *        http://hallaweb.jlab.org/podd/        *
136
  *                                              *
137
  ************************************************
138
139
CINT/ROOT C/C++ Interpreter version 5.18.00, July 2, 2010
140
Type ? for help. Commands must be C++ statements.
141
Enclose multiple statements between { }.
142
analyzer [0]
143
</pre>
144
145
Since the Analyzer is built on top of ROOT, you now have access to all ROOT commands from the Analyzer command prompt. Running the Analyzer is like running ROOT with a bunch of extra classes available. The special Analyzer classes are listed in the "Analyzer Class Index":http://hallaweb.jlab.org/podd/doc/html_v16/ClassIndex.html.
146
147
If you are a new user, you might want to look at the example scripts in the examples/ subdirectory of the distribution. Documentation of them can be found in the "Quickstart Guide":http://hallaweb.jlab.org/podd/doc/quickstart.html.
148
149
h2. Debugging (advanced)
150
151
Advanced users may be interested in creating a debug build. To do so with the make system, you need to edit the top-level Makefile and uncomment the following line
152
<pre>
153
#export DEBUG=1
154
</pre>
155
Also, ensure that WITH_DEBUG=1 is set. This will enable compilation of additional code sections that help with interactive debugging, such as extra error messages. This variable is set by default.
156
157
Once the Makefile has been updated, do
158
<pre>
159
% make clean
160
% make -j
161
</pre>
162
163
You might also want to use a debug-compiled version of ROOT or install an appropriate debuginfo package (e.g. root-debuginfo on RedHat systems using EPEL). Also, be sure to install glibc-debuginfo and glibc-debuginfo-common to get debug support for STL classes and other standard library features. None of these extra steps are necessary on Mac OSX, where the relevant bundles come with the required symbol tables included.
164
165
With the SCons system, creating a debug build is easier. Nothing needs to be edited, simply run
166
<pre>
167
% scons -j debug=1
168
</pre>
169
Of course, the same considerations regarding ROOT and glibc debuginfo apply as described above for make builds.
170
171
The recommended debugger is gdb on Linux (and older macOS such as 10.6) and lldb on newer macOS versions. To avoid problems with macOS's System Integrity Protection when using lldb, do not use /usr/bin/lldb directly, but instead create an alias to the command-line tools version, which isn't a specially-protected executable:
172
<pre>
173
alias lldb='/Library/Developer/CommandLineTools/usr/bin/lldb'
174
</pre>