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 also supplied, but is deprecated since Geant4 10.0. Brief details on this are given in Using Geant4Make to build Applications.

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 Geant4_DIR or CMAKE_PREFIX_PATH variables may be used. For example, if we have an install of Geant4 located in

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

then we could pass the argument -DGeant4_DIR=/opt/Geant4/lib/Geant4-10.5.0 (i.e. the directory holding Geant4Config.cmake) or -DCMAKE_PREFIX_PATH=/opt/Geant4 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 headers needed by Geant4. May contain paths to third party headers if these appear in the public interface of Geant4.

  • Geant4_LIBRARIES

    Set to the list of libraries that need to be linked to an application using Geant4.

  • Geant4_DEFINITIONS

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

  • Geant4_CXX_FLAGS

    The compiler flags used to build this install of Geant4. Usually most important on Windows platforms.

  • Geant4_CXX_FLAGS_<CONFIG>

    The compiler flags recommended for compiling Geant4 and applications in mode CONFIG (e.g. Release, Debug, etc). Usually most important on Windows platforms.

  • Geant4_CXXSTD

    The C++ standard, e.g. “c++11” 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_USE_FILE

    A CMake script which can be included to handle certain CMake steps automatically. Most useful for very basic applications.

  • Geant4_builtin_clhep_FOUND

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

  • Geant4_system_clhep_ISGRANULAR

    A CMake boolean which is set to true if this install of Geant4 was built using the system CLHEP and linked to the granular CLHEP libraries.

  • 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()

    A typical use case for these variables is to automatically set the dataset environment variables for your application without the use of the shell scripts described in Postinstall Setup. This could typically be via a shell script wrapper around your application, or runtime configuration of the application environment via the relevant C/C++ API for your system.

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

find_package(Geant4 REQUIRED)                       # Find Geant4
include_directories(${Geant4_INCLUDE_DIRS})         # Add -I type paths
add_definitions(${Geant4_DEFINITIONS})              # Add -D type defs
set(CMAKE_CXX_FLAGS ${Geant4_CXX_FLAGS})            # Optional

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

Alternatively, the CMake script pointed to by Geant4_USE_FILE may be included:

find_package(Geant4 REQUIRED)                       # Find Geant4
include(${Geant4_USE_FILE})                         # Auto configure includes/flags

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

When included, the Geant4_USE_FILE script performs the following actions:

  1. Adds the definitions in Geant4_DEFINITIONS to the global compile definitions.
  2. Appends the directories listed in Geant4_INCLUDE_DIRS to those the compiler uses for search for include paths, marking them as system include directories.
  3. Prepends Geant4_CXX_FLAGS to CMAKE_CXX_FLAGS, and similarly for the extra compiler flags for each build mode (Release, Debug etc).

This use file is very useful for basic applications, but if your use case requires finer control over compiler definitions, include paths and flags you should use the relevant Geant4_NAME variables directly.

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 10.0 REQUIRED)

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

find_package(Geant4 10.4.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, any needed header paths, libraries and compile definitions required to use the component are appended to the variables Geant_INCLUDE_DIRS, Geant4_LIBRARIES and Geant4_DEFINITIONS respectively. Variables Geant4_<COMPONENTNAME>_FOUND are set to TRUE if component <COMPONENTNAME> is supported by the installation.

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 libraries, 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 version 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 and activates the required compiler definition to build a multithreaded Geant4 application. Multithreading in your application 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.

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

  • wt

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

  • vis_dawn_network

    Geant4_vis_dawn_network_FOUND is TRUE if the install of Geant4 provides the Client/Server network interface to DAWN visualization. Using this component allows use of the Client/Server DAWN Visualization Driver in the linked application.

  • vis_vrml_network

    Geant4_vis_vrml_network_FOUND is TRUE if the install of Geant4 provides the Client/Server network interface to VRML visualization. Using this component allows use of the Client/Server VRML 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.

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

In particular, for the common use case of finding and using an external software package, see the documentation of the find_package command, overview of CMake’s package location functionality, and the list of packages CMake knows about out of the box. Location and use of a required package works exactly as we have illustrated for Geant4. Simply add the required find_package call to your CMake script, and use the supplied variables or targets for headers paths and library linking, e.g.

find_package(Foo 1.2 REQUIRED)        # Find "Foo" of at least version 1.2
find_package(Bar 3.4 EXACT REQUIRED)  # Find "Bar" at exactly version 3.4

include_directories(${Foo_INCLUDE_DIRS}) # Foo's setup supplies a header path

add_library(MyLibrary SHARED MyLibrary.cc) # Define our library
target_link_libraries(MyLibrary            # Link it
  ${Foo_LIBRARIES}                         # Foo's setup supplies a library path
  Bar::Bar                                 # Bar's setup supplies an "IMPORTED" target
  )                                        # which sets header and library paths automatically

You should consult the documentation of the packages your project requires to see if they supply suitable CMake configuration files. If they do not, then CMake provide documentation on writing modules to find packages that do not supply these files. Geant4 cannot provide support for any third party package your project uses, and any questions should be direct to that package’s authors.

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:

$ ./geant4-config --help
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

  --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[no]
 muonic_atoms[no]
 clhep[yes]
 expat[no]
 zlib[yes]
 gdml[no]
 usolids[no]
 freetype[no]
 hdf5[no]
 g3tog4[no]
 qt[no]
 motif[no]
 raytracer-x11[no]
 opengl-x11[no]
 openinventor[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.