# First steps with ROOT

Note

Before using ROOT, it must be installed successfully and all environment variables must be set. → See Installation Guide.

In particular it is recommended to put the following command into the .profile or .login file in order to have the environment variables properly defined at each login.

source /path/to/install-or-build/dir/bin/thisroot.sh


## Starting and quitting a ROOT session

### Starting ROOT

You start ROOT at the system prompt.

Type at the system prompt:

$root  The ROOT prompt is displayed.  ------------------------------------------------------------------ | Welcome to ROOT 6.20/00 https://root.cern | | (c) 1995-2019, The ROOT Team; conception: R. Brun, F. Rademakers | | Built for macosx64 on Oct 30 2019, 08:24:09 | | From heads/master@v6-19-01-1850-gab67fd5a5d | | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q' | ------------------------------------------------------------------ root [0]  To see a list of ROOT commands, type: .help  A list of ROOT commands is displayed.  Cling (C/C++ interpreter) meta commands usage All commands must be preceded by a '.', except for the evaluation statement { } ============================================================================== Syntax: .Command [arg0 arg1 ... argN] .L <filename> - Load the given file or library .(x|X) <filename>[args] - Same as .L and runs a function with signature: ret_type filename(args) .> <filename> - Redirect command to a given file '>' or '1>' - Redirects the stdout stream only '2>' - Redirects the stderr stream only '&>' (or '2>&1') - Redirects both stdout and stderr '>>' - Appends to the given file .undo [n] - Unloads the last 'n' inputs lines .U <filename> - Unloads the given file .I [path] - Shows the include path. If a path is given - adds the path to the include paths .O <level> - Sets the optimization level (0-3) (not yet implemented) .class <name> - Prints out class <name> in a CINT-like style .files - Prints out some CINT-like file statistics .fileEx - Prints out some file statistics .g - Prints out information about global variable 'name' - if no name is given, print them all .@ - Cancels and ignores the multiline input .rawInput [0|1] - Toggle wrapping and printing the execution results of the input .dynamicExtensions [0|1] - Toggles the use of the dynamic scopes and the late binding .printDebug [0|1] - Toggles the printing of input's corresponding state changes .storeState <filename> - Store the interpreter's state to a given file .compareState <filename> - Compare the interpreter's state with the one saved in a given file .stats [name] - Show stats for internal data structures 'ast' abstract syntax tree stats 'asttree [filter]' abstract syntax tree layout 'decl' dump ast declarations 'undo' show undo stack .help - Shows this information .q - Exit the program ROOT special commands. ========================================================================== .pwd : show current directory, pad and style .ls : list contents of current directory .which [file] : shows path of macro file .help Class : opens the reference guide for that class .help Class::Member : opens the reference guide for function/member  ### Starting ROOT with command line options You can start ROOT with the following command line options: -b ROOT session runs in batch mode, without graphics display. This mode is useful in case you do not want to set the DISPLAY. -n Does not execute the logon script and logoff script as specified in .rootrc. -q Exits after processing the command line macro files. -l Do not show the ROOT banner. -a Show the ROOT splash screen. -x Exit on exception. dir If dir is a valid directory, change to it (cd) before executing ROOT. -? Print usage. -h Print usage. --help Print usage. -config Print ./configure options. -memstat Run ROOT with memory usage monitoring. ### Quitting ROOT Type at the ROOT prompt: .q  ## Using the interactive C++ interpreter Cling ROOT uses the interactive C++ interpreter Cling that is built on top of the Low Level Virtual Machine (LLVM) and the Clang libraries. Cling provides command line prompt and a just-in-time (JIT) compiler for compilation. Note When using the interactive interpreter Cling, unlike to pure C++ language, no semicolon (;) is required at the end of the line. ### Simple commands You can use ROOT to execute simple commands on the ROOT prompt. Every command typed at the ROOT prompt is stored in the .root_hist file in your home directory. Examples Simple operations: Relational operators: Calling a function from a ROOT class like TMath::Pi. ### Multi-line commands You can use ROOT to execute multi-line commands on the ROOT prompt. 1. To begin a multi-line command, type at the ROOT prompt:{ 2. Type one command per line. 3. To end the multi-line command, type:} Example ## ROOT macros A ROOT macro contains pure C++ code, which additionally can contain ROOT classes and other ROOT objects (→ see ROOT classes, data types and global variables). A ROOT macro can consist of simple or multi-line commands, but also of arbitrarily complex class and function definitions. ROOT provides a lot of tutorials that are available as ROOT macros (→ see ROOT tutorials). You can save a ROOT macro in a file and execute it at the ROOT prompt or the system prompt. ### Creating ROOT macros The name of the ROOT macro and the file name (without file extension) in which the macro is saved must match. 1. Create a new file in your preferred text editor. 2. Use the following general structure for the ROOT macro: 1. Save the file ROOT macro, using the macro name as file name: MacroName.C ### Executing ROOT macros You can execute a ROOT macro: • at the system prompt, • at the ROOT prompt, • by loading it to a ROOT session. To execute a ROOT macro at the system prompt, type:  root MacroName.C  –or– To execute a ROOT macro at the ROOT prompt, type:  .x MacroName.C  – or – To load a ROOT macro to a ROOT session, type (at the ROOT prompt):  .L MacroName.C MacroName()  Note You can load multiple ROOT macros, as each ROOT macro has a unique name in the ROOT name space. In addition, you can: Executing a ROOT macro from a ROOT macro You can execute a ROOT macro conditionally inside another ROOT macro. ProcessLine() takes a parameter, which is a pointer to an int or to a TInterpreter::EErrorCode to let you access the interpreter error code after an attempt to interpret. This contains the error as defined in enum TInterpreter::EErrorCode with TInterpreter::kSuccess as being the value for a successful execution. Example The example $ROOTSYS/tutorials/tree/cernstaff.C calls a ROOT macro to build a ROOT file, if it does not exist.

