Download/Install

Table of Contents

• Build from source
  • Prerequisites
    • Operating systems
    • Basic software requirements
    • ROOT requirements
  • Optional software
  • Building and installing
    • Build options
    • 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 --depth=1 https://gitlab.in2p3.fr/kaliveda-dev/kaliveda.git

(the depth=1 argument avoids downloading the full history of the git repository, which makes downloading much faster and lighter).

If you want to change the name of the resulting working directory, give the name you want as an extra argument:

$ git clone --depth=1 https://gitlab.in2p3.fr/kaliveda-dev/kaliveda.git kaliveda_sources

For more information, see the git documentation or type:

$ git help clone

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. The following ROOT libraries must be installed (most of them are installed by default):

• libRint.so
• libGraf.so
• libGeom.so
• libSpectrum.so
• libProof.so
• libProofPlayer.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
• libRSQLite.so or libSQLite.so - SQLite database interface

Optional software

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

• 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.

Building and installing

Only out-of-source builds are supported. 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 below by doing either

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

from outside the source directory, or

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

from inside 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 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, or

$ cmake -B ../build -DCMAKE_INSTALL_PREFIX=../install

from directory /home/user/kaliveda/sources.

Then compile and install the sources by doing

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

where [N] is the number of processors/cores on your PC (parallel build).

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 above..] -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

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.

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

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:

$ git pull
$ git submodule update

Warning

The second 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 CMake command to recompile the sources & update the installation:

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

with N the number of cores/CPU on your machine.

In case of problems with the build, delete the build directory and start again from the cmake step of Building and installing :

$ 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+