Download/Install

Table of Contents

• Build from source
  • Prerequisites
    • Operating systems
    • Basic software requirements
    • ROOT requirements
  • Optional software
    • Build options
  • Building and installing
    • Configuring the build
    • Compile and install
    • Installation directories
  • Setting up the environment
  • Keeping up to date
    • Updating the submodules/datasets
    • Recompiling after updates
• Docker containers

If you want to use or try out KaliVeda, several options exist:

• build & install from source
• use in a container (Docker)

Build from source

The source code can be obtained from the git repository https://gitlab.in2p3.fr/kaliveda-dev/kaliveda :

$ git clone https://gitlab.in2p3.fr/kaliveda-dev/kaliveda.git

This will download the sources into a new directory called kaliveda in your current working directory. If you want to download to a different directory, which may or may not already exist, just give the path name as a second argument after the repository URL:

$ git clone https://gitlab.in2p3.fr/kaliveda-dev/kaliveda.git my_kaliveda_sources

This will create my_kaliveda_sources in the current working directory and download the sources there.

As development is always ongoing, several branches are available. When you clone the repository, you get the current default branch, which may not be the one you want/need:

Branch name	Version	Notes
main	1.15	current default: includes new datasets E881 & E884
1.14	1.14	can be used with data up to E818
1.12	1.12	old version used for E789
1.10	1.10	legacy support for INDRA-VAMOS data

If you don't want the default branch, just change your current working directory to the directory where you downloaded the sources

$ cd my_kaliveda_sources

and then execute the following command with the name of the branch you want, e.g. to change to the 1.14 branch:

$ git checkout 1.14

Prerequisites

KaliVeda is an object-oriented toolkit written in (mostly) C++ and based on ROOT, so the prerequisites for building and installing it are basically the same as those for ROOT: if you can build and install a functioning version of ROOT on your machine, you should be able to build and install KaliVeda.

Operating systems

Linux (Ubuntu, Scientific Linux, CentOS, Debian, ...) and MacOS X operating systems are supported. No support for Windows.

Basic software requirements

• cmake (version >= 3.13)
• ROOT (version >= 6.22)
• C/C++/Fortran compilers (the same as used to build ROOT)

For the other required software see the prerequisites for ROOT for your OS.

ROOT requirements

Only ROOT versions >= 6.22 are supported. Note that for ROOT versions >= 6.32, PROOF and PROOFLite are no longer enabled by default (or may simply be removed). We recommend using a ROOT version which has PROOF/PROOFLite support built-in.

The following ROOT libraries must be installed (most of them are installed by default):

• libRint.so
• libGraf.so
• libGeom.so
• libSpectrum.so
• libPhysics.so
• libHist.so
• libRIO.so
• libTree.so
• libMathCore.so
• libMatrix.so
• libGpad.so
• libGui.so
• libNet.so
• libGraf3d.so
• libThread.so

The following ROOT libraries are recommended but not compulsory:

• libRGL.so - OpenGL support
• libMinuit.so - data-fitting library
• libRooFit.so & libRooFitCore.so - advanced data-fitting library
• libProof.so
• libProofPlayer.so
• libRSQLite.so or libSQLite.so - SQLite database interface

Note that we recommend using ROOT with built-in SQLite support; if not, we can provide built-in sqlite functionality if the required packages are present on the system (see below). Note that if you use a pre-compiled version of ROOT with SQLite support, you should ensure that the necessary SQLite packages are installed on your system (see below).

Optional software

Other optional software packages which may add more functionality to KaliVeda if installed before building include:

• sqlite

  We highly recommend to use a version of ROOT with built-in SQLite support (see above); if this is not possible, we provide a drop-in replacement for it, as long as sqlite (more precisely, the necessary development package, e.g. on Ubuntu, libsqlite3-dev) is installed on the system. If you use a pre-compiled version of ROOT with SQLite support, you should also ensure that these packages are present on your system.

• Google Protocol buffers

  Raw FAZIA data is written using Google protocol buffers. Installation of the software for reading the buffers is mandatory if you want to read raw FAZIA data.

Build options

The list of options which can be used to configure the build are given here, with their default values in brackets. Example of use:

$ cmake [..see next subsection..] -D[option1]=[YES|NO] -D[option2]=[ON|OFF] [...]

