Building and Installing from Source

On Unix Platforms

Unpack the Geant4 source package geant4-v11.2.0.tar.gz to a location of your choice. For illustration only, this guide will assume it’s been unpacked in a directory named /path/to, so that the Geant4 source package sits in a subdirectory

/path/to/geant4-v11.2.0

We refer to this directory as the source directory. The next step is to create a directory in which to configure and run the build and store the build products. This directory should not be the same as, or inside, the source directory. In this guide, we create this build directory alongside our source directory:

$ cd /path/to
$ mkdir geant4-v11.2.0-build
$ ls
geant4-v11.2.0  geant4-v11.2.0-build

To configure the build, change into the build directory and run CMake:

$ cd /path/to/geant4-v11.2.0-build
$ cmake -DCMAKE_INSTALL_PREFIX=/path/to/geant4-v11.2.0-install /path/to/geant4-v11.2.0

Here, the CMake Variable CMAKE_INSTALL_PREFIX is used to set the install directory, the directory under which the Geant4 libraries, headers and support files will be installed. It must be supplied as an absolute path. The second argument to CMake is the path to the source directory. In this example, we have used the absolute path to the source directory, but you can also use the relative path from your build directory to your source directory.

Additional arguments may be passed to CMake to activate optional components of Geant4, such as visualization drivers, or tune the build and install parameters. See Geant4 Build Options for details of these options. If you run CMake and decide afterwards you want to activate additional options, simply rerun CMake in the build directory, passing it the extra options plus the build directory path. For example, after running CMake as above, you may wish to activate the installation of Geant4’s datasets, so you would run (in the build directory)

$ cd /path/to/geant4-v11.2.0-build
$ cmake -DGEANT4_INSTALL_DATA=ON .

On executing the CMake command, it will run to configure the build and generate Unix Makefiles to perform the actual build. CMake has the capability to generate buildscripts for other tools, such as Eclipse and Xcode, but please note that we do not support user installs of Geant4 with these tools. On Linux, you will see output similar to:

$ cmake -DCMAKE_INSTALL_PREFIX=/path/to/geant4-v11.2.0-install /path/to/geant4-v11.2.0
-- The C compiler identification is GNU 8.3.0
-- The CXX compiler identification is GNU 8.3.0

... System dependent output not shown for clarity ...

-- Pre-configuring dataset G4NDL (4.7)
-- Pre-configuring dataset G4EMLOW (8.5)
-- Pre-configuring dataset PhotonEvaporation (5.7)
-- Pre-configuring dataset RadioactiveDecay (5.6)
-- Pre-configuring dataset G4PARTICLEXS (4.0)
-- Pre-configuring dataset G4PII (1.3)
-- Pre-configuring dataset RealSurface (2.2)
-- Pre-configuring dataset G4SAIDDATA (2.0))
-- Pre-configuring dataset G4ABLA (3.3)
-- Pre-configuring dataset G4INCL (1.2)
-- Pre-configuring dataset G4ENSDFSTATE (2.3)
  *WARNING*
    Geant4 has been pre-configured to look for datasets
    in the directory:

    /Users/YourUsername/Geant4/geant4-v11.2.0-install/share/Geant4-11.2.0/data

    but the following datasets are NOT present on disk at
    that location:

    G4NDL (4.7)
    G4EMLOW (8.5)
    PhotonEvaporation (5.7)
    RadioactiveDecay (5.6)
    G4PARTICLEXS (4.0)
    G4PII (1.3)
    RealSurface (2.2)
    G4SAIDDATA (2.0))
    G4ABLA (3.3)
    G4INCL (1.2)
    G4ENSDFSTATE (2.3)

    If you want to have these datasets installed automatically
    simply re-run cmake and set the GEANT4_INSTALL_DATA
    variable to ON. This will configure the build to download
    and install these datasets for you. For example, on the
    command line, do:

    cmake -DGEANT4_INSTALL_DATA=ON <otherargs>

    The variable can also be toggled in ccmake or cmake-gui.
    If you're running on a Windows system, this is the best
    solution as CMake will unpack the datasets for you
    without any further software being required

    Alternatively, you can install these datasets manually
    now or after you have installed Geant4. To do this,
    download the following files:

    https://cern.ch/geant4-data/datasets/G4NDL.4.7.tar.gz
    https://cern.ch/geant4-data/datasets/G4EMLOW.8.5.tar.gz
    https://cern.ch/geant4-data/datasets/G4PhotonEvaporation.5.7.tar.gz
    https://cern.ch/geant4-data/datasets/G4RadioactiveDecay.5.6.tar.gz
    https://cern.ch/geant4-data/datasets/G4PARTICLEXS.4.0.tar.gz
    https://cern.ch/geant4-data/datasets/G4PII.1.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4RealSurface.2.2.tar.gz
    https://cern.ch/geant4-data/datasets/G4SAIDDATA.2.0.tar.gz
    https://cern.ch/geant4-data/datasets/G4ABLA.3.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4ENSDFSTATE.2.3.tar.gz

    and unpack them under the directory:

    /Users/YourUsername/Geant4/geant4-v11.2.0-install/share/Geant4-11.2.0/data

    As we supply the datasets packed in gzipped tar files,
    you will need the 'tar' utility to unpack them.

    Nota bene: Missing datasets will not affect or break
    compilation and installation of the Geant4
    libraries.

