5.  Geant4Config.cmake CMake Config File

5.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_USE_FILE

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

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
    

This is very useful for basic applications, but if you need fine control, you should use the 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 yourself 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-9.6.0/
               +- Geant4Config.cmake
    

then we would pass the argument -DGeant4_DIR=/opt/Geant4/lib/Geant4-9.6.0 to CMake.

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.5.0 REQUIRED)
    

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

      find_package(Geant4 9.6.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 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:

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

  • ui_tcsh

    Geant4_ui_tcsh_FOUND is TRUE if the install of Geant4 provides the TCsh command line User Interface.

  • ui_win32

    Geant4_ui_win32_FOUND is TRUE if the install of Geant4 provides the Win32 command line User Interface.

  • motif

    Geant4_motif_FOUND is TRUE if the install of Geant4 provides the Motif(Xm) User Interface and Visualization driver.

  • qt

    Geant4_qt_FOUND is TRUE if the install of Geant4 provides the Qt4 User Interface and Visualization driver.

  • vis_network_dawn

    Geant4_vis_network_dawn_FOUND is TRUE if the install of Geant4 provides the Client/Server network interface to DAWN visualization.

  • vis_network_vrml

    Geant4_vis_network_vrml_FOUND is TRUE if the install of Geant4 provides the Client/Server network interface to VRML visualization.

  • vis_opengl_x11

    Geant4_vis_opengl_x11_FOUND is TRUE if the install of Geant4 provides the X11 interface to the OpenGL Visualization driver.

  • vis_opengl_win32

    Geant4_vis_opengl_win32_FOUND is TRUE if the install of Geant4 provides the Win32 interface to the OpenGL Visualization driver.

  • vis_openinventor

    Geant4_vis_openinventor_FOUND is TRUE if the install of Geant4 provides the OpenInventor Visualization driver.

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

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