Executing a ROOT macro from the invocation of ROOT

You can pass a macro to ROOT in its invocation.

Example

The exact kind of quoting depends on the used shell. This example works for bash-like shells.

   $root -l -b 'myCode.C("some String", 12)'  ### Compiling ROOT macros You can use ACLiC (Compiling Your Code) to compile your code and build a dictionary and a shared library from your ROOT macro. ACliC is implemented in TSystem::CompileMacro(). When using ACliC, ROOT checks what library really needs to be build and calls your system’s C++ compiler, linker and dictionary generator. Then ROOT loads a native shared library. ACLiC executes the following steps: 1. Calling rootcling to create a dictionary. 2. Calling the system’s C++ compiler to build the shared library. 3. If there are errors, it calls the C++ compiler to build a dummy executable to clearly report the unresolved symbols. ACLiC adds the classes and functions declared in included files with the same name as the ROOT macro files with one of following extensions: .h, .hh, .hpp, .hxx, .hPP, .hXX. This means that, by default, you cannot combine ROOT macros from different files into one library by using #include statements; you will need to compile each ROOT macro separately. #### Compiling a ROOT macro with ACLiC Before you can compile your interpreted ROOT macro, you need to add the include statements for the classes used in the ROOT macro. Only then you can build and load a shared library containing your ROOT macro. You can compile a ROOT macro with: • default optimizations • optimizations • debug symbols Compilation ensures that the shared library is rebuilt. Note Do not call ACLiC with a ROOT macro that has a function called main(). To compile a ROOT macro and build a shared library, type:  root[] .L MyScript.C+  The + option compiles the code and generates a shared library. The name of the shared library is the filename where the dot before the extension is replaced by an underscore. In addition, the shared library extension is added. Example On most platforms, hsimple.cxx will generate hsimple_cxx.so. The + command rebuilds the library only if the ROOT macro or any of the files it includes are newer than the library. When checking the timestamp, ACLiC generates a dependency file, which name is the same as the library name, just replacing the so extension by the extension d. To compile a ROOT macro with default optimizations, type:  root[] .L MyScript.C++g  To compile a ROOT macro with optimizations, type:  root[] .L MyScript.C++O  To compile a ROOT macro with debug symbols, type:  root[] .L MyScript.C++  #### Generating dictionaries A dictionary (“reflection database”) contains information about the types and functions that are available in a library. With a dictionary you can call functions inside libraries. They are also needed to write a class into a ROOT file. A dictionary consists of a source file, which contains the type information needed by Cling and ROOT’s I/O subsystem. This source file needs to be generated from the library’s headers and then compiled, linked and loaded. Only then does Cling and ROOT know what is inside a library. There are two ways to generate a dictionary: • using ACLiC • using rootcling Using ACLiC to generate dictionaries With a given header file MyHeader.h, ACliC automatically generates a dictionary:  root[] .L MyHeader.h+  Using rootcling to generate dictionaries You can manually create a dictionary by using rootcling: • DictOutput.cxx specifies the output file that will contain the dictionary. It will be accompanied by a header file DictOutput.h. • OPTIONS are: • Isomething: Adding an include path, so that rootcling can find the files included in Header1.h, Header2.h, etc. • DSOMETHING: Define a preprocessor macro, which is sometimes needed to parse the header files. • Header1.h Header2.h...: The headers files. • Linkdef.h: Tells rootcling, which classes should be added to the dictionary. Note Dictionaries that are used within the same project must have unique names. Compiled object files relative to dictionary source files cannot reside in the same library or in two libraries loaded by the same application if the original source files have the same name. Example In the first step, a TEvent and a TTrack class is defined. Next an event object is created to add tracks to it. The track objects have a pointer to their event. This shows that the I/O system correctly handles circular references. In the second step, the TEvent and the TTrack call are implemented. After that you can use rootcling to generate the directory. This generates the eventdict.cxx file. The TEvent.h header The TTrack.h header Implementation of TEvent and TTrack class Using rootcling to generate the dictionaries eventdict.cxx - the generated dictionary #### Setting the include path The $ROOTSYS/include directory is automatically appended to the include path.

