| Geant4 User's Guide For Application Developers Appendix

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

## 10.5.1 The GNUmake system in Geant4

As described in section 2.1 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 "`gmake`" command from there ("`gmake 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:

- `gmake`
  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`.
- `gmake global`
  starts the compilation process to build a single compound kernel library per category. If issued after "gmake", 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).
- `gmake bin` or `gmake` (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.

## 10.5.2 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 should be installed. 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 store 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`.

  $G4EXEC_BUILD
  Flag specifying if to use a secondary template repository or not for handling template instantiations at the time of building a user application/example. For internal category tests in Geant4, this variable is already in the related GNUmakefile. It's however not needed for examples and tests in `$G4INSTALL/examples`, where class names are already mangled and different each other. It applies only on those compilers which make use of template repositories (see Appendix A.2 of this Guide). The secondary template repository is set to `$G4TREP/exec`.

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

  $G4NO_OPTIMISE
  Specifies to compile the code (libraries or examples) without compiler optimisation.

  $G4NO_STD_EXCEPTIONS (*)
  To avoid throwing of exceptions in Geant4.

  $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, G4UI_BUILD_XAW_SESSION
  Specifies to include in kernel library the XM or XAW Motif-based user interfaces.

  G4UI_USE_XM, G4UI_USE_XAW
  Specifies to use the XM or XAW interfaces in the application to be built.

  G4UI_USE_QT
  Specifies to use the Qt 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_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_QT_DRIVER
  Specifies to build kernel library for visualization including the Qt driver.

  $G4VIS_USE_QT
  Specifies to use Qt graphics 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_lists` module

  $G4LIB_BUILD_LISTS
  Specifies to build or not the `physics_lists` module. By default, the variable is set and the module is built. Set it to `NO` to skip the compilation of the physics lists.

- `zlib` and `g3tog4` modules

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

  $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

  $NeutronHPCrossSections
  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.

## 10.5.3 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.

### 10.5.3.1 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 table 10.5.1.

     # --------------------------------------------------------------------
     # 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)
Table 10.5.1 An example of a customised GNUmakefile for an application or example using an external module not bound to Geant4.

### 10.5.3.2 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 Table 10.5.2.

    # -----------------------------------------------------------------
    # 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)
Table 10.5.2 An example of a customised GNUmakefile for an application or example using external modules bound to Geant4.

About the authors