Makefiles and Environment Variables
This section describes how the GNUmake infrastructure is
implemented in Geant4 and provides a quick reference guide for the
user/installer about the most important environment variables
defined.
The GNUmake system in Geant4
As described in of the
Installation Guide, the GNUmake process in
Geant4 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 map libname.map of each library to establish
the linking order automatically at the bin 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 or make (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.
We recommend that those environment variables listed here and
marked with (*) NOT be overriden 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.
$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.
$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 the gprof 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.
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.
$G4VIS_NONE
If specified, no visualization drivers will be built or used.
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 precison 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_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 implicitely 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 implicitely 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.
$G4LEDATA
Path to external data set for low energy electromagnetic
processes.
$G4LEVELGAMMADATA
Path to the data set for Photon Evaporation.
$G4RADIOACTIVEDATA
Path to the data set for Radiative Decay processes.
$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.
$G4REALSURFACEDATA
Path to the Look-Up-Tables for the LUT model of optical photon
boundary reflection.
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 .
An example of a customised GNUmakefile for an application or
example using an external module not bound to Geant4.
# --------------------------------------------------------------------
# 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 .
An example of a customised GNUmakefile for an
application or example using external modules bound to Geant4.
# -----------------------------------------------------------------
# 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)