# - Geant4 CMake Configuration File for External Projects
# This file is configured by Geant4 for use by an external project
# As this file is configured by Geant4's CMake system it SHOULD NOT BE EDITED
# It defines the following variables
#  Geant4_INCLUDE_DIRS - include directories for Geant4
#  Geant4_DEFINITIONS  - compile definitions needed to use Geant4
#  Geant4_LIBRARIES    - libraries to link against
#  Geant4_CXX_FLAGS    - Recommended CXX flags for the compiler used to
#                        build the Geant4 libraries.
#  Geant4_CXX_FLAGS_<CONFIG> - Recommended CXX flags for build mode CONFIG.
#  Geant4_USE_FILE     - path to a CMake module which may be included to help
#                        setup CMake variables 
#
# You may supply a version number through find_package which will be checked
# against the version of this build. Standard CMake logic is used so that
# the EXACT flag may be passed, and otherwise this build will report itself
# as compatible with the requested version if:
#
#  VERSION_OF_THIS_BUILD >= VERSION_REQUESTED
#
# By default only the core (or kernel) of Geant4 is activated by this module.
# You can specify additional components of Geant4 through the COMPONENTS
# argument to find_package. By default, all core libraries of Geant4 are
# appended to the Geant4_LIBRARIES variable. Specifiying additional components
# will enable a check on the existence of these components, with the following
# per component variables being set:
#
#  Geant4_${COMPONENT}_FOUND    TRUE is the Geant4 library "component" was
#                               found
#
#  Geant4_${COMPONENT}_LIBRARY  Contains the library for the specified
#                               "component" IF the component is a library.
#
# In Geant4, components can be optional subcomponents of an always available
# library. In that case there will be no Geant4_{COMPONENT}_LIBRARY variable.
# These non-library components are generally activated by compile definitions, 
# and in these cases the appropriate definition will be added to the
# Geant4_DEFINITIONS component
#
# If you specify components and use the REQUIRED option to find_package, then
# the module will issue a FATAL_ERROR if this build of Geant does not have 
# the requested component(s).
#
# The list of components available generally corresponds to the optional extras
# that Geant4 can be built with and are:
#
#
#  gdml              (GDML support)
#
#  ui_tcsh           (TCsh Style Application Command Line Interface)
#  ui_win32          (WIN32 Style Application Command Line Interface)
#
#  motif             (Motif-X11/OpenGL Graphical User Interface)
#  qt                (Qt4/OpenGL Graphical User Interface)
#
#  vis_network_dawn  (Client/Server network interface to DAWN visualization)
#  vis_network_vrml  (Client/Server network interface to VRML visualization)
#  vis_opengl_x11    (OpenGL visualization with X11 interface)
#  vis_opengl_win32  (OpenGL visualization with X11 interface)
#  vis_raytracer_x11 (RayTracer visualization with X11 interface)
#  vis_openinventor  (OpenInventor visualization)
#
# In addition, two 'shorthand' components are defined to help activate all
# available User Interface and Visualization drivers:
# 
#  ui_all            (All available UI drivers)
#  vis_all           (All available Vis drivers)
#
# These never result in a FATAL_ERROR, even if the REQUIRED find_package 
# argument is set. This is because these options do not depend on specific
# components being available.
#
# ===========================================================================
# Variables used by this module which can change the default behaviour of
# this module. They need to be set prior to the call to find_package
#
#  Geant4_CONFIG_DEBUG    If set, enable extra messaging output which can be
#                         helpful in debugging and identifying problems with
#                         the configuration.
#
#----------------------------------------------------------------------------

Geant4Config.cmake is designed to be used with CMake's find_package command. 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 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 Geant4 not be located.

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

The typical build of a Geant4 application in a CMake script 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
  

CMake will look in several platform dependent locations for the Geant4Config.cmake file (see find_package for details). You can also specify this yourself when running CMake via 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.5.0/
                  +- Geant4Config.cmake
    

then we would run CMake with Geant4_DIR=/opt/Geant4/lib/Geant4-9.5.0.

A version number may also be supplied to search for a Geant4 install greater than or equal to supplied number, 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.5.0 EXACT REQUIRED)
    

Geant4 can be built with many optional components, and the presence of these can also be required, for example

      find_package(Geant4 REQUIRED qt)
    

would cause CMake to search for an install of Geant4 which was built with Qt4, and fail if a install with Qt4 support was not found. If the componet is found, any needed headers, libraries and compile definitions will be added to the Geant_INCLUDE_DIRS, Geant4_LIBRARIES and Geant4_DEFINITIONS respectively.

All available component arguments are listed in Section 5.1

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 a core install of Geant4 to be found, and then check if this install was built with Qt4 support, continuing without error if Qt4 support was not found in the Geant4 install.

If you use this pattern and need to check if a component was found, Geant4Config.cmake sets the variable(s) Geant4_<COMPONENTNAME>_FOUND to TRUE if component COMPONENTNAME is supported in the found install of Geant4.

The above is only a sampling of the many ways you can search for a Geant4 install and set it up for use by your project in CMake.

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 developer's 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.

Application 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 build directory.