Option	Default	Meaning
WITH_INDRA_DATASETS	OFF	download & install datasets for INDRA experiments
WITH_FAZIA_DATASETS	OFF	download & install datasets for FAZIA experiments
WITH_INDRA_FAZIA_DATASETS	OFF	download & install datasets for INDRA-FAZIA experiments
WITH_ALL_DATASETS	OFF	download & install all datasets listed above
USE_GEMINI	OFF	build KVGemini interface to built-in Gemini++ statistical decay code
USE_MFM	OFF	use library for reading GANIL acquisition data in MFM format
USE_PROTOBUF	OFF	use Google protocol buffers e.g. for reading raw FAZIA data
USE_MESYTEC	OFF	enable support for reading (INDRA) data from Mesytec DAQ electronics
USE_FITLTG	OFF	build Tassan-Got package for fitting identification grids (see KVTGID)
USE_MICROSTAT	OFF	build libraries for generation of events with different statistical weights see MicroStat Package
USE_BUILTIN_GRU	OFF	build own library for reading legacy GANIL acquisition data (not MFM format)
ENABLE_ALL_OPTIONS	OFF	enable all USE_* options listed above
USE_SQLITE	ON	enable SQLite database interface KVSQLite, if SQLite3 available
CCIN2P3_BUILD	OFF	configure build for IN2P3 Computing Centre environment
ONLINE_TOOLS	OFF	build & install tools used during experiment data taking

Note

KaliVeda can be compiled without SQLite support, but certain functionalities will be degraded: most notably, it is impossible to handle or read data without SQLite support.

Warning

Contrary to previous versions (<1.14) of KaliVeda, the files required to handle different datasets from INDRA, FAZIA or INDRA-FAZIA experiments (which includes just being able to build the multidetector array(s) used in each case) are not installed by default. Only experiments for which the corresponding WITH_*_DATASETS=ON build option (see above) is given will be installed.

For full details on the build system and available options, see Appendix: KaliVeda build system.

Building and installing

Only out-of-source builds are supported: this means that the "build directory" must be in a path which is completely outside the path to the source directory. As good practice, the "installation directory" should also be completely outside both source and build directory paths. Once compiled and installed, you should be able to delete both the source directory and build directory without affecting the installed executables and libraries.

Configuring the build

Let us suppose that the sources were cloned from the git repository to a local directory S. With a "build directory" B (where the sources are to be compiled) and an "install directory" I (where the compiled libraries and executables etc. are to be installed), configure the build using the options detailed in Build options above by doing

$ cmake -S [S] -B [B] -DCMAKE_INSTALL_PREFIX=[I] [other build options...]

in a working directory outside the source directory, , with [B], [S] and [I] replaced by the respective (relative or absolute) paths to the build, source and installation directories.

For example, if you cloned the git repository into S=/home/user/kaliveda/sources (see Build from source for how to choose the name of the directory you download the sources to with git clone) and want to install in I=home/user/kaliveda/install, you could do

$ cmake -S kaliveda/sources -B kaliveda/build -DCMAKE_INSTALL_PREFIX=kaliveda/install

from directory /home/user, or

$ cmake -S sources -B build -DCMAKE_INSTALL_PREFIX=install

from directory /home/user/kaliveda.

Compile and install

After successful configuration of the build, compile and install the code by doing

$ cmake --build [B] --target install --parallel [N]

where [N] is the number of processors/cores you want to use for parallel compilation of the code, or, assuming you have a standard Linux environment which uses GNU Makefiles by default,

$ cd [B]
$ make -j [N] install

Installation directories

The default layout for the installation is

bin/
include/
  kaliveda/
lib/
  kaliveda/
  cmake/
share/
  doc/
    kaliveda/
  examples/
    core/
    ...
  kaliveda/
    data/
    etc/
    templates/
    [dataset1]/
    [dataset2]/
...
  man/
    man1/

This allows to install KaliVeda inside system directories, e.g. /usr/local, as any files generated during use of KaliVeda are written in a user-specific "working directory" which by default is created in $HOME/.kaliveda.

Setting up the environment

After building and installing the toolkit, quite a large number of environment variables need to be updated in order to be able to use KaliVeda. To do this execute one of the following shell scripts which can be found in the bin directory of your installation:

### sh/bash shells - i.e. 'echo $SHELL' prints '/bin/sh', '/bin/bash', or equivalent
$ source [path to install]/bin/thiskaliveda.sh
 
### csh/tcsh shells - i.e. 'echo $SHELL' prints '/bin/csh', '/bin/tcsh', or equivalent
$ source [path to install]/bin/thiskaliveda.csh

To set up the environment every time you login/open a terminal, add the following commands to the appropriate start-up script depending on your shell:

### sh/bash shells - add to '.bashrc', '.profile', or equivalent
$ source [path to install]/bin/thiskaliveda.sh
 
### csh/tcsh shells - add to '.chsrc' or equivalent
$ source [path to install]/bin/thiskaliveda.csh [path to install]

Note

For (t)csh shells the installation path must be given as argument to the thiskaliveda.chs script

The environment variable KVROOT will be set with the path to the root of your installation directory (equivalent to ROOTSYS for ROOT).

Keeping up to date

In order to update the source code to the latest version in the gitlab repository, go to the source directory S (see Building and installing above) and do the following:

