1 Getting started

1.1 Using the toolkit in an interactive environment

Type kaliveda to launch the interactive C++ interpreter of ROOT with all the basic libraries of the toolkit already linked in and all necessary paths required for compilation of your code predefined. This is so that you can compile any code written using the KaliVeda toolkit on the command line in a kaliveda interactive session, just like you would with ROOT:

$ kaliveda

/----------------------------------------------------------------------\
| Welcome to KaliVeda 1.12/05             github:kaliveda-dev/kaliveda |
| (c) 2002-2022, The KaliVeda development team                         |
|                                                                      |
| Built with ROOT 6.24.06 on 2022-03-18, 10:11:25                      |
| From heads/master@release-1.12.05-g209ab9c0                          |
| See http://indra.in2p3.fr/kaliveda for help                          |
\----------------------------------------------------------------------/

kaliveda[0] .L MyClass.cpp+
Info in <TUnixSystem::ACLiC>: creating shared library ./MyClass_cpp.so

1.2 Finding your way around the installation

We provide the kaliveda-config command tool to inform about paths to different parts of the installation, compilation flags, etc. (it is based on the equivalent root-config command):

$ kaliveda-config --help
Usage: kaliveda-config [options]

  --version             Print the KaliVeda version
  --bindir              Print the executable directory
  --libdir              Print the library directory
  --incdir              Print the header directory
  --libs                Print linker directives for all libraries
  --builddir            Print the CMake build directory
  --srcdir              Print the source directory
  --gitinfos            Print the git branch and commit
  --examples            Print the examples directory
  --cflags              Print all flags for compiling (including ROOT flags)
  --linklibs            Print all directives for linking (including ROOT libs)
  --help                Print this message

Note that depending on the version of KaliVeda you are using, not all of the above options may be implemented.

1.3 Using KaliVeda outside of the interpreter

1.3.1 Compilation flags/options

If you want/need to compile code using the toolkit in stand-alone mode, you can use the kaliveda-config tool in order to obtain the necessary installation-dependent paths to header files and libraries. Given the following code:

// file: MyCode.cpp

#include "KVNucleus.h"

int main()
{
   KVNucleus xe("129Xe",49.9);
   KVNucleus sn("119Sn");
   KVNucleus CN = xe + sn;
   CN.Print();
}

this can be compiled and linked into an executable using the following command:

$ g++ MyCode.cpp `kaliveda-config --cflags --linklibs`

(we assume the g++ compiler; in reality you should use whatever compiler was used to compile ROOT, i.e. the result of root-config --cxx). Running the executable produces:

$ ./a.out 
KVNucleus Z=104 A=248 E*=2787.58
KVParticle mass=233900 Theta=0 Phi=0 KE=3368.84 Vpar=5.03395

Note that the above commands include also the required paths and libraries from ROOT, and are equivalent to

-I`kaliveda-config --incdir` `root-config --cflags` -L`kaliveda-config --libdir --libs` `root-config --glibs`

1.3.2 Use in a CMake project

The above method is unwieldy for anything more than a simple executable. It cannot be used to make shared libraries containing your own classes, for which you would also need to generate the associated ROOT dictionaries, etc.. Therefore we provide modules which enable KaliVeda to be used with the CMake build system. Note that our CMake modules transparently take care of certain incompatibilities between ROOT versions 5 and 6 (most notably dictionary generation), and can also be used just for this purpose.

Given the MyCode.cpp file above, the same executable can be built using cmake with the following configuration file CMakeLists.txt:

cmake_minimum_required(VERSION 2.8.11)

project(MyProject)

#------- locate KaliVeda installation
find_package(KaliVeda REQUIRED)
include(${KALIVEDA_USE_FILE})

#------- locate ROOT installation
find_package(ROOT REQUIRED)
include(SetUpROOTBuild)

add_executable(XeSn MyCode.cpp)
target_link_libraries(XeSn ${KALIVEDA_LIBRARIES})

Configuration of the build then proceeds like this (note that we strongly discourage in-source builds, the following is just a simplified example):

$ cmake .

-- The C compiler identification is GNU 9.3.0
-- The CXX compiler identification is GNU 9.3.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Found KaliVeda: [...] (found version 1.11.01)
-- Found ROOT version 6.20.99
-- SetUpROOTBuild : CMAKE_CXX_FLAGS =   -std=c++11 -pipe -fsigned-char -pthread
-- Configuring done
-- Generating done
-- Build files have been written to: [...]

After which your code can be compiled like so (note we are assuming a Unix Makefile build generator):

