How to Use the Geant4 Toolkit Libraries

To build an application that uses the Geant4 Toolkit, it is necessary to include the Geant4 headers in the application C++ sources, and compile and link these to the Geant4 libraries. Full details on how to implement, build, and run a Geant4 application are provided in the Geant4 User’s Guide for Application Developers.

Here we describe tools supplied with Geant4 to help with compilation and linking: a CMake Geant4Config.cmake config file and a UNIX-only command line program geant4-config. A self-contained GNUmake system, “Geant4Make” is currently supplied, but is deprecated since Geant4 10.0 and no longer developed or supported.

CMake Build System: Geant4Config.cmake

The Geant4Config.cmake file installed by Geant4 is designed to be used with CMake’s find_package command. When used, it sets several CMake variables and provides a mechanism for checking and activating optional features of Geant4. This allows you to use it in many ways in your CMake project to configure Geant4 for use by your application.

The most basic usage of Geant4Config.cmake in a CMakeLists.txt script is just to locate Geant4 with no requirements on its existence, version number or components

find_package(Geant4)

If Geant4 is an absolute requirement of the project, then you can use

find_package(Geant4 REQUIRED)

This will cause CMake to fail with an error should an install of Geant4 not be located. By default, CMake will look in several platform dependent locations for the Geant4Config.cmake file (see find_package for listings). If these are not sufficient to locate your install of Geant4, then the CMAKE_PREFIX_PATH or Geant4_DIR variables may be used. For example, if we have an install of Geant4 located in

+- opt/
   +- Geant4/
   +- lib/
      +- libG4global.so
      +- ...
      +- cmake/
         +- Geant4/
            +- Geant4Config.cmake

then we could pass the argument -DCMAKE_PREFIX_PATH=/opt/Geant4 or -DGeant4_DIR=/opt/Geant4/lib/cmake/Geant4 (i.e. the directory holding Geant4Config.cmake) to cmake.

When an install of Geant4 is found, the module sets a sequence of CMake variables that can be used elsewhere in the project:

  • Geant4_FOUND

    Set to CMake boolean true if an install of Geant4 was found.

  • Geant4_INCLUDE_DIRS

    Set to a list of directories containing Geant4 public headers.

  • Geant4_DEFINITIONS

    The list of compile definitions needed to compile an application using Geant4. This is most typically used to activate Visualization drivers.

  • Geant4_LIBRARIES

    Set to the list of CMake imported library targets that need to be linked to an application using Geant4. These targets provide CMake Usage Requirements so that linking to them ensures the correct set of include paths and definitions are applied to compile the target using them.

  • Geant4_CXX_STANDARD

    The C++ standard, e.g. “17” against which this install of Geant4 was compiled.

  • Geant4_TLS_MODEL

    The thread-local storage model, e.g. “initial-exec” against which this install of Geant4 was compiled. Only set if the install was compiled with multithreading support.

  • Geant4_builtin_clhep_FOUND

    A CMake boolean which is set to true if this install of Geant4 was built using the internal CLHEP.

  • Geant4_builtin_expat_FOUND

    A CMake boolean which is set to true if this install of Geant4 was built using the internal Expat.

  • Geant4_builtin_zlib_FOUND

    A CMake boolean which is set to true if this install of Geant4 was built using the internal zlib.

  • Geant4_DATASETS

    A CMake list of the names of the physics datasets used by physics models in Geant4. It is provided to help iterate over the Geant4_DATASET_XXX_YYY variables documented below.

  • Geant4_DATASET_<NAME>_ENVVAR

    The name of the environment variable used by Geant4 to locate the dataset with name <NAME>.

  • Geant4_DATASET_<NAME>_PATH

    The absolute path to the dataset with name <NAME>. Note that the setting of this variable does not guarantee the existence of the dataset, and no checking of the path is performed. This checking is not provided because the action you take on non-existing data will be application dependent.

    You can access the Geant4_DATASET_XXX_YYY variables in a CMake script in the following way:

    find_package(Geant4_REQUIRED)                 # Find Geant4

