Building and Installing

On Unix Platforms

Unpack the Geant4 source package geant4.10.05.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.10.05

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.10.05-build
$ ls
geant4.10.05  geant4.10.05-build

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

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

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.10.05-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.10.05-install /path/to/geant4.10.05
-- The C compiler identification is GNU 4.9.2
-- The CXX compiler identification is GNU 4.9.2
-- Check for working C compiler: /usr/bin/gcc-4.9
-- Check for working C compiler: /usr/bin/gcc-4.9 -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/g++-4.9
-- Check for working CXX compiler: /usr/bin/g++-4.9 -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Found EXPAT: /usr/lib64/libexpat.so (found version "2.0.1")
-- Looking for sys/types.h
-- Looking for sys/types.h - found
-- Looking for stdint.h
-- Looking for stdint.h - found
-- Looking for stddef.h
-- Looking for stddef.h - found
-- Check size of off64_t
-- Check size of off64_t - done
-- Looking for fseeko
-- Looking for fseeko - found
-- Looking for unistd.h
-- Looking for unistd.h - found
-- Pre-configuring dataset G4NDL (4.5)
-- Pre-configuring dataset G4EMLOW (7.7)
-- Pre-configuring dataset PhotonEvaporation (5.3)
-- Pre-configuring dataset RadioactiveDecay (5.3)
-- Pre-configuring dataset G4PARTICLEXS (1.1)
-- Pre-configuring dataset G4PII (1.3)
-- Pre-configuring dataset RealSurface (2.1.1)
-- Pre-configuring dataset G4SAIDDATA (2.0))
-- Pre-configuring dataset G4ABLA (3.1)
-- Pre-configuring dataset G4INCL (1.0)
-- Pre-configuring dataset G4ENSDFSTATE (2.2)
  *WARNING*
    Geant4 has been pre-configured to look for datasets
    in the directory:

    /path/to/geant4.10.05-install/share/Geant4-10.5.0/data

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

    G4NDL (4.5)
    G4EMLOW (7.7)
    PhotonEvaporation (5.3)
    RadioactiveDecay (5.3)
    G4PARTICLEXS (1.1)
    G4PII (1.3)
    RealSurface (2.1.1)
    G4SAIDDATA (2.0))
    G4ABLA (3.1)
    G4INCL (1.0)
    G4ENSDFSTATE (2.2)

    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.5.tar.gz
    https://cern.ch/geant4-data/datasets/G4EMLOW.7.7.tar.gz
    https://cern.ch/geant4-data/datasets/G4PhotonEvaporation.5.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4RadioactiveDecay.5.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4PARTICLEXS.1.1.tar.gz
    https://cern.ch/geant4-data/datasets/G4PII.1.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4RealSurface.2.1.1.tar.gz
    https://cern.ch/geant4-data/datasets/G4SAIDDATA.2.0.tar.gz
    https://cern.ch/geant4-data/datasets/G4ABLA.3.1.tar.gz
    https://cern.ch/geant4-data/datasets/G4ENSDFSTATE.2.2.tar.gz

    and unpack them under the directory:

    /path/to/geant4.10.05-install/share/Geant4-10.5.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:
GEANT4_USE_SYSTEM_EXPAT: Using system EXPAT library

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

The exact output will differ depending on the exact platform/compiler in use, 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.10.05-install/share/Geant4-10.5.0/data. If any datasets are not found here, it will pre-configure the setup scripts for using Geant4 (described in Postinstall Setup) to point to 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.11.25547 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 17 the first element of the Compiler Version should be at least 19.

To begin building Geant4, unpack the source package geant4_10_05.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_10_05

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_10_05

> mkdir geant4_10_05-build
> dir /B
geant4_10_05
geant4_10_05-build

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

> cd %HOMEPATH%\Geant4\geant4_10_05-build
> cmake -DCMAKE_INSTALL_PREFIX="%HOMEPATH%\Geant4\geant4_10_05-install" "%HOMEPATH%\Geant4\geant4_10_05"

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_10_05-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 2017, you should see output similar to

