4.  Geant4Config.cmake CMake Config File

4.1.  Usage of Geant4Config.cmake

Geant4Config.cmake is designed to be used with CMake's find_package command. When found, 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 file is just to locate Geant4 with no requirements on its existence, version number or components:

        find_package(Geant4)
      

If you must find Geant4, then you can use

        find_package(Geant4 REQUIRED)
      

This will cause CMake to fail should an install of Geant4 not be located.

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++98" 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_builtin_usolids_FOUND

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

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

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

  • 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 Geant4 shell environment setup scripts. 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.

By default, CMake will look in several platform dependent locations for the Geant4Config.cmake file (see find_package for listings). You can also specify the location directly when running CMake by setting the Geant4_DIR variable to the path of the directory holding Geant4Config.cmake. It may be set on the command line via a -D option, or by adding an entry to the CMake GUI. For example, if we have an install of Geant4 located in

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

then we would pass the argument -DGeant4_DIR=/opt/Geant4/lib/Geant4-10.1.0 to CMake. The CMAKE_PREFIX_PATH variable may also be used to point CMake to Geant4 by adding, to take the example above, /opt/Geant4 to the list of paths it holds. This may be set either on the command line or as a path-style UNIX environment variable.

You can also, if you wish, build an application against a build of Geant4 without installing it. If you look in the directory where you built Geant4 itself (e.g. on UNIX, where you ran make), you see there is a Geant4Config.cmake file. This is a perfectly valid file, so you can also point CMake to this file when building your application. Simply set Geant4_DIR to the directory where you built Geant4. This feature is most useful for Geant4 developers, but it can be useful if you cannot, or do not want to, install Geant4.

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

        find_package(Geant4 9.6.0 REQUIRED)
      

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

        find_package(Geant4 10.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 built 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 support Qt UI and visualization, 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 component(s) is(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 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 of Geant4 libraries 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 USolids replacing the Geant4 solids.

    Note that this only indicates that the replacement of Geant4 solids with USolids has taken place. Further information on the use of USolids 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.

  • 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 Qt4 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_network_dawn

    Geant4_vis_network_dawn_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_network_vrml

    Geant4_vis_network_vrml_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_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.

4.2.  Building an Application against a Build of Geant4

A typical use case for Geant4 developers is to build small testing applications against a fresh build of Geant4. If rebuilds are frequent, then the testing application builds are also frequent.

CMake can be used to build these test applications using find_package and Geant4Config.cmake, as a special version of the latter is created in the Geant4 build directory. This sets up the variables to point to the headers in the Geant4 source directory, and the freshly built libraries in the current build directory.

Applications may therefore be built against a non-installed build of Geant4 by running CMake for the application and setting Geant4_DIR to point to the current build directory of Geant4.