... System dependent output not shown for clarity ...

-- The following Geant4 features are enabled:
CMAKE_CXX_STANDARD: Compiling against C++ Standard '17'
GEANT4_BUILD_MULTITHREADED: Build multithread enabled libraries
GEANT4_BUILD_TLS_MODEL: Building with TLS model 'initial-exec'
GEANT4_USE_SYSTEM_EXPAT: Using system EXPAT library

-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/geant4-v11.2.0-build

The exact output will as noted depend on the exact platform/compiler in use, and how the build has been configured, but the last three lines should be the same to within path differences. These indicate a successful configuration.

The warning message about datasets is simply an advisory. Due to the size of the datasets, Geant4 will try and reuse any datasets it can find under the data installation prefix, in our example case /path/to/geant4-v11.2.0-install/share/Geant4-11.2.0/data. If any datasets are not found here, it will pre-configure Geant4 (described in Postinstall Setup) to use this location and emit the message to advise you on the steps you need to take to manually install the datasets at a time of your convenience.

Datasets are not required to be present to build Geant4, but may be required to run your application, depending on the physics models you use. If you wish to download and install the datasets automatically as part of your build of Geant4, simply add the option -DGEANT4_INSTALL_DATA=ON to the arguments passed to CMake. Note that this requires a working network connection and will download around 0.5GB of data. If you already have the datasets present on your system, you can point Geant4 to their location. See the GEANT4_INSTALL_DATADIR option described Standard Options for more details.

If you see any errors at this point, carefully check the error messages output by CMake, and check your install of CMake and C++ compiler first. The default configuration of Geant4 is very simple, and provided CMake and the compiler are installed correctly, you should not see errors.

After the configuration has run, CMake will have generated Unix Makefiles for building Geant4. To run the build, simply execute make in the build directory:

$ make -jN

where N is the number of parallel jobs you require (e.g. if your machine has a dual core processor, you could set N to 2).

The build will now run, and will output information on the progress of the build and current operations. If you need more output to help resolve issues or simply for information, run make as:

$ make -jN VERBOSE=1

Once the build has completed, you can install Geant4 to the directory you specified earlier in CMAKE_INSTALL_PREFIX by running:

$ make install

in the build directory. The libraries, headers and resource files are installed under your chosen install prefix in a standard Unix-style hierarchy of directories, described below in Postinstall Setup. If you are performing a staged install for packaging or deployment, the CMake generated Makefiles support the DESTDIR variable for copying to a temporary location. To uninstall Geant4 you can run:

$ make uninstall

which will remove all installed files but not any installed directories.

On Windows Platforms

The easiest way to build and install Geant4 from source on Windows platforms is to use the Windows command line program cmd plus CMake’s command line interface to the MSBuild tool supplied with Visual Studio. Whilst the full Visual Studio GUI can be used, cmd and CMake/MSBuild provide a simpler interface and the commands can be used inside scripts. You can also use PowerShell instead of cmd if you prefer, and the instructions below should transfer barring minor syntax differences. Builds of Geant4 using Cygwin or MinGW with their own compilers or the Microsoft C++ Compiler are neither supported or tested, though the CMake system is expected to work under these toolchains. If you are using these tools via their native shells and with their own versions of CMake, then the instructions for building and installing on Unix platforms On Unix Platforms can be used.

To ensure that the appropriate Visual Studio paths and settings are set up for building, open a Visual Studio Developer cmd window from Start → Visual Studio 201X → Visual Studio Tools → Developer Command Prompt for VS201X. After running this, confirm that you have the MSVC compiler available by running the cl command, and you should see (NB, in the following, the cmd prompt is shown as a > for clarity):

> cl
Microsoft (R) C/C++ Optimizing Compiler Version 19.25.28614 for x86
Copyright (C) Microsoft Corporation.  All rights reserved.

usage: cl [ option... ] filename... [ /link linkoption... ]

The exact version number of cl may differ slightly, but for Visual Studio 2019 the first element of the Compiler Version should be at least 19.

To begin building Geant4, unpack the source package geant4-v11.2.0.zip to a location of your choice. For illustration only, this guide will assume it’s been unpacked in a directory named C:\Users\YourUsername\Geant4, so that the Geant4 source package sits in a subdirectory C:\Users\YourUsername\Geant4\geant4-v11.2.0

We refer to this directory as the source directory. The next step is to create a directory in which to configure and run the build and store the build products. This directory should not be the same as, or inside, the source directory. In this guide, we create this build directory alongside our source directory:

> cd %HOMEPATH%\Geant4
> dir /B
geant4-v11.2.0

> mkdir geant4-v11.2.0-build
> dir /B
geant4-v11.2.0
geant4-v11.2.0-build

To configure the build, change into the build directory and run CMake:

> cd %HOMEPATH%\Geant4\geant4-v11.2.0-build
> cmake -DCMAKE_INSTALL_PREFIX="%HOMEPATH%\Geant4\geant4-v11.2.0-install" "%HOMEPATH%\Geant4\geant4-v11.2.0"

Here, the CMake Variable CMAKE_INSTALL_PREFIX is used to set the install directory, the directory under which the Geant4 libraries, headers and support files will be installed. It must be supplied as an absolute path. The second argument to CMake is the path to the source directory. In this example, we have used the absolute path to the source directory, but you can also use the relative path from your build directory to your source directory. Paths should be quoted in case they contain spaces.

Additional arguments may be passed to CMake to activate optional components of Geant4, such as visualization drivers, or tune the build and install parameters. See Geant4 Build Options for details of these options. If you run CMake and decide afterwards you want to activate additional options, simply rerun CMake in the build directory, passing it the extra options plus the build directory. For example, after running CMake as above, you may wish to activate the installation of Geant4’s datasets, so you would run

> cd %HOMEPATH%\Geant4\geant4-v11.2.0-build
> cmake -DGEANT4_INSTALL_DATA=ON .

On executing the CMake command, it will run to configure the build and generate Visual Studio Project files to perform the actual build. CMake has the capability to generate buildscripts for other tools, such as NMake and Ninja, but please note that these are not supported for builds of Geant4 on Windows yet. With Visual Studio, you should see output similar to

> cmake -DCMAKE_INSTALL_PREFIX="%HOMEPATH%\Geant4\geant4-v11.2.0-install" "%HOMEPATH%\Geant4\geant4-v11.2.0"
-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
-- The C compiler identification is MSVC 19.25.28614.0
-- The CXX compiler identification is MSVC 19.25.28614.0

... System dependent output omitted for clarity ...

-- Pre-configuring dataset G4NDL (4.7)
-- Pre-configuring dataset G4EMLOW (8.5)
-- Pre-configuring dataset PhotonEvaporation (5.7)
-- Pre-configuring dataset RadioactiveDecay (5.6)
-- Pre-configuring dataset G4PARTICLEXS (4.0)
-- Pre-configuring dataset G4PII (1.3)
-- Pre-configuring dataset RealSurface (2.2)
-- Pre-configuring dataset G4SAIDDATA (2.0))
-- Pre-configuring dataset G4ABLA (3.3)
-- Pre-configuring dataset G4INCL (1.2)
-- Pre-configuring dataset G4ENSDFSTATE (2.3)
  *WARNING*
    Geant4 has been pre-configured to look for datasets
    in the directory:

    /Users/YourUsername/Geant4/geant4-v11.2.0-install/share/Geant4-11.2.0/data

    but the following datasets are NOT present on disk at
    that location:

    G4NDL (4.7)
    G4EMLOW (8.5)
    PhotonEvaporation (5.7)
    RadioactiveDecay (5.6)
    G4PARTICLEXS (4.0)
    G4PII (1.3)
    RealSurface (2.2)
    G4SAIDDATA (2.0))
    G4ABLA (3.3)
    G4INCL (1.2)
    G4ENSDFSTATE (2.3)

    If you want to have these datasets installed automatically
    simply re-run cmake and set the GEANT4_INSTALL_DATA
    variable to ON. This will configure the build to download
    and install these datasets for you. For example, on the
    command line, do:

    cmake -DGEANT4_INSTALL_DATA=ON <otherargs>

    The variable can also be toggled in ccmake or cmake-gui.
    If you're running on a Windows system, this is the best
    solution as CMake will unpack the datasets for you
    without any further software being required

    Alternatively, you can install these datasets manually
    now or after you have installed Geant4. To do this,
    download the following files:

    https://cern.ch/geant4-data/datasets/G4NDL.4.7.tar.gz
    https://cern.ch/geant4-data/datasets/G4EMLOW.8.5.tar.gz
    https://cern.ch/geant4-data/datasets/G4PhotonEvaporation.5.7.tar.gz
    https://cern.ch/geant4-data/datasets/G4RadioactiveDecay.5.6.tar.gz
    https://cern.ch/geant4-data/datasets/G4PARTICLEXS.4.0.tar.gz
    https://cern.ch/geant4-data/datasets/G4PII.1.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4RealSurface.2.2.tar.gz
    https://cern.ch/geant4-data/datasets/G4SAIDDATA.2.0.tar.gz
    https://cern.ch/geant4-data/datasets/G4ABLA.3.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4ENSDFSTATE.2.3.tar.gz

    and unpack them under the directory:

    /Users/YourUsername/Geant4/geant4-v11.2.0-install/share/Geant4-11.2.0/data

    As we supply the datasets packed in gzipped tar files,
    you will need the 'tar' utility to unpack them.

    Nota bene: Missing datasets will not affect or break
    compilation and installation of the Geant4
    libraries.