$ make
Scanning dependencies of target XeSn
[ 50%] Building CXX object CMakeFiles/XeSn.dir/MyCode.cpp.o
[100%] Linking CXX executable bin/XeSn
[100%] Built target XeSn

For more details (including how to make shared libraries of your own classes), see here.

1.4 Writing code with KaliVeda

1.4.1 Automatic class source code generator

KaliVeda provides a class which can write source code for other classes: KVClassFactory. At its simplest, only a class name and short description are required in order to generate a fully ROOT-compatible class from the KaliVeda command line. Giving a base class to derive your new class from will copy and implement all constructors from the base class:

kaliveda [0] KVClassFactory::MakeClass("MyClass", "A new class", "TNamed")
<KVClassFactory::WriteClassHeader> : File MyClass.h generated.
<KVClassFactory::WriteClassImp> : File MyClass.cpp generated.

will generate the following MyClass.h file (all constructors and destructors are inlined by default) which includes the beginning of a doxygen comment block to document your class:

#ifndef __MYCLASS_H
#define __MYCLASS_H

#include "TNamed.h"

/**
 \class MyClass
 \brief A new class

 Write a detailed documentation for your class here, see doxygen manual for help.

 \author John Frankland
 \date Wed Aug 12 14:28:34 2020
*/

class MyClass : public TNamed
{
public:
   MyClass()
   : TNamed()
   {
   }
   MyClass(const char* name, const char* title)
   : TNamed(name, title)
   {
   }
   MyClass(const TString& name, const TString& title)
   : TNamed(name, title)
   {
   }

   virtual ~MyClass()
   {
   }

   ClassDef(MyClass,1)//A new class
};

#endif

You can also add methods to your class before generating the code, or use template files to define complicated methods which can be reused in many classes. See the KVClassFactory documentation and the examples.

1.4.2 Useful C++ Pre-processor Symbols

The header file KVConfig.h which is configured and generated at build time contains several symbols which may be of help when writing your own code using KaliVeda. KVConfig.h is #included by most class headers in the toolkit; in case of doubt, just add #include "KVConfig.h" before your code.

The following symbols are mainly to ensure portability of code:

Symbol	Functionality
`WITH_GEMINI` `WITH_MFM` `WITH_ZMQ` `WITH_BOOST` etc. etc.	Defined when each specific piece of 3rd-party software is available
`WITH_MULTICORE_CPU`	Defined to number of cores
`WITH_CPP11` `WITH_CPP14` `WITH_CPP17`	C++11 language can be used C++14 & C++11 language can be used C++17,C++14 & C++11 can be used
`WITH_ROOT5`	Using a ROOT version before v6.00 [i.e. with CINT dictionaries]
`WITH_ROOT6`	ROOT v6.00 or later [i.e. with CLING dictionaries]

Example of use:

   KVEvent Event;  // some multi-particle event i.e. collection of nuclei
#ifdef WITH_CPP11
   // range-based for-loop and 'auto' variables: C++11 onwards
   for (auto& nuc : Event)
   {
      nuc.Print();   
   }
#else
   // standard for-loop with iterators for C++03 & before
   for (KVEvent::Iterator it = Event.begin(); it != Event.end(); ++it)
   {
      (*it).Print();
   }
#endif

The following macros simplify the addition of commonly-used/required methods to classes:

Macro	Equivalent code
`ROOT_DEF_CTOR(C,B)`	`C() : B() {}`
`ROOT_NAME_CTOR(C,B)`	`C(const Char_t* name) : B(name) {}`
`ROOT_DEF_CTOR_WITH_INIT(C,B)`	`C() : B() { init(); }`
`ROOT_NAME_CTOR(C,B)`	`C(const Char_t* name) : B(name) { init(); }`
`ROOT_COPY_CTOR(C,B)`	`C(const C& o) : B() { o.Copy(*this); }`
`ROOT_COPY_ASSIGN_OP(C)`	`C& operator=(const C& o) { if(this!=&o) o.Copy(this); return this; }`
`ROOT_FULL_SET(C,B)`	`ROOT_DEF_CTOR(C,B) ROOT_NAME_CTOR(C,B) ROOT_COPY_CTOR(C,B) virtual ~C() {} ROOT_COPY_ASSIGN_OP(C)`
`ROOT_FULL_SET_WITH_INIT(C,B)`	`ROOT_DEF_CTOR_WITH_INIT(C,B) ROOT_NAME_CTOR_WITH_INIT(C,B) ROOT_COPY_CTOR(C,B) virtual ~C() {} ROOT_COPY_ASSIGN_OP(C)`