Hall A Analyzer

h1. Guide to Installing the Hall A C++ Analyzer From Source

h2. General

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 often the safest to build the Analyzer from source. (A precompiled version is installed in the Hall A counting house and on the JLab ifarm systems.) Build instructions follow.

h2. System Requirements

* Linux or macOS.

* Reasonably powerful hardware (multicore CPU, 2 GB RAM). Less may work, but it won't be fun.

* 50 MB disk space to build the Analyzer. GBs of disk space for raw data files.

h2. Prerequisites

Ensure the following is installed:

* "ROOT":https://root.cern version 6. Latest version recommended.

* Compilers: "gcc/g++":http://gcc.gnu.org C/C++ compiler 4.8 or higher, or "clang":https://clang.llvm.org 4 or higher, including Apple Clang 5 or higher.

Important: The installed version of ROOT must have been built with the same compiler!

* "CMake":https://cmake.org 3.5 or later (3.15 or higher recommended). Alternatively, "SCons":https://scons.org version 3 or higher.

* gzip/gunzip.

* wget or curl (for downloading EVIO)

* Optional: "EVIO":https://coda.jlab.org/drupal/content/event-io-evio version 5.3. The <code>CODA</code> environment variable should point to the location of your installation.

For ROOT, <code>root-config</code> must be in your <code>PATH</code>. Check this:

<pre>

% which root-config

/opt/ROOT/PRO/bin/root-config

</pre>

Also, check if you can start ROOT:

<pre>

% root

</pre>

If any of these checks fail, investigate. Consult your system administrator.

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.

[[ROOT Installation Guide]] 

h2. Getting the analyzer source code

Source distributions can be downloaded from "here":https://github.com/JeffersonLab/analyzer/releases. Unpack the archive:

<pre>

% tar xzf analyzer-1.7.0.tar.gz

</pre>

The sources will be unpacked into the subdirectory <code>analyzer-Release-170</code>. Go there

<pre>

% cd analyzer-Release-170

</pre>

Alternatively, you can clone the GitHub repository:

<pre>

% git clone --branch Release-170_patches https://github.com/JeffersonLab/analyzer 

</pre>

h2. Building and Installing

CMake is strongly recommended for building the analyzer, preferably CMake version 3.15 or higher. CMake automatically detects and configures the build environment in portable way. Additionally, it is a good idea to "install" the analyzer in a suitable directory from where it can be run; this allows several versions to be installed in parallel, for example. Each installation is self-contained (except for dependencies like ROOT), so the source directory can be moved, updated, or deleted at any time without affecting the installation. To set the installation location, point the CMake variable <code>CMAKE_INSTALL_PREFIX</code> to the desired top-level directory. For example

<pre>

% cmake -B build -S . -DCMAKE_INSTALL_PREFIX=~/JLab/Software/Podd/1.7.0

% cmake --build build -j

% cmake --install build

</pre>

This will put the analyzer in <code>~/JLab/Software/Podd/1.7.0/{bin,lib,include}</code>. The <code>-j</code> flag instructs make to do a parallel build using all available CPU cores of your machine. This will greatly speed up the build on multicore systems.

The analyzer's CMake build system supports a number of options that can be set at configuration time:

* <code>WITH_DEBUG</code>: Enables additional debug messages. ON by default.

* <code>PODD_SET_RPATH</code>: Set RPATH on executables so that there is no need to set <code>(DY)LD_LIBRARY_PATH</code> to run the installed analyzer. ON by default.

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, simply delete the build directory completely (<code>build</code> in the example above).

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.

h2. Installation

As already explained above, it is recommended to install the analyzer in a suitable location from where it can be run. Use the <code>cmake --install <build_dir></code> command to do the installation. If the <code>PODD_SET_RPATH</code> CMake option is enabled (the default), the analyzer will run without further configuration from the installation location. Optionally, one can set a number of environment variables. Assuming <code>CMAKE_INSTALL_PREFIX</code> was set to <code>~/JLab/Software/Podd/1.7.0</code>, one can set

For bash (Linux default):

<pre>

% export ANALYZER=~/JLab/Software/Podd/1.7.0

% export PATH=$ANALYZER/bin:$PATH

% export LD_LIBRARY_PATH=$ANALYZER/lib64:$LD_LIBRARY_PATH

</pre>

For tcsh (JLab CUE default):

<pre>

% setenv ANALYZER ~/JLab/Software/Podd/1.7.0

% set path = ( ${ANALYZER}/bin $path )

% setenv LD_LIBRARY_PATH ${ANALYZER}/lib64:${LD_LIBRARY_PATH}

</pre>

You probably want to put these definitions in your login script: ~/.bash_profile or ~/.login.

h2. Running

If the <code>PATH</code> has been set to include <code>$ANALYZER/bin</code>, all you have to do is type

<pre>

% analyzer

</pre>

You should see the startup message:

<pre>

  ************************************************

  *                                              *

  *            W E L C O M E  to  the            *

  *       H A L L A   C++  A N A L Y Z E R       *

  *                                              *

  *  Release     1.7.0               Nov 16 2021 *

  *  Based on ROOT    6.26/02        12 Apr 2022 *

  *                                              *

  *            For information visit             *

  * https://redmine.jlab.org/projects/podd/wiki/ *

  *                                              *

  ************************************************

analyzer [0]

</pre>

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.

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.

h2. Debugging (advanced)

The build type ("Release", "Debug", etc.) can be set via the CMake variable CMAKE_BUILD_TYPE. Please consult the "CMake documentation":https://cmake.org/cmake/help/latest for more information.

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

<pre>

export DEBUG=1

</pre>

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.

Once the Makefile has been updated, do

<pre>

% make clean

% make -j

</pre>

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.

With the SCons system, creating a debug build is easier. Nothing needs to be edited, simply run

<pre>

% scons -j debug=1

</pre>

Of course, the same considerations regarding ROOT and glibc debuginfo apply as described above for make builds.

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:

<pre>

alias lldb='/Library/Developer/CommandLineTools/usr/bin/lldb'

</pre>