-- The following Geant4 features are enabled:
CMAKE_CXX_STANDARD: Compiling against C++ Standard '17'
GEANT4_BUILD_MULTITHREADED: Build multithread enabled libraries

-- Configuring done
-- Generating done
-- Build files have been written to: C:/Users/YourUsername/Geant4/geant4-v11.2.0-build

The output will differ slightly for different systems/configuration, and due to the source/build paths being for illustration only, but the last three lines at least should be the same to within path differences. These indicate a successful configuration.

The warning message about datasets is simply an advisory. Due to the size of the datasets, Geant4 will try and reuse any datasets it can find under the data installation prefix, in our example case C:\Users\YourUsername\Geant4\geant4-v11.2.0-install\share\Geant4-11.2.0\data. If any datasets are not found here, the message is emitted to advise you of the steps you need to take to manually install the datasets at a time of your convenience.

Datasets are not required to be present to build Geant4, but may be required to run your application, depending on the physics models you use. If you wish to download and install the datasets automatically as part of your build of Geant4, simply add the option -DGEANT4_INSTALL_DATA=ON to the arguments passed to CMake. Note that this requires a working network connection and will download around 0.5GB of data. If you already have the datasets present on your system, you can point Geant4 to their location. See the GEANT4_INSTALL_DATADIR option described Standard Options for more details.

If you see any errors at this point, carefully check the error messages output by CMake, and check your install of CMake and Visual Studio first. The default configuration of Geant4 is very simple, and provided CMake and Visual Studio are installed correctly, you should not see errors.

After the configuration has run, CMake will have generated Visual Studio Solution files for building Geant4. CMake itself can be used to run the build by executing the command:

> cmake --build . --config Release

Here, the --build argument takes the path to the build directory, in this case we are running from the build directory so it is just the current working directory. The --config argument takes the configuration we want to build (Visual Studio, unlike Make, can support multiple configurations in the same project) and Release is chosen to provide fully optimised libraries for best performance. If you are developing applications and require debugging information, then you should change this argument to RelWithDebInfo.

The build will now run, and will output information on the progress of the build and current operations. By default, Visual Studio Solutions do not enable parallel compilation of files for faster builds. Geant4’s CMake system provides an option to enable this, so if you have a multicore system, you can add the option -DGEANT4_BUILD_MSVC_MP=ON to the arguments passed to CMake. Once the build has completed the headers, libraries and support files can be installed by running the command:

> cmake --build . --config Release --target install

This command may also be invoked immediately after configuration to build and install Geant4 in one step. The file and directory structure of the installation follows that of the Unix build, and is described in Postinstall Setup.

Geant4 Build Options

Both On Unix Platforms and On Windows Platforms give the minimal procedure to build and install Geant4 on these platforms. Many additional options can be passed to CMake to adjust the way Geant4 is built and installed and to enable optional components.

Options are divided into Standard Options, which any user or developer can set directly, and Advanced Options, which in general are only needed by advanced users, developers or to give very fine control over the build and install. Some options enable components of Geant4 which require external software (as listed in Geant4 System/Software Prerequisites). If these options are enabled, the required software will be searched for, and hence there are also options which control where CMake should look for these packages. If a required software package is not found, then CMake will exit with an error message detailing what was not found.

These options may be set by passing their name and value to the cmake command via -D flags. For example:

$ cmake -DCMAKE_INSTALL_PREFIX=/opt/geant4 -DGEANT4_USE_GDML=ON /path/to/geant4-source

would configure the build of Geant4 for installation under /opt/geant4 and compilation of support for GDML.

If you have already created a build directory and used CMake to configure the build, you can always rerun CMake in that directory with new options to regenerate the buildscripts (Makefiles or IDE solutions). You can also deactivate a previously selected option to remove a component from the build. For example, if we had configured a build to enable GDML support and wanted to remove it, we could run:

$ cmake -DGEANT4_USE_GDML=OFF .

Note that this assumes we are running cmake in a previously configured build directory so we only need pass the current working directory rather than the full source directory path.

If you reconfigure to unset an option and rebuild and reinstall, your install may contain files installed by the previously set option (for example headers). In this case, you should build the uninstall target before reconfiguring to guarantee removal of these files.

Warning

After every invocation of cmake that introduces or changes an option you should rebuild as described above.

CMake also provides Curses (UNIX only) and Qt (UNIX and Windows) based Terminal/GUI interfaces which may be used to browse and set options. Please see the CMake documentation for more information on these interfaces.

Standard Options

