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 currently supplied, but is deprecated since
Geant4 10.0 and no longer developed or supported.
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 CMAKE_PREFIX_PATH
or Geant4_DIR
variables may be used. For
example, if we have an install of Geant4 located in
+- opt/
+- Geant4/
+- lib/
+- libG4global.so
+- ...
+- cmake/
+- Geant4/
+- Geant4Config.cmake
then we could pass the argument -DCMAKE_PREFIX_PATH=/opt/Geant4
or -DGeant4_DIR=/opt/Geant4/lib/cmake/Geant4
(i.e. the directory holding Geant4Config.cmake
)
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 activate 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 target using them.
Geant4_CXX_STANDARD
The C++ standard, e.g. “
17
” 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_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_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()
The typical usage of find_package
and these variables to configure a
build requiring Geant4 is thus:
find_package(Geant4 REQUIRED) # Find Geant4
add_executable(myg4app myg4app.cc) # Compile application
target_link_libraries(myg4app ${Geant4_LIBRARIES}) # Link it to Geant4
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 11.0 REQUIRED)
would make CMake search for a Geant4 install whose version number is greater than or equal to 11.0. An exact version number may also be specified:
find_package(Geant4 11.1.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 Multithreading in your applications 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.
smartstack
Geant4_smartstack_FOUND
isTRUE
if the install of Geant4 was built withG4SmartStack
use inG4TrackingManager
.php_as_hp
Geant4_php_as_hp_FOUND
isTRUE
if the install of Geant4 was built with ParticleHP as HP.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_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.vis_toolssg_x11_gles
Geant4_vis_toolssg_x11_gles_FOUND
isTRUE
if the install of Geant4 provides the ToolsSG visualization driver with X11 backend. Using this component allows use of the ToolsSG Visualization Driver in the linked application.vis_toolssg_xt_gles
Geant4_vis_toolssg_xt_gles_FOUND
isTRUE
if the install of Geant4 provides the ToolsSG visualization driver with Motif backend. Using this component allows use of the ToolsSG Visualization Driver in the linked application.vis_toolssg_qt_gles
Geant4_vis_toolssg_qt_gles_FOUND
isTRUE
if the install of Geant4 provides the ToolsSG visualization driver with Qt5 backend. Using this component allows use of the ToolsSG Visualization Driver in the linked application.vis_toolssg_windows_gles
Geant4_vis_toolssg_windows_gles_FOUND
isTRUE
if the install of Geant4 provides the ToolsSG visualization driver with Windows backend. Using this component allows use of the ToolsSG Visualization Driver in the linked application.vis_Vtk
Geant4_vis_Vtk_FOUND
isTRUE
if the install of Geant4 provides the Vtk visualization driver. Using this component allows use of the Vtk 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 preceding 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/use 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 together with the CMake Discourse Forum.
We also recommend the HEP Software Foundation CMake Tutorial and the CLIUtils Modern CMake Tutorial.
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:
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
--features print list of features
--sh print shell commands required to set environment
variables for Geant4, which can be evaluated in
the calling shell with "eval $(geant4-config --sh)"
--csh print C shell commands required to set environment
variables for Geant4, which can be evaluated in
the calling shell with "eval `geant4-config --csh`"
--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[yes]
smartstack[no]
php_as_hp[no]
clhep[yes]
expat[no]
zlib[yes]
gdml[no]
ptl[yes]
usolids[no]
freetype[no]
hdf5[no]
g3tog4[no]
qt[no]
qt3d[no]
motif[no]
raytracer-x11[no]
opengl-x11[no]
openinventor[no]
vtk[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
.