To get the include path, type:

   root[] .include


To append the include path, type:

   root[] .include $HOME/mypackage/include  Append the following line in the ROOT macro to include the include path:  gSystem->AddIncludePath(" -I$HOME/mypackage/include")


To overwrite an existing include path, type:

   gSystem->SetIncludePath(" -I$HOME/mypackage/include")  To add a static library that should be used during linking, type:  gSystem->AddLinkedLibs("-L/my/path -l*anylib*");  For adding a shared library, you can load it before you compile the ROOT macros, by  gSystem->Load("mydir/mylib");  ### Developing portable ROOT macros Portable ROOT macros run both with the Cling interpreter and ACLiC (Compiling Your Code). Therefore, it is recommended not to use the Cling extensions and program around the Cling limitations. If it is not possible to program around the Cling limitations, use the C preprocessor symbols defined for Cling and rootcling: • __CLING__ is defined for both ROOT and rootcling. • __ROOTCLING__ (and __MAKECINT__ for backward compatibility) is only defined in rootcling. Use !defined(__CLING__) || defined(__ROOTCLING__) to bracket code that needs to be seen by the compiler and rootcling, but will be invisible to the interpreter. – or ­– Use !defined(__CLING__) to bracket code that should be seen only by the compiler and not by Cling nor rootcling. Example Hiding the declaration and initialization of the array gArray from both Cling and rootcling: Cling and rootcling will ignore all statements between the #if !defined (__CLING__) and #endif. Because ACLiC calls rootcling to build a dictionary, the declaration of gArray will not be included in the dictionary, and consequently, gArray will not be available at the command line even if ACLiC is used. If you want use the ROOT macro in the interpreter, you have to bracket the usage of gArray between the #if’s, since the definition is not visible. gArray will be visible to rootcling, but still not visible to Cling. If you use ACLiC, gArray will be available at the command line. #### Included header files It is recommended to write ROOT macros with all the needed include statements. Only a few header files are not handled correctly by Cling. You can include following types of headers in the interpreted and compiled mode: • The subset of standard C/C++ headers defined in $ROOTSYS/Cling/include.

• Headers of classes defined in a previously loaded library (including ROOT own library). The defined class must have a name known to ROOT (this is a class with a ClassDef).

Hiding header files from rootcling that are necessary for the compiler but optional for the interpreter can lead to a fatal error.