We list standard options here in logical order. If you use CMake’s curses or GUI interfaces, they will be listed alphabetically. Where third-party software requirements are listed, please consult Geant4 System/Software Prerequisites for links and information on these packages.

  • CMAKE_INSTALL_PREFIX

    • Sets the installation prefix for Geant4. Equivalent to --prefix in Autotools. The default is platform dependent:

      Unix: /usr/local

      Windows: C:\Program Files\Geant4

      It should be supplied as an absolute path, otherwise CMake will interpret its value relative to your build directory.

      See also the CMAKE_INSTALL_XXXDIR Advanced Options for fine control of installation locations.

  • CMAKE_BUILD_TYPE : (DEFAULT : Release)

    • Sets the type of build. It defaults to Release which gives a fully optimised build without debugging symbols. The most useful values are:

      Release : Optimised build, no debugging symbols

      Debug : Debugging symbols, no optimisation

      RelWithDebInfo : Optimised build with debugging symbols

      See Options for Changing the Compiler and Build Flags for the compiler flags used in each mode.

      Note that if you use a build system which supports multiconfiguration builds (e.g. Xcode and Visual Studio), this variable has no effect. For these systems, all build types are available inside the CMake generated project and can be selected in the tool itself or via the --config argument to cmake --build, e.g. cmake --build . --config Debug.

  • GEANT4_BUILD_MULTITHREADED : (DEFAULT : ON)

    • If set to ON, build Geant4 libraries with support for multithreading.

      Requires: Compiler/C++ Standard Library with support for C++ Threading

  • GEANT4_INSTALL_DATA : (DEFAULT : OFF)

    • If set to ON, download and install any Geant4 datasets missing from GEANT4_INSTALL_DATADIR. Each dataset will be unpacked and installed in the directory pointed to by GEANT4_INSTALL_DATADIR.

      Requires: A working network connection. It is highly recommended to switch this option on if you have a network connection to give the best integration with application development.

  • GEANT4_INSTALL_DATADIR : (DEFAULT : CMAKE_INSTALL_DATAROOTDIR)

    • Installation directory for Geant4 datasets. It can be supplied as a path relative to CMAKE_INSTALL_PREFIX or as an absolute path. It is always searched for existing datasets, which if present will be reused.

  • GEANT4_USE_G3TOG4 : (DEFAULT : OFF)

    • If set to ON, build the G3ToG4 library for reading ASCII call list files generated from Geant3 geometries.

  • GEANT4_USE_GDML : (DEFAULT : OFF)

    • If set to ON, build the G4persistency library with support for GDML.

      Requires: Xerces-C++ libraries and headers. See the CMAKE_PREFIX_PATH Advanced Options or the CMake FindXercesC documentation if CMake has trouble locating Xerces-C

  • GEANT4_USE_INVENTOR (DEFAULT : OFF)

    • If set to ON, build the X11/Win32 OpenInventor visualization driver.

      Requires: Coin3D Open Inventor implementation, SoXt (Unix) or SoWin (Windows) binding, and OpenGL libraries and headers.

      See the CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating Coin3D or SoXt/SoWin.

      Known Issue: Use of clang compiler and Debug build mode will cause the Inventor driver build to fail with errors relating to Inventor specific debugging functions.

  • GEANT4_USE_INVENTOR_QT (DEFAULT : OFF)

    • If set to ON, build the OpenInventorQt visualization driver.

      Note that enabling this option will disable build of the X11/Win OpenInventor driver as only one binding can be present.

      Requires: Coin3D Open Inventor implementation plus SoQt binding and Qt5 libraries and headers.

      See the CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating Coin3D or SoQt.

  • GEANT4_USE_OPENGL_WIN32 (DEFAULT : OFF, Windows Only)

    • If set to ON, build the Win32 OpenGL visualization driver.

      Requires: OpenGL libraries and headers.

  • GEANT4_USE_OPENGL_X11 (DEFAULT : OFF, Unix Only)

    • If set to ON, build the X11 OpenGL visualization driver.

      Requires: X11 and OpenGL libraries and headers.

  • GEANT4_USE_QT (DEFAULT : OFF)

    • If set to ON, build Qt User Interface and Visualization drivers.

      Requires: Qt5 and OpenGL libraries and headers.

      See the CMAKE_PREFIX_PATH variable under Advanced Options if CMake has trouble locating Qt.

  • GEANT4_USE_RAYTRACER_X11 (DEFAULT : OFF, Unix only)

    • If set to ON, build RayTracer visualization driver with X11 support.

      Requires: X11 libraries and headers.

  • GEANT4_USE_SYSTEM_CLHEP (DEFAULT : OFF)

    • If set to ON, build Geant4 with an external install of CLHEP. You should not set this unless your usage of Geant4 mandates a specific external CLHEP installation (e.g. if your project’s software uses CLHEP in other tools and requires consistent use of the same CLHEP across the software stack).

      Requires: CLHEP libraries and headers. See the CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating CLHEP.

  • GEANT4_USE_SYSTEM_EXPAT (DEFAULT : ON)

    • If set to ON, build Geant4 with an external install of Expat. Whilst Expat is installed on the vast majority of systems, it may be missing in certain instances. In these cases, simply switch this option to OFF and Geant4 will build and use its internal version of Expat.

      Requires: Expat library and headers. See the CMAKE_PREFIX_PATH Advanced Options or the CMake documentation for FindEXPAT if CMake has trouble locating Expat.

  • GEANT4_USE_SYSTEM_ZLIB (DEFAULT : OFF)

    • If set to ON, build Geant4 with an external install of zlib.

      Requires: Zlib library and headers. See the CMAKE_PREFIX_PATH Advanced Options or the CMake documentation for FindEXPAT if CMake has trouble locating ZLIB.

  • GEANT4_USE_VTK : (DEFAULT : OFF)

    • If set to ON, build the VTK Visualization driver.

      Requires: VTK libraries and headers.

  • GEANT4_USE_XM (DEFAULT : OFF, Unix Only)

    • If set to ON, build Motif User Interface and Visualization drivers.

      Requires: Motif and OpenGL libraries and headers. See the CMAKE_PREFIX_PATH Advanced Options or the CMake documentation for FindMotif if CMake has trouble locating Motif.

