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 with an error 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++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 external shell 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:
Adds the definitions in Geant4_DEFINITIONS
to the global compile definitions.
Appends the directories listed in Geant4_INCLUDE_DIRS
to those the compiler uses for search for include paths,
marking them as system include directories.
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.2.0/ +- Geant4Config.cmake
then we would pass the argument
-DGeant4_DIR=/opt/Geant4/lib/Geant4-10.2.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 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.2.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 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
.
freetype
Geant4_freetype_FOUND
is
TRUE
if the install of Geant4 was built
with Freetype 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 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
.
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.