$ cd [S]
$ git pull
$ git submodule update

Warning

The last command is mandatory to update any datasets you may have configured in your sources (see Build options). Without it, the dataset directories will not receive the latest updates and your sources may be left in an incoherent state. Read the next subsection for more details.

Updating the submodules/datasets

If one or more of the dataset submodules which you have configured in your source tree have been updated, when you run the git pull command you will see something like:

$ git pull
remote: Enumerating objects: 10, done.
remote: Counting objects: 100% (10/10), done.
remote: Compressing objects: 100% (7/7), done.
remote: Total 7 (delta 5), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (7/7), 1.22 KiB | 416.00 KiB/s, done.
From https://gitlab.in2p3.fr/kaliveda-dev/kaliveda
   63f1900..c9cee5b  dev        -> origin/dev
Updating 63f1900..c9cee5b
Fast-forward
 datasets/INDRA   |  2 +-
 release_notes.md | 24 +++++++++++++++++++++++-
 2 files changed, 24 insertions(+), 2 deletions(-)

which indicates that datasets/INDRA has updates. If you run git status at this point (after having configured it to show informations on submodule changes, by doing:

$ git config --global status.submoduleSummary true

) then you will see something like:

On branch dev
Your branch is up-to-date with 'origin/dev'.
 
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   datasets/INDRA (new commits)
 
Submodules changed but not updated:
 
* datasets/INDRA cf08b50...b010e5e (1):
  < [CAMP2]: complete CsI calibrations for INDRA rings 2-9
 
no changes added to commit (use "git add" and/or "git commit -a")

which can be very confusing: you just did a git pull which went well (apparently), and yet there are now uncommitted changes in your working copy? No, not at all: unlike for ordinary files (e.g. release_notes.md in the above example), submodule changes are not automatically applied when git pull is run. Instead you have to manually update the submodule(s) with

$ git submodule update
Submodule path 'datasets/INDRA': checked out 'cf08b502aa7791e0c262e583dff5678bfe5f5d54'

and then everything is fine:

$ git status
On branch dev
Your branch is up-to-date with 'origin/dev'.

Recompiling after updates

In most cases it is sufficient to re-run the previous Compile and install command to recompile the sources & update the installation, i.e. either do

$ cmake --build [B] --target install --parallel [N]

or

$ cd [B]
$ make -j [N] install

in both cases[N] is the number of cores/CPU to use for parallel compilation.

In case of problems with the build, delete the build directory and start again from the Configuring the build step, e.g.:

$ rm -rf [B]
$ cmake -S [S] -B [B] -DCMAKE_INSTALL_PREFIX=[I] [..your build options here..]
$ cmake --build [B] --target install --parallel [N]

Docker containers

Continuously updated & tagged Docker containers for the latest version of KaliVeda are available from gitlab-registry.in2p3.fr/kaliveda-dev/dockers (see here for list of all available containers). See the Docker documentation if you are new to Docker containers.

To download and use the latest version of kaliveda (this corresponds to the tip of the dev branch: see https://gitlab.in2p3.fr/kaliveda-dev/kaliveda for details) you can do:

$ docker pull gitlab-registry.in2p3.fr/kaliveda-dev/dockers/kaliveda

You can then run the kaliveda command-line interface with

$ docker run --rm -it \
   --user $(id -u):$(id -g) \
   gitlab-registry.in2p3.fr/kaliveda-dev/dockers/kaliveda

To have access to your HOME directory from within the container (and start kaliveda with this directory as your working directory):

$ docker run --rm -it \
   --user $(id -u):$(id -g) \
   -v $HOME:/home/$USER -w /home/$USER \
   gitlab-registry.in2p3.fr/kaliveda-dev/dockers/kaliveda

Finally, in order to use the graphical interfaces provided by either ROOT or KaliVeda, you can do

$ docker run --rm -it \
   --user $(id -u):$(id -g) \
   -v $HOME:/home/$USER -w /home/$USER \
   -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
   gitlab-registry.in2p3.fr/kaliveda-dev/dockers/kaliveda

Note that the graphical display only works if the host machine is running either an X11/Xorg or XWayland display server (Wayland is the default display for Ubuntu since 22.04, and by default XWayland should be installed and running; on earlier versions Xorg was the default. You can also use one of the legacy Xorg Ubuntu desktops).

Making an alias to one of the above commands, e.g. such as

$ alias kaliveda='docker run --rm -it \
   --user $(id -u):$(id -g) \
   -v $HOME:/home/$USER -w /home/$USER \
   gitlab-registry.in2p3.fr/kaliveda-dev/dockers/kaliveda'

you can then use the container as if the kaliveda executable had been compiled and installed on your PC:

$ kaliveda
 
$ kaliveda some_file.root
 
$ kaliveda my_script.C+