Installation

Prerequisites

To build the project you need

a C++ compiler,
a Fortran compiler,
ROOT,
GSL (GNU Scientific Library),
CMake (version 3.12 or higher).

Instructions for installing ROOT can be found here.

Using the LCG software collection

On lxplus (or another system with access to cvmfs) you can select a coherent set of packages through an LCG view by sourcing, for example,

source /cvmfs/sft.cern.ch/lcg/views/LCG_104c/x86_64-el9-gcc13-opt/setup.sh

or, if you are using a (t)csh-type shell,

source /cvmfs/sft.cern.ch/lcg/views/LCG_104c/x86_64-el9-gcc13-opt/setup.csh

Other combinations of architectures and compilers are also available.

Platform-specific instructions

Instructions for Ubuntu (contributed by Irina Kempf)
On MacOS 12, Garfield++ has been built successfully using
- a CMake binary distribution,
- the clang compiler provided with the Xcode command line developer tools (xcode-select --install),
- a matching version of gfortran from this page,
- GSL built from source, and
- a pre-compiled binary ROOT distribution.
On MacOS 14, Garfield++ has been built successfully using
- a CMake binary distribution,
- Xcode command line developer tools (xcode-select --install),
- gfortran, ROOT and GSL from MacPorts
```
sudo port install gcc1
sudo port install root6
sudo port install gsl
```

Using a Garfield++ installation from CVMFS

To profit from the latest developments and bug fixes, it is recommended to use the HEAD of the repository and build the project yourself following the instructions below. Alternatively, if you have access to cvmfs, you can pick up a Garfield++ installation from an LCG view, e. g.

source /cvmfs/sft.cern.ch/lcg/views/LCG_104c/x86_64-el9-gcc13-opt/setup.sh
source /cvmfs/sft.cern.ch/lcg/views/LCG_104c/x86_64-el9-gcc13-opt/share/Garfield/setupGarfield.sh

Instead of a release, it is also possible to use the LCG nightly builds

source /cvmfs/sft-nightlies.cern.ch/lcg/views/dev3/latest/x86_64-el9-gcc13-opt/setup.sh
source /cvmfs/sft-nightlies.cern.ch/lcg/views/dev3/latest/x86_64-el9-gcc13-opt/share/Garfield/setupGarfield.sh

Building the project from source

Downloading the source code

Git

The Garfield++ source files are kept in a GitLab repository. For an introduction to the Git version control system consult the Pro Git book.

To get hold of the source files, please follow the steps below.

Define an environment variable $GARFIELD_HOME pointing to the directory where the Garfield++ source files should be located. Note that this directory must be empty or non-existing.

If you are using bash, type
```
export GARFIELD_HOME=/home/mydir/garfield
```
(replace /home/mydir/garfield by the path of your choice)

For (t)csh-type shells, type
```
setenv GARFIELD_HOME /home/mydir/garfield
```
You might also want to add the above lines to your .bashrc (or .cshrc).
Clone the (master branch of the) repository.

If you have a CERN account, you can use ssh authentication.

git clone ssh://git@gitlab.cern.ch:7999/garfield/garfieldpp.git $GARFIELD_HOME

If you do not have a CERN account, use HTTP authentication.

git clone https://gitlab.cern.ch/garfield/garfieldpp.git $GARFIELD_HOME

Building the project

Make sure that the ROOT environment has been set by sourcing the thisroot.sh (or thisroot.csh) script.
Go to the directory $GARFIELD_HOME.
```
cd $GARFIELD_HOME
```
Create a build directory and make it your work directory.
```
mkdir build
cd build
```
Run CMake. If you are happy with the default settings, you can simply type
```
cmake $GARFIELD_HOME
```
CMake options

By default, the install folder (i. e. the folder to which the headers and library will be copied during the make install step) is set to $GARFIELD_HOME/install. This default can be overriden using the flag CMAKE_INSTALL_PREFIX:
```
cmake -DCMAKE_INSTALL_PREFIX=<installdir> $GARFIELD_HOME
```
The variable WITH_EXAMPLES specifies whether (some of) the example applications should be built at the same time as the project itself. It defaults to ON. If you want to skip building the examples, set this flag to OFF:
```
cmake -DWITH_EXAMPLES=OFF $GARFIELD_HOME
```
The variable WITH_DOCS is optional, and should be passed if you wish to build the Doxygen based documentation. Please note that this requires an existing installation of Doxygen. If CMake cannot locate Doxygen, its install location should be added into CMAKE_PREFIX_PATH.
```
cmake -DWITH_DOCS=ON $GARFIELD_HOME
```
For further details please have a look at the CMake tutorial.

Run make.

make -j <number of cores on your machine>
make install

The install directory should now contain the headers and the library.
Set up the environment for building and running a Garfield++-based application by sourcing the script setupGarfield.(c)sh.

If you are using bash, type
```
source $GARFIELD_HOME/install/share/Garfield/setupGarfield.sh
```
If you are using a (t)csh-type shell, type
```
source $GARFIELD_HOME/install/share/Garfield/setupGarfield.csh
```
You might want to add these lines to your .bashrc (or .cshrc).

The script will set the environment variable GARFIELD_INSTALL pointing to the Garfield++ install folder, the environment variable HEED_DATABASE pointing to the directory containing the photoabsorption cross-section data, and will prepend the install directory to the CMAKE_PREFIX_PATH environment variable.

At present, the code is still frequently modified. To obtain the latest version, use the command git pull origin master and rebuild the project.

Building and running an application

As an example for building an application, we consider the GEM example located in $GARFIELD_HOME/Examples/Gem.

Since we will probably want to modify the code, it is a good idea to copy the folder to a local directory.
```
cp -r $GARFIELD_HOME/Examples/Gem .
```
The Gem folder contains the source code of the example, the CMakeLists.txt file for building the executable, and the field map files needed for running it.

Make sure you have set up the ROOT and Garfield++ environment variables by sourcing the scripts thisroot.(c)sh and setupGarfield.(c)sh.
Create a build folder and make it the current working directory.
```
mkdir Gem/build; cd Gem/build
```
Run CMake to create the Makefile and build the executable.
```
cmake ..
make
```
We can now run the application
```
./gem
```

Python interface

Thanks to PyROOT, one can also use the Garfield++ classes in Python. After building the project and setting up the environment following the instructions above (i. e. sourcing the setupGarfield.(c)sh script), one can load the library in the Python interpreter using

import ROOT
import Garfield

Examples can be found here (pythonized version of the drift tube example) and here (GEM example).