Advanced Options

Most installs should never need to touch these options, and are primarily to give advanced users more control over the build, enable experimental features, and to help CMake locate needed software packages. Advanced options and variables can be set like the standard ones listed earlier using -D arguments to cmake. In CMake’s curses and GUI interfaces these options can be displayed by pressing t in ccmake, or clicking the ‘advanced’ check box in the CMake GUI.

In the list below, we only list those options most relevant for Geant4. Many additional core CMake variables are available, for which you should consult the Reference Documentation section of the main CMake documentation , and specifically the sections on Variables. The following list is presented in semi-alphabetical order, with grouping by task where appropriate.

  • BUILD_SHARED_LIBS : (DEFAULT : ON)

    • If set to ON build Geant4 shared libraries.

  • BUILD_STATIC_LIBS : (DEFAULT : OFF)

    • If set to ON, build Geant4 static libraries.

  • CMAKE_CXX_STANDARD : (DEFAULT : 17)

    • Compile Geant4 against given C++ standard ( 17, 20, or 23). Geant4 is written in C++17, and you should use this option if your application requires support for the newer standard. If you set the variable to a standard the compiler does not support, an error will be emitted.

      Requires: C++ Compiler with support for the requested standard.

  • CMAKE_INSTALL_BINDIR : (DEFAULT : bin)

    • Installation directory for Geant4 Toolkit executables. It can be supplied as a path relative to CMAKE_INSTALL_PREFIX or as an absolute path.

  • CMAKE_INSTALL_INCLUDEDIR : (DEFAULT : include)

    • Installation directory for Geant4 C/C++ headers. It can be supplied as a path relative to CMAKE_INSTALL_PREFIX or as an absolute path. The headers will always be installed in a subdirectory of CMAKE_INSTALL_INCLUDEDIR named Geant4.

  • CMAKE_INSTALL_LIBDIR : (DEFAULT : lib(+?SUFFIX))

    • Installation directory for object code libraries. It can be supplied as a path relative to CMAKE_INSTALL_PREFIX, or an absolute path. When the default is used, SUFFIX will be set to 64 on 64bit Linux platforms apart from Debian systems.

  • CMAKE_INSTALL_DATAROOTDIR : (DEFAULT : share)

    • Installation directory for read-only architecture-independent data files. It can be supplied as a path relative to CMAKE_INSTALL_PREFIX, or an absolute path.

  • GEANT4_INSTALL_DATA_TIMEOUT : (DEFAULT : 1500)

    • Sets the time in seconds allowed for download of each Geant4 dataset. The value can be increased if you are on a slow network connection and require more time to download.

  • GEANT4_INSTALL_EXAMPLES : (DEFAULT : ON)

    • Set to OFF to prevent installation of the source code and documentation for the Geant4 examples.

  • GEANT4_INSTALL_PACKAGE_CACHE : (DEFAULT : ON)

    • If set to ON, install a file containing the locations of external dependencies as used when building this install of Geant4.

      If you are packaging (e.g. rpm, deb, spack, Homebrew, etc) Geant4, it is recommended to set this option to OFF to disable install of the cache file and make the package relocatable. Your install of Geant4 will then rely on CMAKE_PREFIX_PATH and other variables used by CMake to re-find any needed dependencies. Alternately, if your packaging system allows install-time patching, you may install the cache file and patch it at that time with known paths to the dependencies at that point. In both cases, it is your responsibility to setup/patch the environment/cache file correctly and as appropriate.

      WARNING: This option is only intended for the packaging case outlined above, and is not recommended for single-user installs of Geant4.

  • GEANT4_INSTALL_DATASETS_TENDL : (DEFAULT :OFF)

    • If set to ON, enable download and install of the optional TENDL dataset.

  • GEANT4_BUILD_MSVC_MP : (Windows Only, DEFAULT : OFF)

    • If set to ON, add /MP to CMAKE_CXX_FLAGS to enable file level parallel compilation when using MSVC and MSBuild. Note that this only works when building Geant4 using Visual Studio Solutions.

  • GEANT4_BUILD_TLS_MODEL : (DEFAULT : initial-exec (UNIX only))

    • If building Geant4 with multithreading support, use a specific model for Thread Local Storage ( initial-exec, local-exec, global-dynamic, local-dynamic or auto). If you set the variable to a model unknown to the compiler, an error will be emitted.

      Geant4’s default model of initial-exec is chosen to give the best performance under a wide variety of use cases.

      The special auto value leaves the choice of TLS model to the compiler.

      Requires: GEANT4_BUILD_MULTITHREADED set to ON

  • GEANT4_BUILD_STORE_TRAJECTORY : (DEFAULT : ON)

    • If set to ON, store trajectories in event processing. It can be switched to OFF to give a degree of performance improvement, but you will not be able to visualise events.

  • GEANT4_BUILD_VERBOSE_CODE : (DEFAULT : ON)

    • If set to ON, build Geant4 libraries with extra verbosity. It can be switched to OFF to give a degree of performance improvement, but you will not have as much information output should you run into problems or need to debug.

  • GEANT4_BUILD_BUILTIN_BACKTRACE : (DEFAULT : OFF)

    • If set to ON, build Geant4 Run Manager with signal handling using G4Backtrace. This provides simple backtrace reporting, but should not be set to ON if you application implements/requires its own signal handling.

  • GEANT4_BUILD_PHP_AS_HP : (DEFAULT : OFF)

    • If set to ON, build the ParticleHP model as HP.

  • GEANT4_USE_QT_QT6 : (DEFAULT : OFF)

    • If set to ON when GEANT4_USE_QT is ON, search for and use Qt6 instead of Qt5.

      Requires: Qt6 libraries and headers. See the CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating Qt6.

      WARNING: Use of Qt6 in Geant4 is currently in beta and full functionality is not guaranteed. If you enable this option and also build the VTK and SoQt drivers, those dependencies must have been built and linked against Qt6 as well. If you have both Qt5 and Qt6 installed on your system, you may need to be careful of header path ordering.

  • GEANT4_USE_SMARTSTACK : (DEFAULT : OFF)

    • If set to ON, use G4SmartStack in G4TrackingManager.

  • GEANT4_USE_SYSTEM_PTL (DEFAULT : OFF)

  • GEANT4_USE_TBB (DEFAULT : OFF)

    • If set to ON, use Intel TBB as the Tasking backend for PTL.

      Requires: Intel TBB libraries and headers. See the CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating TBB

  • GEANT4_ENABLE_TESTING : (DEFAULT : OFF)

    • If set to ON, build and run Geant4 testing suites.

      WARNING: this option is for Geant4 system testing only and is not intended for use by users. No support is, or will be, provided for user builds with this option.

  • GEANT4_USE_FREETYPE : (DEFAULT : OFF)

    • If set to ON, build Geant4 Analysis library with support for Freetype font rendering.

      Requires: Freetype libraries and headers.

  • GEANT4_USE_HDF5 : (DEFAULT : OFF)

    • If set to ON, build Geant4 Analysis library with support for HDF5 persistency.

      WARNING: use of HDF5 is experimental and should be used with caution.

      Requires: HDF5 C libraries and headers, compiled in threadsafe mode if Geant4 is built with multithreading support.

  • GEANT4_USE_USOLIDS : (DEFAULT : OFF)

    • If set to ON, replace Geant4 solids with VecGeom equivalents.

      WARNING: the use of VecGeom is experimental and should be used with caution.

      Requires: VecGeom libraries and headers.

  • GEANT4_USE_TIMEMORY : (DEFAULT : OFF)

    • If set to ON, build Geant4 with support for memory/CPU profiling with TiMemory.

      Requires: TiMemory library and headers.

  • CMAKE_PREFIX_PATH

    • If you have software packages required by Geant4 installed in custom locations, this variable can be set to list these prefixes to help CMake locate the packages. For example, if Xerces-C is needed and installed in /custom/xerces-c, then CMAKE_PREFIX_PATH could be set on the command line as:

      cmake -DCMAKE_PREFIX_PATH="/custom/xerces-c" <otherargs>

      Additional paths may be added, separated by semicolons, e.g.:

      cmake -DCMAKE_PREFIX_PATH="/A;/B;/C" <otherargs>

      CMAKE_PREFIX_PATH may also be set in the environment with paths separated by the appropriate element separator for the platform (“:” on UNIX, “;” on Windows).

