Both Section 2.1 and Section 2.2 give the minimal proceedure to build and install Geant4. Many additional options can be passed to CMake to adjust the way Geant4 is built and installed and to enable optional components.
On the command line, 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.9.6
would configure the build of Geant4 for installation under
/opt/geant4
and compilation of support for GDML.
In the CMake GUI, the options are listed as textbox entries, and values may be set directly by clicking on the entry for the option and entering the requested information (for example, if a path is required, the GUI will pop up a file browser).
On Unix, CMake also provides a curses based interface,
ccmake
, which can be used to browse and set
options in the terminal. Please see the CMake documentation for more
information on this command.
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). The curses based ccmake
command
is very useful in this case for browsing the current configuration
and for updating it if required.
In the CMake GUI, you should set the
Where is the source code: path to
that of your source directory, and the
Where to build the binaries: path to that of
the build directory you wish to reconfigure.
You will then need to rebuild and reinstall to pick up the changes.
You can also deactivate a previously selected
option to remove a component from the build. For example, we could do
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/geant4 -DGEANT4_USE_GDML=OFF /path/to/geant4.9.6
to explicitly remove support for GDML from a build (In the CMake
GUI, we would simply uncheck the tick box for
GEANT4_USE_GDML
). Note however that 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 may
wish to build the uninstall
target before
reconfiguring.
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 and install. Some options enable components of Geant4 which require external software (as listed in Section 1.2). 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.
We list standard options here in logical order. If you use CMake's curses or GUI interfaces, they will be listed alphabetically.
CMAKE_INSTALL_PREFIX
Sets the installation prefix for Geant4. Equivalent to
--prefix
in Autotools. Its 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)
Controls the type of build, at present only the additional
flags passed to the compiler. It defaults to
Release
which gives an optimized build
with no debugging symbols. The most useful values are:
Release
: Optimized build, no
debugging symbols
Debug
: Debugging symbols, no
optimization
RelWithDebInfo
: Optimized build
with debugging symbols
Note that if you use a build system which supports multiconfiguration builds (e.g. Xcode, Visual Studio), this variable has no effect as all build types are available inside the CMake generated project.
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_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_USE_GDML : (DEFAULT : OFF | ON if XERCESC_ROOT_DIR is set)
If set to ON
, build the
G4persistency
library with support for
GDML.
REQUIRES :
Xerces-C++ libraries and
headers, see the XERCESC_ROOT_DIR
option.
XERCESC_ROOT_DIR
If your Xerces-C++ installation is in a non-standard
location, 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 the Advanced
XERCESC_INCLUDE_DIR
and
XERCESC_LIBRARY
options.
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_QT (DEFAULT : OFF)
If set to ON
, build Qt4 User Interface
and Visualization drivers.
REQUIRES :
Qt4 and OpenGL libraries
and headers. See also the
QT_QMAKE_EXECUTABLE
option if CMake
has trouble locating your Qt4 installation.
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).
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. In most cases, these should be found
automatically, but if not, see
the Advanced MOTIF_INCLUDE_DIR
and
MOTIF_LIBRARIES
options.
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_OPENGL_WIN32 (DEFAULT : OFF, Windows Only)
If set to ON
, build the Win32 OpenGL
visualization driver.
REQUIRES :
OpenGL libraries and
headers. If you are using Visual Studio, then this should
supply the needed headers and libraries.
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.
In case of issues with locating the Inventor
implementation, see the Advanced
INVENTOR_INCLUDE_DIR
,
INVENTOR_LIBRARY
,
INVENTOR_SOXT_INCLUDE_DIR
,
INVENTOR_SOXT_LIBRARY
and
INVENTOR_SOWIN_LIBRARY
options.
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_RAYTRACER_X11 (DEFAULT : OFF, Unix only)
If set to ON
, build RayTracer
visualization driver with X11 support.
REQUIRES :
X11 Headers and Libraries.
GEANT4_USE_SYSTEM_CLHEP (DEFAULT : OFF | ON if CLHEP_ROOT_DIR set)
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 experiment's software uses CLHEP in other tools
and requires consistent use of the same CLHEP across
the software). If the CLHEP_ROOT_DIR
option is not set, CLHEP will be searched for under
standard system paths.
REQUIRES :
CLHEP libraries and headers.
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.
GEANT4_USE_SYSTEM_EXPAT (DEFAULT : ON)
If set to ON
, build Geant4 with an
external install of Expat. In this case, the Expat
headers and library will be searched for under the
standard system paths. If these are not sufficient
to locate the required Expat installation, see the
Advanced EXPAT_INCLUDE_DIR
and
EXPAT_LIBRARY
options/
REQUIRES :
Expat library and headers.
Most builds should never need to touch the advanced options, but should you need more control or CMake has problems locating needed software packages, they can be very helpful. We only list the options and variables most relevent for Geant4. For help on core CMake variables and options, you should consult the Reference Documentation section of the main CMake documentation , and specifically the sections on Variables.
Advanced options are not displayed by default in CMake's curses and
GUI interfaces, but can be displayed by pressing t
in ccmake, or clicking the 'advanced' check box in the CMake GUI.
Note that displaying advanced options will also display a large
number of options and variables used by CMake for build
configuration and to cache the locations of Third Party packages.
On the command line, advanced
options and variables can be set like the standard ones listed
earlier using -D
arguments.
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_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.
REQUIRES :
a working network
connection.
GEANT4_INSTALL_EXAMPLES : (DEFAULT : OFF)
If set to ON
, install Geant4 example
application source code under
CMAKE_INSTALL_DATAROOTDIR
.
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 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.
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
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
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
.
CLHEP_INCLUDE_DIR (If GEANT4_USE_SYSTEM_CLHEP
selected)
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 GEANT4_USE_SYSTEM_CLHEP
selected)
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 GEANT4_USE_SYSTEM_EXPAT
selected)
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 GEANT4_USE_SYSTEM_EXPAT
selected)
If CMake cannot locate your EXPAT installation, set this to
the full path to the EXPAT library, e.g.
/usr/lib/libexpat.so
GEANT4_BUILD_CXXSTD : (DEFAULT : c++98, Unix Only)
Compile Geant4 against given C++ standard (
c++98
, including addenda,
c++0x
, or
c++11
. Geant4 is written in
c++98
, and you should use this
option if your application requires support for the
newer standards. If you set the variable to a standard
the compiler does not support, and error will be
emitted.
REQUIRES :
GNU, Clang or Intel C++
compilers.
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_GRANULAR_LIBRARIES : (DEFAULT : OFF) (DEPRECATED)
If set to ON
, build Geant4 libraries in
granular mode. WARNING: this option is
deprecated, intended for Geant4 developers only and does
not provide a fully usable Geant4 install.
No support is, or will be, provided for user
applications built with granular libraries.
GEANT4_BUILD_EXAMPLES : (DEFAULT : OFF)
If set to ON
, build all Geant4 example
applications using current Geant4 build.
WARNING: this option is for Geant4
system testing only and is not intended for use by users
studying and working on the examples.
No support is, or will be, provided
for user builds of the examples using this
option.
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.
CMake will, by default, select the first C and C++ compilers it finds in your path. Geant4's CMake scripts configure a default set of flags based on the compiler identity, as follows
CMAKE_CXX_FLAGS : -W -Wall -pedantic
-Wno-non-virtual-dtor
-Wno-long-long
-Wwrite-strings
-Wpointer-arith
-Woverloaded-virtual
-pipe
CMAKE_CXX_FLAGS_RELEASE : -O2 -DNDEBUG
CMAKE_CXX_FLAGS_DEBUG : -g
CMAKE_CXX_FLAGS_RELWITHDEBINFO : -O2 -g
CMAKE_CXX_FLAGS : -W -Wall -pedantic
-Wno-non-virtual-dtor
-Wno-long-long
-Wwrite-strings
-Wpointer-arith
-Woverloaded-virtual
-pipe
-Qunused-arguments
CMAKE_CXX_FLAGS_RELEASE : -O2 -DNDEBUG
CMAKE_CXX_FLAGS_DEBUG : -g
CMAKE_CXX_FLAGS_RELWITHDEBINFO : -O2 -g
CMAKE_CXX_FLAGS : -GR -EHsc -Zm200 -nologo
-D_CONSOLE
-D_WIN32
-DWIN32
-DOS
-DXPNET
-D_CRT_SECURE_NO_DEPRECATE
CMAKE_CXX_FLAGS_RELEASE : -MD -O2 -DNDEBUG
CMAKE_CXX_FLAGS_DEBUG : -MDd -Od -Zi
CMAKE_CXX_FLAGS_RELWITHDEBINFO : -MD -O2 -Zi
CMAKE_CXX_FLAGS : -w1 -Wno-non-virtual-dtor
-Wpointer-arith
-Wwrite-strings
-fp-model precise
CMAKE_CXX_FLAGS_RELEASE : -O2 -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++98
standard.
This can be changed if the compiler version supports it by
setting the GEANT4_BUILD_CXXSTD
to the required
standard, as described in Section 2.3.2.
If you are using an unsupported or unrecognized (by Geant4)
compiler, CMake will default to a standard and very simple set
of flags for that compiler.
We strongly recommend that you use the default compiler and flags,
but both can be modified if your use case requires it. 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 specify a full path should the compilers not be in
the PATH
.
You can also specify the C and C++ compilers 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 do perform this step, it can only be done by rerunning
CMake and passing the new compiler via the
CMAKE_<LANG>_COMPILER
argument(s), as the CC
and CXX
variables have no effect on subsequent runs of CMake in a given
build directory. You may also need to remove the
CMakeCache.txt
file from the build directory
before running CMake again.
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.
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.
CMake is also aware of the CFLAGS
and
CXXFLAGS
variables, so you may set these on the
command line or as environment variables. However, note that this
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.
As Geant4, and CMake in general, has many configurable options,
remembering and typing out the CMake command line can be tedious and
potentially error prone once you start to use a significant number
of options. To ease this task and provide reproducible builds,
you can write options as CMake set()
commands
into a so-called initial cache script. For example, to select Clang
as the compiler and enable Qt support, we could write the
following
set(CMAKE_C_COMPILER clang CACHE STRING "") set(CMAKE_CXX_COMPILER clang++ CACHE STRING "") set(GEANT4_USE_QT ON CACHE BOOL "")
into a file, say, mysettings.cmake
. We could then
pass this file to CMake to configure the Geant4 build with these
settings:
$ cmake -C /home/me/mysettings.cmake /path/to/geant4.9.6
Any settings in the supplied script will take priority over
the defaults, so this can be a useful way to manage different
builds in a reproducible way. Note that the set()
commands must use the CACHE
argument to ensure
they are loaded into the CMake cache.