How to Use the Geant4 Toolkit Libraries¶
To build an application that uses the Geant4 Toolkit, it is necessary to include the Geant4 headers in the application C++ sources, and compile and link these to the Geant4 libraries. Full details on how to implement, build, and run a Geant4 application are provided in the Geant4 User’s Guide for Application Developers.
Here we describe tools supplied with Geant4 to help with compilation and linking: a CMake
Geant4Config.cmake
config file and a UNIX-only command line program geant4-config
.
A self-contained GNUmake system, “Geant4Make” is also supplied, but is deprecated since
Geant4 10.0. Brief details on this are given in Using Geant4Make to build Applications.
CMake Build System: Geant4Config.cmake¶
The Geant4Config.cmake
file installed by Geant4 is designed to be used with
CMake’s find_package
command. When used, 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 script
is just to locate Geant4 with no requirements on its existence, version
number or components
find_package(Geant4)
If Geant4 is an absolute requirement of the project, 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. By default, CMake will look in several platform dependent locations for
the Geant4Config.cmake
file (see
find_package
for listings). If these are not sufficient to locate your install of Geant4, then
the Geant4_DIR
or CMAKE_PREFIX_PATH
variables may be used. For
example, if we have an install of Geant4 located in
+- opt/ +- Geant4/ +- lib/ +- libG4global.so +- ... +- Geant4-10.6.0/ +- Geant4Config.cmake
then we could pass the argument -DGeant4_DIR=/opt/Geant4/lib/Geant4-
10.6.0
(i.e. the directory holding Geant4Config.cmake
) or -DCMAKE_PREFIX_PATH=/opt/Geant4
to cmake
.
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 Geant4 public headers.
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_LIBRARIES
Set to the list of CMake imported library targets that need to be linked to an application using Geant4. These targets provide CMake Usage Requirements so that linking to them ensures the correct set of include paths and definitions are applied to compile the dependent target.
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 the shell scripts described in Postinstall Setup. 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
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 viaadd_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 viainclude_directories
Prepends
Geant4_CXX_FLAGS
toCMAKE_CXX_FLAGS
, and similarly for the extra compiler flags for each build mode (Release, Debug etc).
This use file is only intended for the most basic applications and is provided for backward compatibility. Projects should prefer linking directly to the Geant4 imported targets for ease of use and stronger linking guarantees.
A version number may 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.4.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 installed 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 provides the Qt UI and visualization drivers, 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 components are found, the needed dependencies are refound and added as usage requirements on the Geant4 imported target libraries.
If you want to activate options only if they exist, you can use the pattern
find_package(Geant4 REQUIRED)
find_package(Geant4 QUIET OPTIONAL_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
isTRUE
if the install of Geant4 provides static libraries.Use of this component forces the variable
Geant4_LIBRARIES
to contain static library targets, 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 versions of third party libraries will be used.multithreaded
Geant4_multithreaded_FOUND
isTRUE
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
isTRUE
if the install of Geant4 was built with VecGeom replacing the Geant4 solids.Note that this only indicates that the replacement of Geant4 solids with VecGeom has taken place. Further information on the use of VecGeom applications is provided in the Application Developers Guide.
gdml
Geant4_gdml_FOUND
isTRUE
if the install of Geant4 was built with GDML support.g3tog4
Geant4_g3tog4_FOUND
isTRUE
if the install of Geant4 provides the G3ToG4 library. If so, the G3ToG4 library is added toGeant4_LIBRARIES
.freetype
Geant4_freetype_FOUND
isTRUE
if the install of Geant4 was built with Freetype support.hdf5
Geant4_hdf5_FOUND
isTRUE
if the install of Geant4 was built with HDF5 support.ui_tcsh
Geant4_ui_tcsh_FOUND
isTRUE
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
isTRUE
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
isTRUE
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
isTRUE
if the install of Geant4 provides the Qt User Interface and Visualization driver. Using this component allows use of the Qt User Interface and Visualization Driver in the linked application.vis_dawn_network
Geant4_vis_dawn_network_FOUND
isTRUE
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_vrml_network
Geant4_vis_vrml_network_FOUND
isTRUE
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_raytracer_x11
Geant4_vis_raytracer_x11_FOUND
isTRUE
if the install of Geant4 provides the X11 interface to the RayTracer Visualization driver. Using this component allows use of the RayTracer X11 Visualization Driver in the linked application.vis_opengl_x11
Geant4_vis_opengl_x11_FOUND
isTRUE
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
isTRUE
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
isTRUE
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
.
Going further with CMake¶
The preceeding sections show the minimal CMake scripting required to configure, build and install an application linking against the Geant4 libraries. If your project requires more advanced configuration, CMake provides tools such as compiler/platform identification and location of additional libraries/executables to link to/use. As this document is specific to Geant4, we do not cover more advanced usage of CMake and recommend that you consult the online manuals and tutorials supplied by Kitware.
In particular, for the common use case of finding and using an external
software package, see the documentation of the find_package
command, overview of CMake’s package location
functionality,
and the list of packages CMake knows about out of the
box.
Location and use of a required package works exactly as we have
illustrated for Geant4. Simply add the required find_package
call to
your CMake script, and use the supplied variables or targets for headers
paths and library linking, e.g.
find_package(Foo 1.2 REQUIRED) # Find "Foo" of at least version 1.2
find_package(Bar 3.4 EXACT REQUIRED) # Find "Bar" at exactly version 3.4
include_directories(${Foo_INCLUDE_DIRS}) # Foo's setup supplies a header path
add_library(MyLibrary SHARED MyLibrary.cc) # Define our library
target_link_libraries(MyLibrary # Link it
${Foo_LIBRARIES} # Foo's setup supplies a library path
Bar::Bar # Bar's setup supplies an "IMPORTED" target
) # which sets header and library paths automatically
You should consult the documentation of the packages your project requires to see if they supply suitable CMake configuration files. If they do not, then CMake provide documentation on writing modules to find packages that do not supply these files. Geant4 cannot provide support for any third party package your project uses, and any questions should be direct to that package’s authors.
Other Unix Build Systems: geant4-config
¶
If you wish to write your own Makefiles or use a completely different
buildsystem for your application, a simple command line program named
geant4-config
is installed on Unix systems to help you query a
Geant4 installation for locations and features. It is installed at:
+- CMAKE_INSTALL_PREFIX
+- bin/
+- geant4-config
It may be run using either a full or relative path, or directly if
CMAKE_INSTALL_PREFIX/bin
is in your PATH
.
This program provides the following command line interface for querying various parameters of the Geant4 installation:
$ ./geant4-config --help
Usage: geant4-config [OPTION...]
--prefix output installation prefix of Geant4
--version output version for Geant4
--cxxstd C++ Standard compiled against
--tls-model Thread Local Storage model used
--libs output all linker flags
--cflags output all preprocessor
and compiler flags
--libs-without-gui output linker flags without
GUI components
--cflags-without-gui output preprocessor and compiler
flags without GUI components
--has-feature FEATURE output yes if FEATURE is supported,
or no if not supported
--datasets output dataset name, environment variable
and path, with one line per dataset
--check-datasets output dataset name, installation status and
expected installation location, with one line
per dataset
--install-datasets download and install any missing datasets,
requires a network connection and for the dataset
path to be user writable
Known Features:
staticlibs[no]
multithreading[no]
clhep[yes]
expat[no]
zlib[yes]
gdml[no]
usolids[no]
freetype[no]
hdf5[no]
g3tog4[no]
qt[no]
motif[no]
raytracer-x11[no]
opengl-x11[no]
openinventor[no]
Help options:
-?, --help show this help message
--usage display brief usage message
You are completely free to organise your application sources as you wish
and to use any buildsystem that can interface with the output of
geant4-config
.
The --cflags
argument will print the required compile definitions
and include paths (in -I<path>
format) to use Geant4 to stdout. Note
that default header search paths for the compiler Geant4 was built with
are filtered out of the output of --cflags
.
The --libs
argument will print the libraries (in -L<path> -lname1 ... -lnameN
format)
required to link with Geant4 to stdout. Note that this may include
libraries for third party packages and may not be reliable for static
builds. By default, all the flags and Geant4 libraries needed to
activate all installed UI and Visualization drivers are provided in
these outputs, but you may use the -without-gui
variants of these
arguments to suppress this.
You may also check the availability of features supported by the install
of Geant4 with the --has-feature
argument. If the argument to
--has-feature
is known to Geant4 and enabled in the installation,
yes
will be printed to stdout, otherwise no
will be printed.
The --datasets
argument may be used to print out a table of dataset
names, environment variables and paths. No checking of the existence of
the paths is performed, as the action to take on a non-existing dataset
will depend on your use case. The table is printed with one row per
dataset, with space separated columns for the dataset name, environment
variable name and path. As with Geant4Config.cmake
, this information
is provided to help you configure your application environment to locate
the Geant4 datasets without a preexisting setup, if your use case
demands this.
The --check-datasets
argument may be used to check whether the
datasets are installed in the location expected (as set by the
configuration of Geant4). A table is printed with one row per dataset,
with space separated columns for the dataset name, installation status
and expected path. If the expected path is found, the status column will
contain INSTALLED
, otherwise it will contain NOTFOUND
. Note that
this check only verifies the existence of the dataset path. It does not
validate that the dataset files are all present nor that the relevant
environment variables are set.
If you did not use the GEANT4_INSTALL_DATA
option to install data
when Geant4 itself was installed, you can use the --install-datasets
argument to perform this task at a later time. Running geant4-config
with this argument will download, unpack and install each dataset to the
location expected by the Geant4 installation. These steps require a
working network connection, the local dataset installation path to be
writable by the user running geant4-config
and the presence of the
curl
, openssl
and tar
programs. Note that no changes to the
environment are made by the data installation, so you may need to update
this using the relevant scripts documented in Postinstall Setup.
Due to the wide range of possible use cases, we do not provide an
example of using geant4-config
to build an application. However, it
should not require more than appending the output of --cflags
to
your compiler flags and that of --libs
to the list of libraries to
link to. We welcome feedback, suggestions for improvement and bug
reports on geant4-config
.