Example

In this case, rootcling does not have enough information about the TTree class to produce the correct dictionary file.

If you try this, rootcling and compiling will be error free. However, instantiating a subTree object from the Cling command line will cause a fatal error.

In general, it is recommended to let rootcling see as many header files as possible.

## ROOT tutorials

A ROOT tutorial is a ROOT macro that demonstrates ROOT specific features.

There are tutorials for the following topics, among others:

• Containers
• Data Frames
• Fast Fourier Transforms
• Fitting histograms, graphs, etc.
• FITS files interface
• FOAM (multi-dimensional general-purpose Monte Carlo event generator)
• Geometry
• Graphics
• Graphs
• Graphical User Interface (GUI)
• Histograms
• HTTP interface
• Images (using TImage class)
• Input/Output
• Mathematics, matrixes, etc
• Monte Carlo simulations
• Physics
• PyRoot
• R
• RooFit
• RooStats (statistics)
• SQL
• Trees
• UNURAN
• Vectors
• XML
• and many more

When you install ROOT, a tutorials directory is created, containing all ROOT tutorials listed on reference guide tutorial page.

Note

You need write permissions to the tutorials directory to execute the tutorials.

### Starting with hsimple.C

It is recommended to start with the hsimple.C macro first. It creates the ROOT file hsimple.root, which is used by many other macros. hsimple.root contains four histograms hpx, hpx;1, hpxpy;1 and hprof;1.

For detailed information on ROOT files, see → Storing ROOT objects.

To execute the hsimple.C macro at the ROOT prompt, type:

root[0] .x hsimple.C


### Executing demos with demos.C

There are a lot of demos available in the demos.C macro.

To execute the demos.C macro at the ROOT prompt, type:

root[0] .x demos.C


A window is displayed. Here you can try out the different demos.

### Source code of ROOT tutorials

To check the source code of a ROOT macro, open it in your favorite text editor.

Example

graph.C tutorial from $ROOTSYS/tutorials/graphs ## Regular expressions You can use the following meta-characters in regular expressions: ˆ: Start-of-line anchor. $: End-of-line anchor.

.: Matches any character.

[: Start a character class.

]: End a character class.

ˆ: Negates character class if first character.

*: Kleene closure (matches 0 or more).

+: Positive closure (1 or more).

?: Optional closure (0 or 1).

When using wildcards, the regular expression is assumed to be preceded by a ˆ (BOL) and terminated by \$ (EOL).

All * (closures) are assumed to be preceded by a . , this is any character, except slash /. Its special treatment allows the easy matching of pathnames.

Example

*.root will match aap.root, but not pipo/aap.root

The escape characters are:

\: Backslash.

b: Backspace.

f: Form feed.

n: New line.

r: Carriage return.

s: Space.

t: Tab.

e: ASCII ESC character (‘033’).

DDD: number formed of 1-3 octal digits.

xDD: number formed of 1-2 hex digits.

ˆC: C = any letter. Control code.

You can use the TRegexp class to create a regular expression from an input string. If the wildcard is true, then the input string contains a wildcard expression.

Example

   TRegexp(const char *re, Bool_t wildcard)


Regular expression and wildcards can be easily used in methods like:

Ssiz_t Index(const TString& string,Ssiz_t* len,Ssiz_t i) const

The method finds the first occurrence of the regular expression in the string and returns its position.

## Using Cling commands to control ROOT

You can pass commands directly to ROOT by placing a dot before the command.

Type at the ROOT prompt:

   .<command>


.q: Quits ROOT.

.?: Provides a list of all commands.

.!<OS_command>: Accesses the shell of the operating system. For example .!ls or .!pwd.

.x <file_name>: Executes a ROOT macro.

.U <file_name>: Unloads a file.

.L <file_name>: Loads a ROOT macro or library.

.L <file_name>+: Compiles a ROOT macro.

.help: Provides a list of all commands.

.class: Lists the available ROOT classes.

.class X: Shows what cling knows about class X.

.files: Shows all loaded files.

.include: Shows the include paths.

.I path: Adds an include path.

.printAST`: Shows the abstract syntax tree after each processed entity.