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.
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_expat_FOUND
A CMake boolean which is set to true if this install of Geant4 was built using the internal Expat.
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 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
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-10.0.0/ +- Geant4Config.cmake
then we would pass the argument
-DGeant4_DIR=/opt/Geant4/lib/Geant4-10.0.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.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.0.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 checked/required by passing extra "component" arguments. For example, to require that Geant4 is found and that it supports 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:
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. Multithreading in an application requires creation and usage of the appropriate C++ objects and interfaces as described 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.
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.
wt
Geant4_wt_FOUND
is
TRUE
if the install of Geant4 provides
the Wt Web 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
.
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.