foreach(dsname ${Geant4_DATASETS})            # Iterate over dataset names
  if(NOT EXISTS ${Geant4_DATASET_${dsname}_PATH})  # Check existence
    message(WARNING "${dsname} not located at ${Geant4_DATASET_${dsname}_PATH}")
  endif()
endforeach()

The typical usage of find_package and these variables to configure a build requiring Geant4 is thus:

find_package(Geant4 REQUIRED)                       # Find Geant4
add_executable(myg4app myg4app.cc)                  # Compile application
target_link_libraries(myg4app ${Geant4_LIBRARIES})  # Link it to Geant4

A version number may be supplied to search for a Geant4 install greater than or equal to the supplied version, e.g.

find_package(Geant4 11.0 REQUIRED)

would make CMake search for a Geant4 install whose version number is greater than or equal to 11.0. An exact version number may also be specified:

find_package(Geant4 11.1.0 EXACT REQUIRED)

In both cases, CMake will fail with an error if a Geant4 install meeting these version requirements is not located.

Geant4 can be installed with many optional components, and the presence of these can also be required by passing extra “component” arguments. For example, to require that Geant4 is found and that it provides the Qt UI and visualization drivers, we can do

find_package(Geant4 REQUIRED qt)

In this case, if CMake finds a Geant4 install that does not support Qt, it will fail with an error. Multiple component arguments can be supplied, for example

find_package(Geant4 REQUIRED qt gdml)

requires that we find a Geant4 install that supports both Qt and GDML. If the components are found, the needed dependencies are refound and added as usage requirements on the Geant4 imported target libraries.

If you want to activate options only if they exist, you can use the pattern

find_package(Geant4 REQUIRED)
find_package(Geant4 QUIET OPTIONAL_COMPONENTS qt)

which will require CMake to locate a core install of Geant4, and then check for and activate Qt support if the install provides it, continuing without error otherwise. A key thing to note here is that you can call find_package multiple times to append configuration of components. If you use this pattern and need to check if a component was found, you can use the Geant4_<COMPONENTNAME>_FOUND variables described earlier to check the support.

The components which can be supplied to find_package for Geant4 are as follows:

  • static

    Geant4_static_FOUND is TRUE if the install of Geant4 provides static libraries.

    Use of this component forces the variable Geant4_LIBRARIES to contain static library targets, if they are available. It can therefore be used to force static linking if your application requires this, but note that this does not guarantee that static versions of third party libraries will be used.

  • multithreaded

    Geant4_multithreaded_FOUND is TRUE if the install of Geant4 was built with multithreading support.

    Note that this only indicates availability of multithreading support Multithreading in your applications requires creation and usage of the appropriate C++ objects and interfaces as described in the Application Developers Guide.

  • usolids

Geant4_usolids_FOUND is TRUE if the install of Geant4 was built with VecGeom replacing the Geant4 solids.