Options for Changing the Compiler and Build Flags

CMake will, by default, select the first C and C++ compilers it finds in your PATH. To specify the C and C++ compilers to be used, you can set the CC and CXX variables:

$ # ... assuming clang/clang++ are in the PATH ...

$ CC=clang CXX=clang++ cmake <otherargs>

$ # ... or ...

$ export CC=clang
$ export CXX=clang++
$ cmake <otherargs>

You can also use a full path should the compilers not be in the PATH or via the CMAKE_<LANG>_COMPILER options:

cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ <otherargs>

Use of CMAKE_<LANG>_COMPILER will take precedence over any setting of CC or CXX in the environment or on the command line.

Whilst you can change the compiler after an initial configuration with CMake, it is not recommended as you may need to reset some variables by hand. If you are building Geant4 using several compilers and/or versions, we strongly recommend creating one build directory per compiler system. Whilst this takes extra disk space, it provides a clean separation between different builds and also allows fast incremental builds against a single source directory.

Geant4’s CMake scripts configure a set of flags for use with each supported compiler as follows. CMAKE_CXX_FLAGS are always applied, with the CMAKE_CXX_FLAGS_<MODE> being appended when building in the given <MODE> (e.g. “Release”). If you are using an unsupported or unrecognised compiler, CMake will default to a standard and very simple set of flags.

  • GNU Compiler Collection

    • CMAKE_CXX_FLAGS : -W -Wall -pedantic -Wno-non-virtual-dtor -Wno-long-long -Wwrite-strings -Wpointer-arith -Woverloaded-virtual -Wno-variadic-macros -Wshadow -pipe

    • CMAKE_CXX_FLAGS_RELEASE : -O3 -DNDEBUG -fno-trapping-math -ftree-vectorize -fno-math-errno

    • CMAKE_CXX_FLAGS_DEBUG : -g

    • CMAKE_CXX_FLAGS_RELWITHDEBINFO : -O2 -g

  • Clang

    • CMAKE_CXX_FLAGS : -W -Wall -pedantic -Wno-non-virtual-dtor -Wno-long-long -Wwrite-strings -Wpointer-arith -Woverloaded-virtual -Wno-variadic-macros -Wshadow -pipe -Qunused-arguments

    • CMAKE_CXX_FLAGS_RELEASE : -O3 -DNDEBUG -fno-trapping-math -ftree-vectorize -fno-math-errno

    • CMAKE_CXX_FLAGS_DEBUG : -g

    • CMAKE_CXX_FLAGS_RELWITHDEBINFO : -O2 -g

  • Microsoft Visual C++

    • CMAKE_CXX_FLAGS : -GR -EHsc -Zm200 -nologo -D_CONSOLE -D_WIN32 -DWIN32 -DOS -DXPNET -D_CRT_SECURE_NO_DEPRECATE

    • CMAKE_CXX_FLAGS_RELEASE : -MD -Ox -DNDEBUG

    • CMAKE_CXX_FLAGS_DEBUG : -MDd -Od -Zi

    • CMAKE_CXX_FLAGS_RELWITHDEBINFO : -MD -O2 -Zi

  • Intel

    • CMAKE_CXX_FLAGS : -w1 -Wno-non-virtual-dtor -Wpointer-arith -Wwrite-strings -fp-model precise

    • CMAKE_CXX_FLAGS_RELEASE : -O3 -DNDEBUG

    • CMAKE_CXX_FLAGS_DEBUG : -g

    • CMAKE_CXX_FLAGS_RELWITHDEBINFO : -O2 -g

