Unix Machines

Installation Guide

Before installing Geant4, the required software listed in section 1.2 (and 1.3 in the case of graphics drivers) of this Installation Guide must already be installed on your system.

In this section, a short tutorial on how to install the toolkit's kernel libraries is given. The installation of the Geant4 kernel libraries and the proper configuration of the environment can be achieved either manually (by setting the proper environment variables) or through the Configure shell script, which will allow the installation of just the necessary source code and libraries in a specified installation area.

2.1 Using the `Configure` Script for installation

A shell script is provided for building the libraries and to allow easy installation in a specified area. The Configure shell script is placed in the top directory tree of the distribution (geant4/Configure) and allows the user or system administrator to install the Geant4 toolkit in a semi-automatic way. Some knowledge of the system is required for the installation, such as:

the compiler to be used
the path where the Geant4 toolkit is to be installed ($G4INSTALL)
definition of installation directory paths (optional)
kind of graphics/analysis system(s) installed in the system, and paths to the installation of each graphics/analysis package
the kind of library to be generated: static/shared, compound/granular.

To run the installer script for installation of the Geant4 toolkit, one must type the following from the top directory geant4:

 > ./Configure -build

and follow the on-screen instructions. The script will ask for the path in the system where the Geant4 libraries should be installed later on. The script provides default settings for most of the environment variables to be set. By pressing -RETURN-, the default values will be selected; otherwise the proper selection (or path, in case a path is requested) must be typed in.

In case the installation procedure fails for some reason, or you realise the selected options were not correct at the time the installation started, you can repeat the whole process by manually removing the current installation with:

 > cd geant4/source
 > gmake clean

where the $G4SYSTEM environment variable (specifying the kind of architecture and compiler used) is manually set in your environment (according to the flavors listed in section 1.1).

In case new modules must be added to an existing build (for example a module for visualization), this can be done manually by re-running Configure and providing the new settings.

Once the process of building the libraries has been completed successfully, the Geant4 toolkit can be installed in the specified (already existing) installation area by typing:

 > ./Configure -install

Libraries and necessary source code will be installed in lib/geant4, include/geant4 (if selected to install all headers in a single directory), src/geant4, respectively.
$G4INSTALL will be set to [INSTALLATION_AREA]/src/geant4.

2.1.1 Configuring the Environment to Use Geant4

Once libraries have been installed, the user's environment must be correctly set up for the usage of the Geant4 toolkit. The Configure script provides a way to check the existing installation and provide the correct configuration for the user's environment. Configuration scripts env[.sh.csh] can be generated, and should be sourced by the final users in order to configure their environment according to the performed installation.
To generate the configuration scripts, the user should run Configure placed in the installation area, as follows:

 > $G4INSTALL/Configure

This will generate the shell script env.csh (env.sh for bash shell) to be sourced or integrated into the shell login script (.tcshrc or .bashrc). The shell script will be generated in the user's current directory ($PWD). The user can customize it to specify for example her/his proper working directory through the variable $G4WORKDIR. Once the generated script is sourced, the user will be ready to start building a Geant4 application.
Refer to section 2.7 of the "Geant4 User's Guide for Application Developers" for information on how to build an executable in Geant4.

2.2 Installing Geant4 Manually

Before proceeding with the installation, some key environment variables must be defined in your user environment in order to specify where all software components are to be placed and to set some compilation options. A complete reference to all environment variables in Geant4 is available in section 10.5 of the "User's Guide - For Application Developers".

Required Environment Variables

G4SYSTEM:: set to one of the flavors listed in section 1.1 to specify the kind of architecture and compiler used
G4INSTALL:: path where the Geant4 toolkit tree is installed (ex. $HOME/geant4)
CLHEP_BASE_DIR:: path to the CLHEP installation

Optional Environment Variables

G4WORKDIR:: path of the user's working directory (default in $G4INSTALL)
G4LIB:: path where the kernel libraries should be installed (default in $G4INSTALL/lib)
G4TMP:: path where temporary files (object files, dependency files) are placed (default in $G4WORKDIR/tmp)
G4BIN:: path where final executable files are placed (default in $G4WORKDIR/bin).
G4INCLUDE:: path where source header files may be mirrored at installation by issuing gmake includes (default in $G4INSTALL/include)
G4DEBUG:: flag specifying that libraries be built with debug symbols (requires a lot of disk space). The default is optimised-mode
G4LIB_BUILD_SHARED:: flag specifying that kernel libraries be built as shared libraries (libraries will then be used by default). If not set, static archive libraries are built by default
G4LIB_BUILD_STATIC:: flag specifying that kernel libraries be built as static archive libraries. Note that you may specify this flag in addition to G4LIB_BUILD_SHARED to build shared and static libraries simultaneously.
G4LIB_BUILD_G3TOG4:: flag specifying that the library for the g3tog4 module be built. By default the library will not be built.
G4LIB_BUILD_ZLIB:: flag specifying that an additional library for file compression should be built (not required on Linux/Unix systems). By default the library will not be built.
G4_NO_VERBOSE:: defining this flag prevents the compilation of verbosity code (for better performance). The default is with verbosity on.

The Geant4 installation requires native STL (the Standard Template Library) as the base foundation class library. This also implies strict ISO-ANSI language compliance. In addition to the above, you might want to set the proper environment for visualization, such as:

the kind of graphics driver(s) installed in the system
the path to the installation of each graphics driver

in case you want to build the Geant4 kernel libraries with the graphics drivers built-in. See section 8.3 in the User's Application Developers Guide.

At this point, you may choose one of two ways to compile and install the kernel libraries, depending on your needs and system resources. From $G4INSTALL/source:

gmake
This will make one library for each "leaf" category (maximum library granularity) and automatically produce a map of library use and dependencies.
gmake global
This will make global libraries, one for each major category.

The main advantage of the first approach is the speed of building the libraries and of the application, which in some cases can be improved by a factor of two or three compared to the "global library" approach.
Using the "granular library" approach a fairly large number (roughly 90) of "leaf" libraries is produced. However, the dependencies and linking list are evaluated and generated automatically on the fly. The top-level GNUmakefile in $G4INSTALL/source parses the dependency files of Geant4 and produces a file libname.map in $G4LIB. libname.map is produced by the tool liblist, whose source code is in $G4INSTALL/config.
When building a binary application the script binmake.gmk in $G4INSTALL/config will parse the user's dependency files and use libname.map to determine through liblist the required libraries to add to the linking list. Only the required libraries will be loaded in the link command.
The command gmake libmap issued from $G4INSTALL/source, allows manual rebuilding of the dependency map. The command is issued by default in the normal build process for granular libraries.
It is possible to install both "granular" and "compound" libraries, by typing "gmake" and "gmake global" in sequence. In this case, to choose usage of granular libraries at link time one should set the flag G4LIB_USE_GRANULAR in the environment; otherwise compound libraries will be adopted by default.

2.3 Integrating Geant4 into a Generic Framework

As part of the Geant4 kernel libraries installation, it is also possible to put the entire set of header files in a single place, which is determined by the environment variable G4INCLUDE specifying the directory path. Therefore, it's rather straightforward to integrate Geant4 into a generic external framework, by simply knowing the path where header files are located in the system (G4INCLUDE) and where installed libraries are placed (G4LIB).

In section 10.5 of the Appendix, you can find a list of all the environment variables, together with a section explaining how to integrate external libraries which may or may not use Geant4 kernel libraries, in the GNUmake mechanism of Geant4.