Note that this only indicates that the replacement of Geant4 solids with VecGeom has taken place. Further information on the use of VecGeom applications is provided in the Application Developers Guide.

  • smartstack

    Geant4_smartstack_FOUND is TRUE if the install of Geant4 was built with G4SmartStack use in G4TrackingManager.

  • php_as_hp

    Geant4_php_as_hp_FOUND is TRUE if the install of Geant4 was built with ParticleHP as HP.

  • gdml

    Geant4_gdml_FOUND is TRUE if the install of Geant4 was built with GDML support.

  • g3tog4

    Geant4_g3tog4_FOUND is TRUE if the install of Geant4 provides the G3ToG4 library. If so, the G3ToG4 library is added to Geant4_LIBRARIES.

  • freetype

    Geant4_freetype_FOUND is TRUE if the install of Geant4 was built with Freetype support.

  • hdf5

    Geant4_hdf5_FOUND is TRUE if the install of Geant4 was built with HDF5 support.

  • ui_tcsh

    Geant4_ui_tcsh_FOUND is TRUE if the install of Geant4 provides the TCsh command line User Interface. Using this component allows use of the TCsh command line interface in the linked application.

  • ui_win32

    Geant4_ui_win32_FOUND is TRUE if the install of Geant4 provides the Win32 command line User Interface. Using this component allows use of the Win32 command line interface in the linked application.

  • motif

    Geant4_motif_FOUND is TRUE if the install of Geant4 provides the Motif(Xm) User Interface and Visualization driver. Using this component allows use of the Motif User Interface and Visualization Driver in the linked application.

  • qt

    Geant4_qt_FOUND is TRUE if the install of Geant4 provides the Qt User Interface and Visualization driver. Using this component allows use of the Qt User Interface and Visualization Driver in the linked application.

  • vis_raytracer_x11

    Geant4_vis_raytracer_x11_FOUND is TRUE if the install of Geant4 provides the X11 interface to the RayTracer Visualization driver. Using this component allows use of the RayTracer X11 Visualization Driver in the linked application.

  • vis_opengl_x11

    Geant4_vis_opengl_x11_FOUND is TRUE if the install of Geant4 provides the X11 interface to the OpenGL Visualization driver. Using this component allows use of the X11 OpenGL Visualization Driver in the linked application.

  • vis_opengl_win32

    Geant4_vis_opengl_win32_FOUND is TRUE if the install of Geant4 provides the Win32 interface to the OpenGL Visualization driver. Using this component allows use of the Win32 OpenGL Visualization Driver in the linked application.

  • vis_openinventor

    Geant4_vis_openinventor_FOUND is TRUE if the install of Geant4 provides the OpenInventor Visualization driver. Using this component allows use of the OpenInventor Visualization Driver in the linked application.

  • vis_toolssg_x11_gles

    Geant4_vis_toolssg_x11_gles_FOUND is TRUE if the install of Geant4 provides the ToolsSG visualization driver with X11 backend. Using this component allows use of the ToolsSG Visualization Driver in the linked application.

  • vis_toolssg_xt_gles

    Geant4_vis_toolssg_xt_gles_FOUND is TRUE if the install of Geant4 provides the ToolsSG visualization driver with Motif backend. Using this component allows use of the ToolsSG Visualization Driver in the linked application.

  • vis_toolssg_qt_gles

    Geant4_vis_toolssg_qt_gles_FOUND is TRUE if the install of Geant4 provides the ToolsSG visualization driver with Qt5 backend. Using this component allows use of the ToolsSG Visualization Driver in the linked application.

  • vis_toolssg_windows_gles

    Geant4_vis_toolssg_windows_gles_FOUND is TRUE if the install of Geant4 provides the ToolsSG visualization driver with Windows backend. Using this component allows use of the ToolsSG Visualization Driver in the linked application.

  • vis_Vtk

    Geant4_vis_Vtk_FOUND is TRUE if the install of Geant4 provides the Vtk visualization driver. Using this component allows use of the Vtk Visualization Driver in the linked application.

  • ui_all

    Activates all available UI drivers. Does not set any variables, and never causes CMake to fail.

  • vis_all

    Activates all available Visualization drivers. Does not set any variables, and never causes CMake to fail.

Please note that whilst the above aims to give a complete summary of the functionality of Geant4Config.cmake, it only gives a sampling of the ways in which you may use it, and other CMake functionality, to configure your application. We also welcome feedback, suggestions for improvement and bug reports on Geant4Config.cmake.

Going further with CMake

The preceding sections show the minimal CMake scripting required to configure, build and install an application linking against the Geant4 libraries. If your project requires more advanced configuration, CMake provides tools such as compiler/platform identification and location/use of additional libraries/executables to link to/use. As this document is specific to Geant4, we do not cover more advanced usage of CMake and recommend that you consult the online manuals and tutorials supplied by Kitware together with the CMake Discourse Forum.

We also recommend the HEP Software Foundation CMake Tutorial and the CLIUtils Modern CMake Tutorial.

Other Unix Build Systems: geant4-config

If you wish to write your own Makefiles or use a completely different buildsystem for your application, a simple command line program named geant4-config is installed on Unix systems to help you query a Geant4 installation for locations and features. It is installed at:

+- CMAKE_INSTALL_PREFIX
   +- bin/
      +- geant4-config

It may be run using either a full or relative path, or directly if CMAKE_INSTALL_PREFIX/bin is in your PATH.