> cmake -DCMAKE_INSTALL_PREFIX="%HOMEPATH%\Geant4\geant4_10_05-install" "%HOMEPATH%\Geant4\geant4_10_05"
-- Building for: Visual Studio 15 2017
-- The C compiler identification is MSVC 19.11.25547.0
-- The CXX compiler identification is MSVC 19.11.25547.0
-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.11.25503/bin/Hostx86/x86/cl.exe
-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.11.25503/bin/Hostx86/x86/cl.exe -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.11.25503/bin/Hostx86/x86/cl.exe
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.11.25503/bin/Hostx86/x86/cl.exe -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Looking for dlfcn.h
-- Looking for dlfcn.h - not found
-- Looking for fcntl.h
-- Looking for fcntl.h - found
-- Looking for inttypes.h
-- Looking for inttypes.h - found
-- Looking for memory.h
-- Looking for memory.h - found
-- Looking for stdint.h
-- Looking for stdint.h - found
-- Looking for stdlib.h
-- Looking for stdlib.h - found
-- Looking for strings.h
-- Looking for strings.h - not found
-- Looking for string.h
-- Looking for string.h - found
-- Looking for sys/stat.h
-- Looking for sys/stat.h - found
-- Looking for sys/types.h
-- Looking for sys/types.h - found
-- Looking for unistd.h
-- Looking for unistd.h - not found
-- Looking for getpagesize
-- Looking for getpagesize - not found
-- Looking for bcopy
-- Looking for bcopy - not found
-- Looking for memmove
-- Looking for memmove - found
-- Looking for mmap
-- Looking for mmap - not found
-- Looking for 4 include files stdlib.h, ..., float.h
-- Looking for 4 include files stdlib.h, ..., float.h - found
-- Check if the system is big endian
-- Searching 16 bit integer
-- Looking for stddef.h
-- Looking for stddef.h - found
-- Check size of unsigned short
-- Check size of unsigned short - done
-- Using unsigned short
-- Check if the system is big endian - little endian
-- Looking for off_t
-- Looking for off_t - not found
-- Looking for size_t
-- Looking for size_t - not found
-- Check size of off64_t
-- Check size of off64_t - failed
-- Looking for fseeko
-- Looking for fseeko - not found
-- Looking for unistd.h
-- Looking for unistd.h - not found
-- Pre-configuring dataset G4NDL (4.5)
-- Pre-configuring dataset G4EMLOW (7.7)
-- Pre-configuring dataset PhotonEvaporation (5.3)
-- Pre-configuring dataset RadioactiveDecay (5.3)
-- Pre-configuring dataset G4PARTICLEXS (1.1)
-- Pre-configuring dataset G4PII (1.3)
-- Pre-configuring dataset RealSurface (2.1.1)
-- Pre-configuring dataset G4SAIDDATA (2.0))
-- Pre-configuring dataset G4ABLA (3.1)
-- Pre-configuring dataset G4INCL (1.0)
-- Pre-configuring dataset G4ENSDFSTATE (2.2)
  *WARNING*
    Geant4 has been pre-configured to look for datasets
    in the directory:

    /Users/YourUsername/Geant4/geant4_10_05-install/share/Geant4-10.5.0/data

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

    G4NDL (4.5)
    G4EMLOW (7.7)
    PhotonEvaporation (5.3)
    RadioactiveDecay (5.3)
    G4PARTICLEXS (1.1)
    G4PII (1.3)
    RealSurface (2.1.1)
    G4SAIDDATA (2.0))
    G4ABLA (3.1)
    G4INCL (1.0)
    G4ENSDFSTATE (2.2)

    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.5.tar.gz
    https://cern.ch/geant4-data/datasets/G4EMLOW.7.7.tar.gz
    https://cern.ch/geant4-data/datasets/G4PhotonEvaporation.5.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4RadioactiveDecay.5.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4PARTICLEXS.1.1.tar.gz
    https://cern.ch/geant4-data/datasets/G4PII.1.3.tar.gz
    https://cern.ch/geant4-data/datasets/G4RealSurface.2.1.1.tar.gz
    https://cern.ch/geant4-data/datasets/G4SAIDDATA.2.0.tar.gz
    https://cern.ch/geant4-data/datasets/G4ABLA.3.1.tar.gz
    https://cern.ch/geant4-data/datasets/G4ENSDFSTATE.2.2.tar.gz

    and unpack them under the directory:

    /Users/YourUsername/Geant4/geant4_10_05-install/share/Geant4-10.5.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:

-- Configuring done
-- Generating done
-- Build files have been written to: C:/Users/YourUsername/Geant4/geant4_10_04-build

The output will differ slightly 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_10_05-install\share\Geant4-10.5.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 optimized 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 proceedure 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 Getting Started). 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.

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 Getting Started 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 optimized build without debugging symbols. The most useful values are:

      Release : Optimized build, no debugging symbols

      Debug : Debugging symbols, no optimization

      RelWithDebInfo : Optimized 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, 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.

  • GEANT4_BUILD_MULTITHREADED : (DEFAULT : OFF)

    • If set to ON, build Geant4 libraries with support for multithreading. At present, this is only supported on Unix systems.

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

  • 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 XERCESC_XXX and CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating Xerces-C.

  • GEANT4_USE_QT (DEFAULT : OFF)

    • If set to ON, build Qt4/5 User Interface and Visualization drivers.

      Requires: Qt4 or Qt5 and OpenGL libraries and headers. Qt5 will be searched for first. If it is not found Qt4 will be searched for. This behaviour can be adjusted through the advanced option GEANT4_FORCE_QT4.

      See the QT_QMAKE_EXECUTABLE and CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating Qt.

  • 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_RAYTRACER_X11 (DEFAULT : OFF, Unix only)

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

      Requires: X11 libraries and headers.

  • 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_INVENTOR (DEFAULT : OFF)

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

      Requires: Coin3D Open Inventor implementation, SoXt (Unix) or SoWin (Windows) binding, and OpenGL libraries and headers. CMake will use coin-config and soxt-config if present to locate the Coin3D and SoXt implementation respectively, and will honor the COINDIR environment variable.

      See the INVENTOR_XXX and CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating Inventor.

      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_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 MOTIF_XXX and CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating Motif.

  • 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 CLHEP_XXX and 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 EXPAT_XXX and CMAKE_PREFIX_PATH Advanced Options 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 ZLIB_XXX and CMAKE_PREFIX_PATH Advanced Options if CMake has trouble locating ZLIB.

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 relevent 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_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_BUILD_CXXSTD : (DEFAULT : 11)

    • Compile Geant4 against given C++ standard ( 11, 14, or 17). Geant4 is written in C++11, 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. Use of C++17 requires CMake 3.8 or newer.

  • 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)

    • 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 visualize 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_MUONIC_ATOMS_IN_USE : (DEFAULT : OFF)

    • Set to ON only if using Muonic Atom physics.

  • 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_NETWORKDAWN : (DEFAULT : OFF, Unix Only)

    • If set to ON, build network server/client support for DAWN visualization driver. You do not need this to view DAWN files.

  • GEANT4_USE_NETWORKVRML : (DEFAULT : OFF, Unix Only)

    • If set to ON, build network server/client support for VRML visualization driver. You do not need this to view VRML files.

  • 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.

  • GEANT4_USE_WT : (DEFAULT : OFF)

    • If set to ON, build Geant4 Wt web based visualization driver.

      WARNING: this driver is experimental and should be used with caution.

      Requires: Wt libraries and headers, OpenGL libraries and headers, Boost headers and Boost signals library.

  • 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).

  • XERCESC_ROOT_DIR

    • If CMAKE_PREFIX_PATH is not sufficient to locate, or you require a very specific version of, Xerces-C, set this variable to the root directory of the installation (i.e. the directory containing the include and lib subdirectories for Xerces-C++). If this is not sufficient to locate Xerces-C++, see XERCESC_INCLUDE_DIR and XERCESC_LIBRARY.

      Setting this variable will automatically enable a build with support for GDML.

  • XERCESC_INCLUDE_DIR

    • If CMake cannot locate your Xerces-C++ installation, set this to the directory containing the Xerces-C++ headers (e.g. if you have /foobar/xercesc/util/XercesVersion.hpp, then set this to /foobar).

  • XERCESC_LIBRARY

    • If CMake cannot locate your Xerces-C++ installation, set this to the full path to the Xerces-C++ library, e.g. /usr/lib/libxerces-c.so

  • GEANT4_FORCE_QT4 : (DEFAULT : OFF)

    • If set to ON, only search for a Qt4 installation. WARNING: This cannot be set after a Qt5 installation has already been found.

  • QT_QMAKE_EXECUTABLE

    • If your Qt4 installation is in a non-standard location, set this variable to point to the qmake executable of the Qt4 installation you wish to use. If you have a system install on Linux or the binary SDK install on other platforms, Qt4 will in general be found automatically (CMake should also honor the QTDIR environment variable).

      To locate Qt5 installations, the CMAKE_PREFIX_PATH variable should be used to point the installation prefix for the required Qt5.

  • INVENTOR_INCLUDE_DIR

    • If CMake cannot locate your OpenInventor installation, set this to the directory containing the Inventor headers (e.g. if you have /foobar/Inventor/So.h, then set this to /foobar).

  • INVENTOR_LIBRARY

    • If CMake cannot locate your Inventor installation, set this to the full path to the Inventor library, e.g. /usr/lib/libCoin.so

  • INVENTOR_SOWIN_LIBRARY (Windows only)

    • If CMake cannot locate your Inventor installation, set this to the full path to the Inventor SoWin binding library, e.g. C:\Program Files\Coin\sowin.dll.

  • INVENTOR_SOXT_INCLUDE_DIR (Unix only)

    • If CMake cannot locate your Inventor installation, set this to the directory containing the Inventor SoXt binding headers (e.g. if you have /foobar/Inventor/SoXt/SoXt.h, then set this to /foobar).

  • INVENTOR_SOXT_LIBRARY (Unix only)

    • If CMake cannot locate your Inventor installation, set this to the full path to the Inventor SoXt binding library, e.g. /usr/lib/libSoXt.so.

  • MOTIF_INCLUDE_DIR

    • If CMake cannot locate your Motif installation, set this to the directory containing the Motif headers (e.g. if you have /foobar/Xm/Xm.h, then set this to /foobar).

  • MOTIF_LIBRARIES

    • If CMake cannot locate your Motif installation, set this to the full path to the Motif library, e.g. /usr/lib/libXm.so

  • GEANT4_USE_SYSTEM_CLHEP_GRANULAR (DEFAULT : OFF)

    • If set to ON, configure Geant4 to search for and use the Evaluator, Geometry, Random and Vector component libraries of CLHEP rather than the single CLHEP library.

      WARNING: This option should only be used if your project is locked into using the CLHEP granular libraries by other requirements. Use of the single CLHEP library is no different and simplifies the configuration and use of Geant4.

  • CLHEP_ROOT_DIR

    • If you wish Geant4 to use a specific installation of CLHEP, set this variable to point to the root install directory of the CLHEP installation you wish to use. This directory should contain the include and lib subdirectories containing the CLHEP headers and library respectively. If this is not sufficient to locate CLHEP, see the Advanced CLHEP_INCLUDE_DIR and CLHEP_LIBRARY options.

      Setting this variable will automatically enable a build using the located system install of CLHEP.

  • CLHEP_INCLUDE_DIR

    • If CMake cannot locate your external CLHEP installation, set this to the directory containing the CLHEP headers (e.g. if you have /foobar/CLHEP/Vector/defs.h, then set this to /foobar).

  • CLHEP_LIBRARY

    • If CMake cannot locate your CLHEP installation, set this to the full path to the CLHEP library, e.g. /usr/lib/libCLHEP.so

  • EXPAT_INCLUDE_DIR

    • If CMake cannot locate your external EXPAT installation, set this to the directory containing the EXPAT headers (e.g. if you have /foobar/expat.h, then set this to /foobar).

  • EXPAT_LIBRARY

    • If CMake cannot locate your external EXPAT installation, set this to the full path to the EXPAT library, e.g. /usr/lib/libexpat.so

  • ZLIB_INCLUDE_DIR

    • If CMake cannot locate your external zlib installation, set this to the directory containing the zlib headers (e.g. if you have /foobar/zlib.h, then set this to /foobar).

  • ZLIB_LIBRARY

    • If CMake cannot locate your zlib installation, set this to the full path to the zlib library, e.g. /usr/lib/libz.so

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 unrecognized 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 -DG4FPE_DEBUG
    • 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 -DG4FPE_DEBUG
    • 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 C++11 standard. This can be changed if the compiler version supports it by setting the GEANT4_BUILD_CXXSTD 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:

  • -DG4MULTITHREADED -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.