Using Geant4Make to build Applications¶
Please note that this system is deprecated since Geant4 v10.0, meaning that it is no longer
supported and may be removed in future releases without warning. You should migrate
your application to be built using CMake via the Geant4Config.cmake
script, or any other
build tool of your choice, using the geant4-config
program to query
the relevant compiler/linker flags.
Geant4Make is the Geant4 GNU Make toolchain formerly used to build the
toolkit and applications. It is installed on UNIX systems (except for
Cygwin) for backwards compatibility with the Geant4 Examples and your
existing applications which use a GNUmakefile and the Geant4Make
binmake.gmk
file. The files for Geant4Make are installed under:
+- CMAKE_INSTALL_PREFIX/
+- share/
+- geant4make/
+- geant4make.sh
+- geant4make.csh
+- config/
+- binmake.gmk
+- ...
The system is designed to form a self-contained GNUMake system which is configured primarily by environment variables (though you may manually replace these with Make variables if you prefer). Building a Geant4 application using Geant4Make therefore involves configuring your environment followed by writing a GNUmakefile using the Geant4Make variables and GNUMake modules.
To configure your environment, simply source the relevant configuration
script CMAKE_INSTALL_PREFIX/share/Geant4-G4VERSION/geant4make/geant4make.(c)sh
for your shell. Whilst both scripts can be sourced
interactively, if you are using the C shell and need to source the
script inside another script, you must use the commands:
$ cd CMAKE_INSTALL_PREFIX/share/Geant4-G4VERSION/geant4make
$ source geant4make.csh
You should replace CMAKE_INSTALL_PREFIX
with the
actual prefix you installed Geant4 under. Both of these commands work
around a limitation in the C shell which prevents the script locating
itself.
Please also note that due to limitations of Geant4Make, you should not
rely on the environment variables it sets for paths into Geant4 itself.
In particular, note that the G4INSTALL
variable is not equivalent
to CMAKE_INSTALL_PREFIX
.
Once you have configured your environment, you can start building your
application. Geant4Make enforces a specific organization and naming of
your sources in order to simplify the build. We’ll use Basic Example B1,
which you may find in the Geant4 source directory under
examples/basic/B1
, as the canonical example again. Here, the sources
are arranged as follows:
+- B1/
+- GNUmakefile
+- exampleB1.cc
+- include/
... headers.hh ...
+- src/
... sources.cc ...
As before, exampleB1.cc
contains main()
for the application,
with include/
and src/
containing the implementation class
headers and sources respectively. You must
organise your sources in
this structure with these filename extensions to use Geant4Make as it
will expect this structure when it tries to build the application.
With this structure in place, the GNUmakefile for exampleB1 is very simple:
name := exampleB1
G4TARGET := $(name)
G4EXLIB := true
.PHONY: all
all: lib bin
include $(G4INSTALL)/config/binmake.gmk
Here, name
is set to the application to be built, and it must match
the name of the file containing the main()
program without the
.cc
extension. The rest of the variables are structural to prepare
the build, and finally the core Geant4Make module is included. The
G4INSTALL
variable is set in the environment by the geant4make
script to point to the root of the Geant4Make directory structure.
With this structure in place, simply run make
to build your
application:
$ make
If you need extra detail on the build, append CPPVERBOSE=1
to
the make command to see a detailed log of the command executed.
The application executable will be output to
$(G4WORKDIR)/bin/$(G4SYSTEM)/exampleB1
, where $(G4SYSTEM)
is the
system and compiler combination you are running on, e.g. Linux-g++. By
default, $(G4WORKDIR)
is set by the geant4make
scripts to
$(HOME)/geant4_workdir
, and also prepends this directory to your
PATH
. You can therefore run the application directly once it’s
built:
$ exampleB1
If you prefer to keep your application builds separate, then you can set
G4WORKDIR
in the GNUmakefile
before including binmake.gmk
.
In this case you would have to run the executable by supplying the full
path.
Geant4Make System¶
The Geant4Make system is mainly controlled by the following
GNUmake script files (*.gmk
scripts are placed in
$G4INSTALL/config
):
architecture.gmk
: defining all the architecture specific settings and paths. System settings are stored in$G4INSTALL/config/sys
in separate files.common.gmk
: defining all general GNUmake rules for building objects and libraries.globlib.gmk
: defining all general GNUmake rules for building compound libraries.binmake.gmk
: defining the general GNUmake rules for building executables.GNUmake
scripts: placed inside each directory in the G4 distribution and defining directives specific to build a library (or a set of sub-libraries) or and executable.
To build a single library (or a set of sub-libraries) or an executable,
you must explicitly change your current directory to the one you’re
interested in and invoke the “make
” command from there
(“make global
” for building a compound library). Here is a list of
the basic commands or GNUmake “targets” one can invoke to build
libraries and/or executables:
make
starts the compilation process for building a kernel library or a library associated with an example. Kernel libraries are built with maximum granularity, i.e. if a category is a compound, this command will build all the related sub-libraries, not the compound one. The top level
GNUmakefile
in$G4INSTALL/source
will also build in this case a dependency maplibname.map
of each library to establish the linking order automatically at thebin
step. The map will be placed in$G4LIB/$G4SYSTEM
.make global
starts the compilation process to build a single compound kernel library per category. If issued after “make”, both ‘granular’ and ‘compound’ libraries will be available (NOTE: this will consistently increase the disk space required. Compound libraries will then be selected by default at link time, unless G4LIB_USE_GRANULAR is specified).
make bin
ormake
(only for examples/)starts the compilation process to build an executable. This command will build implicitly the library associated with the example and link the final application. It assumes all kernel libraries are already generated and placed in the correct
$G4INSTALL
path defined for them.The linking order is controlled automatically in case libraries have been built with maximum granularity, and the link list is generated on the fly.
make dll
On Windows systems this will start the compilation process to build single compound kernel library per category and generate Dynamic Link Libraries (DLLs). Once the libraries are generated, the process will imply also the deletion of all temporary files generated during the compilation.
lib/ bin/
and tmp/
directories¶
The $G4INSTALL
environment variable specifies where the installation
of the Geant4 toolkit should take place, therefore kernel libraries will
be placed in $G4INSTALL/lib
. The $G4WORKDIR
environment variable
is set by the user and specifies the path to the user working directory;
temporary files (object-files and data products of the installation
process of Geant4) will be placed in $G4WORKDIR/tmp
, according to
the system architecture used. Binaries will be placed in
$G4WORKDIR/bin
, according to the system architecture used. The path
to $G4WORKDIR/bin/$G4SYSTEM
should be added to $PATH
in the user
environment.
Environment variables¶
Here is a list of the most important environment variables defined
within the Geant4 GNUmake
infrastructure, with a short explanation
of their use.
Warning
We recommend that those environment variables listed here and marked with (*) NOT be overridden or set (explicitly or by accident). They are already set and used internally in the default setup !
System configuration¶
- $CLHEP_BASE_DIR
Specifies the path where the CLHEP package is installed in your system.
- $USOLIDS_BASE_DIR
Specifies the path where the USolids package is installed in your system.
- $G4SYSTEM
Defines the architecture and compiler currently used.
Note
This variable is set automatically if the Configure
script is adopted for the installation. This will result in the
proper settings also for configuring the environment with the
generated shell scripts env.[c]sh
.
Installation paths¶
- $G4INSTALL
Defines the path where the Geant4 toolkit is located. It should be set by the system installer. By default, it sets to
$HOME/geant4
, assuming the Geant4 distribution is placed in$HOME
.- $G4BASE (*)
Defines the path to the source code. Internally used to define
$CPPFLAGS
and$LDFLAGS
for -I and -L directives. It has to be set to$G4INSTALL/src
.- $G4WORKDIR
Defines the path for the user’s workdir for Geant4. It is set by default to
$HOME/geant4
, assuming the user’s working directory for Geant4 is placed in$HOME
.- $G4INCLUDE
Defines the path where source header files may be mirrored at installation by issuing
gmake includes
(default is set to$G4INSTALL/include
)- $G4BIN, $G4BINDIR (*)
Used by the system to specify the place where to store executables. By default they’re set to
$G4WORKDIR/bin
and$G4BIN/$G4SYSTEM
respectively. The path to$G4WORKDIR/bin/$G4SYSTEM
should be added to$PATH
in the user environment.$G4BIN
can be overridden.- $G4TMP, $G4TMPDIR (*)
Used by the system to specify the place where to store temporary files products of the compilation/build of a user application or test. By default they’re set to
$G4WORKDIR/tmp
and$G4TMP/$G4SYSTEM
respectively.$G4TMP
can be overridden.- $G4LIB, $G4LIBDIR (*)
Used by the system to specify the place where to install libraries. By default they’re set to
$G4INSTALL/lib
and$G4LIB/$G4SYSTEM
respectively.$G4LIB
can be overridden.
Build specific¶
- $G4TARGET
Specifies the target (name of the source file defining the main()) of the application/example to be built. This variable is set automatically for the examples and tests placed in
$G4INSTALL/examples
.- $G4DEBUG
Specifies to compile the code (libraries or examples) including symbolic information in the object code for debugging. The size of the generated object code can increase considerably. By default, code is compiled in optimised mode (
$G4OPTIMISE
set).- $G4OPTDEBUG
Only available for the
g++
compiler, specifies to compile the code (libraries or examples) in optimised mode, but including symbolic information in the object code for debugging.- $G4USE_STD11
Specifies to compile the code (libraries or examples) with C++11 Standard enabled on compilers supporting the C++11 Standard.
- $G4NO_OPTIMISE
Specifies to compile the code (libraries or examples) without compiler optimisation.
- $G4PROFILE
On Linux systems with the
g++
compiler, it allows to build libraries with profiling setup for monitoring with thegprof
tool.- $G4_NO_VERBOSE
Geant4 code is compiled by default in high verbosity mode (
$G4VERBOSE
flag set). For better performance, verbosity code can be left out by defining$G4_NO_VERBOSE
.- $G4LIB_BUILD_SHARED
Flag specifying if to build kernel libraries as shared libraries (libraries will be then used by default). If not set, static archive libraries are built by default.
- $G4LIB_BUILD_STATIC
Flag specifying if to build kernel libraries as static archive libraries in addition to shared libraries (in case
$G4LIB_BUILD_SHARED
is set as well).- $G4LIB_BUILD_DLL (*)
Internal flag for specifying to build DLL kernel libraries for Windows systems. The flag is automatically set when requested to build DLLs.
- $G4LIB_USE_DLL
For Windows systems only. Flag to specify to build an application using the installed DLL kernel libraries for Windows systems. It is required to have this flag set in the environment in order to successfully build an application if the DLL libraries have been installed.
- $G4LIB_USE_GRANULAR
To force usage of “granular” libraries against “compound” libraries at link time in case both have been installed. The Geant4 building system chooses “compound” libraries by default, if installed.
UI specific¶
The most relevant flags for User Interface drivers are just listed here. A more detailed description is given also in section 2. of this User’s Guide.
- G4UI_USE_TERMINAL
Specifies to use dumb terminal interface in the application to be built (default).
- G4UI_USE_TCSH
Specifies to use the tcsh-shell like interface in the application to be built.
- G4UI_BUILD_XM_SESSION
Specifies to include in kernel library the
XM
Motif-based user interfaces.- G4UI_USE_XM
Specifies to use the
XM
interfaces in the application to be built.- G4UI_BUILD_WIN32_SESSION
Specifies to include in kernel library the WIN32 terminal interface for Windows systems.
- G4UI_USE_WIN32
Specifies to use the WIN32 interfaces in the application to be built on Windows systems.
- G4UI_BUILD_QT_SESSION
Specifies to include in kernel library the Qt terminal interface.
$QTHOME
should specify the path where Qt libraries and headers are installed- G4UI_USE_QT
Specifies to use the Qt interfaces in the application to be built.
- G4UI_NONE
If set, no UI sessions nor any UI libraries are built. This can be useful when running a pure batch job or in a user framework having its own UI system.
Visualization specific¶
The most relevant flags for visualization graphics drivers are just listed here. A description of these variables is given also in section 2. of this User’s Guide.
- $G4VIS_BUILD_OPENGLX_DRIVER
Specifies to build kernel library for visualization including the OpenGL driver with X11 extension. It requires
$OGLHOME
set (path to OpenGL installation).- $G4VIS_USE_OPENGLX
Specifies to use OpenGL graphics with X11 extension in the application to be built.
- $G4VIS_BUILD_OPENGLXM_DRIVER
Specifies to build kernel library for visualization including the OpenGL driver with XM extension. It requires
$OGLHOME
set (path to OpenGL installation).- $G4VIS_USE_OPENGLXM
Specifies to use OpenGL graphics with XM extension in the application to be built.
- G4VIS_BUILD_OPENGLQT_DRIVER
Specifies to build kernel library for visualization including the OpenGL driver with Qt extension. It requires
$QTHOME
set to specify the path where Qt libraries and headers are installed.- G4VIS_USE_OPENGLQT
Specifies to use OpenGL graphics with Qt extension in the application to be built.
- $G4VIS_BUILD_OI_DRIVER
Specifies to build kernel library for visualization including the OpenInventor driver. It requires
$OIHOME
set (paths to the OpenInventor installation).- $G4VIS_USE_OI
Specifies to use OpenInventor graphics in the application to be built.
- $G4VIS_BUILD_OIX_DRIVER
Specifies to build the driver for the free X11 version of OpenInventor.
- $G4VIS_USE_OIX
Specifies to use the free X11 version of OpenInventor.
- $G4VIS_BUILD_RAYTRACERX_DRIVER
Specifies to build kernel library for visualization including the Ray-Tracer driver with X11 extension. It requires
X11
installed in the system.- $G4VIS_USE_RAYTRACERX
Specifies to use the X11 version of the Ray-Tracer driver.
- $G4VIS_BUILD_OIWIN32_DRIVER
Specifies to build the driver for the free X11 version of OpenInventor on Windows systems.
- $G4VIS_USE_OIWIN32
Specifies to use the free X11 version of OpenInventor on Windows systems.
- $G4VIS_BUILD_DAWN_DRIVER
Specifies to build kernel library for visualization including the driver for DAWN.
- $G4VIS_USE_DAWN
Specifies to use DAWN as a possible graphics renderer in the application to be built.
- $G4DAWN_HOST_NAME
To specify the hostname for use with the DAWN-network driver.
Hadronic physics specific¶
- $G4NEUTRONHP_USE_ONLY_PHOTONEVAPORATION
When using high precision neutron code, user may choose to force the use of Photon Evaporation model instead of using the neutron capture final state data.
- $G4NEUTRONHP_SKIP_MISSING_ISOTOPES
User can force high precision neutron code to use only exact isotope data files instead of allowing nearby isotope files to be used. If the exact file is not available, the cross section will be set to zero and a warning message will be printed.
- $G4NEUTRONHP_NEGLECT_DOPPLER
Sets neglecting Doppler broadening mode for boosting performance.
GDML, zlib and g3tog4 modules¶
- $G4LIB_BUILD_GDML
If set, triggers compilation of a plugin module
gdml
for allowing import/export of detector description setups (geometrical volumes, solids, materials, etc.). By default, the flag is not set; if set, the path to the installation of XercesC package must be specified through the variable$XERCESCROOT
.- $G4LIB_USE_GDML
Specifies to use the
gdml
module. The flag is automatically set if$G4LIB_BUILD_GDML
is set in the environment.- $G4LIB_USE_USOLIDS
Specifies to adopt the
USolids
primitives in place of the original Geant4 solids.- $G4LIB_BUILD_ZLIB
If set, triggers compilation of a specific
zlib
module for the compression of output files (mainly in use currently for the HepRep graphics driver). By default, the flag is not set and the built-in system library for compression is adopted instead. Setting this flag will also implicitly set the flag below. On Windows systems, if OpenGL or OpenInventor visualization drivers are built, this module is automatically built.- $G4LIB_USE_ZLIB
Specifies to use the
zlib
module, either system built-in or Geant4 specific.- $G4LIB_BUILD_G3TOG4
If set, triggers compilation of the
g3tog4
module for conversions of simple legacy geometries descriptions to Geant4. By default, the flag is not set and the module’s library is not built. Setting this flag will also implicitly set the flag below.- $G4LIB_USE_G3TOG4
Specifies to use the
g3tog4
module, assuming the related library has been already installed.
Analysis specific¶
- $G4ANALYSIS_USE
Specifies to activate the appropriate environment for analysis, if an application includes code for histogramming based on
AIDA
. Additional setup variables are required ($G4ANALYSIS_AIDA_CONFIG_CFLAGS
,$G4ANALYSIS_AIDA_CONFIG_LIBS
) to define config options for AIDA (“aida-config --cflags
” and “aida-config --libs
”). See installation instructions of the specific analysis tools for details.
Directory paths to Physics Data¶
- $G4NEUTRONHPDATA
Path to external data set for Neutron Scattering processes.
- $G4NEUTRONXSDATA
Path to external data set for evaluated neutron cross-sections.
- $G4LEDATA
Path to external data set for low energy electromagnetic processes.
- $G4PIIDATA
Path to external data set for shell ionisation cross-sections.
- $G4LEVELGAMMADATA
Path to the data set for Photon Evaporation.
- $G4RADIOACTIVEDATA
Path to the data set for Radiative Decay processes.
- $G4ENSDFSTATE1.0
Path to the data set for NuclideTable
- $G4ABLADATA
Path to nuclear shell effects data set for INCL/ABLA hadronic model.
- $G4REALSURFACEDATA
Path to the data set for measured optical surface reflectance for precise optical physics.
Linking External Libraries with Geant4¶
The Geant4 GNUmake infrastructure allows to extend the link list of libraries with external (or user defined) packages which may be required for some user’s applications to generate the final executable.
Adding external libraries which do not use Geant4¶
In the GNUmakefile
of your application, before including
binmake.gmk
, specify the extra library in EXTRALIBS
either using
the -L...-l...
syntax or by specifying the full pathname, e.g.:
EXTRALIBS := -L<your-path>/lib -l<myExtraLib>
or
EXTRALIBS := <your-path>/lib/lib<myExtraLib>.a
You may also specify EXTRA_LINK_DEPENDENCIES
, which is added to the
dependency of the target executable, and you may also specify a rule for
making it, e.g.:
EXTRA_LINK_DEPENDENCIES := <your-path>/lib/lib<myExtraLib>.a
<your-path>/lib/lib<myExtraLib>.a:
cd <your-path>/lib; $(MAKE)
Note that you almost certainly need to augment CPPFLAGS
for the
header files of the external library, e.g.:
CPPFLAGS+=-I<your-path>/include
See Listing 101.
# --------------------------------------------------------------------
# GNUmakefile for the application "sim" depending on module "Xplotter"
# --------------------------------------------------------------------
name := sim
G4TARGET := $(name)
G4EXLIB := true
CPPFLAGS += -I$(HOME)/Xplotter/include
EXTRALIBS += -L$(HOME)/Xplotter/lib -lXplotter
EXTRA_LINK_DEPENDENCIES := $(HOME)/Xplotter/lib/libXplotter.a
.PHONY: all
all: lib bin
include $(G4INSTALL)/config/binmake.gmk
$(HOME)/Xplotter/lib/libXplotter.a:
cd $(HOME)/Xplotter; $(MAKE)
Adding external libraries which use Geant4¶
In addition to the above, specify, in EXTRALIBSSOURCEDIRS
, a list of
directories containing source files in its src/
subdirectory. Thus,
your GNUmakefile
might contain:
EXTRALIBS += $(G4WORKDIR)/tmp/$(G4SYSTEM)/<myApp>/lib<myApp>.a \
-L<your-path>/lib -l<myExtraLib>
EXTRALIBSSOURCEDIRS += <your-path>/<myApp> <your-path>/<MyExtraModule>
EXTRA_LINK_DEPENDENCIES := $(G4WORKDIR)/tmp/$(G4SYSTEM)/<myApp>/lib<myApp>.a
MYSOURCES := $(wildcard <your-path>/<myApp>/src/*cc)
$(G4WORKDIR)/tmp/$(G4SYSTEM)/<myApp>/lib<myApp>.a: $(MYSOURCES)
cd <your-path>/<myApp>; $(MAKE)
See the Listing 102.
# -----------------------------------------------------------------
# GNUmakefile for the application "phys" depending on module "reco"
# -----------------------------------------------------------------
name := phys
G4TARGET := $(name)
G4EXLIB := true
EXTRALIBS += $(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a \
-L$(HOME)/reco/lib -lreco
EXTRALIBSSOURCEDIRS += $(HOME)/phys $(HOME)/reco
EXTRA_LINK_DEPENDENCIES := $(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a
.PHONY: all
all: lib bin
include $(G4INSTALL)/config/binmake.gmk
MYSOURCES := $(wildcard $(HOME)/phys/src/*cc)
$(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a: $(MYSOURCES)
cd $(HOME)/phys; $(MAKE)