This program provides the following command line interface for querying various parameters of the Geant4 installation:

Usage: geant4-config [OPTION...]
  --prefix                output installation prefix of Geant4
  --version               output version for Geant4
  --cxxstd                C++ Standard compiled against
  --tls-model             Thread Local Storage model used
  --libs                  output all linker flags
  --cflags                output all preprocessor
                          and compiler flags

  --libs-without-gui      output linker flags without
                          GUI components
  --cflags-without-gui    output preprocessor and compiler
                          flags without GUI components

  --has-feature FEATURE   output yes if FEATURE is supported,
                          or no if not supported

  --features              print list of features

  --sh                    print shell commands required to set environment
                          variables for Geant4, which can be evaluated in
                          the calling shell with "eval $(geant4-config --sh)"

  --csh                   print C shell commands required to set environment
                          variables for Geant4, which can be evaluated in
                          the calling shell with "eval `geant4-config --csh`"

  --datasets              output dataset name, environment variable
                          and path, with one line per dataset

  --check-datasets        output dataset name, installation status and
                          expected installation location, with one line
                          per dataset

  --install-datasets      download and install any missing datasets,
                          requires a network connection and for the dataset
                          path to be user writable

Known Features:
 staticlibs[no]
 multithreading[yes]
 smartstack[no]
 php_as_hp[no]
 clhep[yes]
 expat[no]
 zlib[yes]
 gdml[no]
 ptl[yes]
 usolids[no]
 freetype[no]
 hdf5[no]
 g3tog4[no]
 qt[no]
 qt3d[no]
 motif[no]
 raytracer-x11[no]
 opengl-x11[no]
 openinventor[no]
 vtk[no]

Help options:
  -?, --help              show this help message
  --usage                 display brief usage message

You are completely free to organise your application sources as you wish and to use any buildsystem that can interface with the output of geant4-config.

The --cflags argument will print the required compile definitions and include paths (in -I<path> format) to use Geant4 to stdout. Note that default header search paths for the compiler Geant4 was built with are filtered out of the output of --cflags.

The --libs argument will print the libraries (in -L<path> -lname1 ... -lnameN format) required to link with Geant4 to stdout. Note that this may include libraries for third party packages and may not be reliable for static builds. By default, all the flags and Geant4 libraries needed to activate all installed UI and Visualization drivers are provided in these outputs, but you may use the --without-gui variants of these arguments to suppress this.

You may also check the availability of features supported by the install of Geant4 with the --has-feature argument. If the argument to --has-feature is known to Geant4 and enabled in the installation, yes will be printed to stdout, otherwise no will be printed.

The --datasets argument may be used to print out a table of dataset names, environment variables and paths. No checking of the existence of the paths is performed, as the action to take on a non-existing dataset will depend on your use case. The table is printed with one row per dataset, with space separated columns for the dataset name, environment variable name and path. As with Geant4Config.cmake, this information is provided to help you configure your application environment to locate the Geant4 datasets without a preexisting setup, if your use case demands this.

The --check-datasets argument may be used to check whether the datasets are installed in the location expected (as set by the configuration of Geant4). A table is printed with one row per dataset, with space separated columns for the dataset name, installation status and expected path. If the expected path is found, the status column will contain INSTALLED, otherwise it will contain NOTFOUND. Note that this check only verifies the existence of the dataset path. It does not validate that the dataset files are all present nor that the relevant environment variables are set.

If you did not use the GEANT4_INSTALL_DATA option to install data when Geant4 itself was installed, you can use the --install-datasets argument to perform this task at a later time. Running geant4-config with this argument will download, unpack and install each dataset to the location expected by the Geant4 installation. These steps require a working network connection, the local dataset installation path to be writable by the user running geant4-config and the presence of the curl, openssl and tar programs. Note that no changes to the environment are made by the data installation, so you may need to update this using the relevant scripts documented in Postinstall Setup.

Due to the wide range of possible use cases, we do not provide an example of using geant4-config to build an application. However, it should not require more than appending the output of --cflags to your compiler flags and that of --libs to the list of libraries to link to. We welcome feedback, suggestions for improvement and bug reports on geant4-config.