For the GNU, Clang and Intel compilers, an additional flag selecting the C++ standard to compile against will be set. By default, this will use the minimum required C++17 standard. This can be changed if the compiler version supports it by setting the CMake variable CMAKE_CXX_STANDARD to the required standard, as described in Advanced Options.

When Geant4 is built with support for multithreading (GEANT4_BUILD_MULTITHREADED set to ON), the following additional flags are added to all build types for the GNU, Clang and Intel compilers:

  • -ftls-model=initial-exec -pthread

Note that the model passed to the -ftls-model argument can be changed using the GEANT4_BUILD_TLS_MODEL option described in Advanced Options. The additional auto option to GEANT4_BUILD_TLS_MODEL does not set additional flags, leaving the selection of TLS model to the compiler.

Whilst we strongly recommend the default set of flags as described above, they may be modified. CMake is aware of the CFLAGS and CXXFLAGS variables, so these may be set on the command line or as environment variables like the CC and CXX options above. However, note that these will only prepend extra flags to the default CMAKE_<LANG>_FLAGS. If you need to completely change the compiler flags, then you can set CMAKE_<LANG>_FLAGS directly as a -D option to CMake. This will override all defaults set by Geant4’s CMake scripts. Compiler flags can be interactively modified through the ccmake and CMake GUI interfaces. As compiler flags are an advanced option, you will need to activate viewing of advanced options. You may then edit the flags as you wish.