Geant4 Installation

Installing Geant4[edit | edit source]

SLAC Geant4 Tutorial: http://geant4.slac.stanford.edu/SLACTutorial14/HandsOn1/

CERN Geant4 Guide: See here for a full guide to installing Geant4 on Unix and Windows platforms, as well as how to compile and run provided examples.

Below will follow an abbreviated guide from CERN's installation website.

Download Link[edit | edit source]

Download the Geant4 source files here. The first download button is for Unix systems such as MacOS and Linux, and the second is for Windows.

Building and Installing on Unix Platforms[edit | edit source]

Unpack the Geant4 source package geant4.10.00.tar.gz to a location of your choice. This directory will be referred to as the source directory. For simplicity's sake, let's assume that the source directory is named /path/to. This way, the Geant4 source package resides in a subdirectory called /path/to/geant4.10.00.

Next we must create a build directory alongside the source directory to configure and run the build as well as store the build products. The build directory should not be the same as or inside of the source directory.

$ cd /path/to
$ mkdir geant4.10.0-build
$ ls
geant4.10.00 geant4.10.0-build

In order to configure the build, switch into the build directory and run CMake:

$ cd /path/to/geant4.10.0-build
$ cmake -DCMAKE_INSTALL_PREFIX=/path/to/geant4.10.0-install /path/to/geant4.10.00

Here, the CMake Variable CMAKE_INSTALL_PREFIX is used to set the install directory, the directory under which the Geant4 libraries, headers and support files will be installed. If you wish to activate additional options after running CMake, rerun CMake in the build directory and add the options. For instance, if after running CMake as above, you want to activate the installation of Geant4's datasets, you would run

$ cd /path/to/geant4.10.0-build
$ cmake -DGEANT4_INSTALL_DATA=ON

When you execute the CMake command, it will run to configure the build and generate Unix Makefiles to perform the actual build. You should see a long output that ends with three lines similar to this:

-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/geant4.10.0-build

After the configuration has run, CMake will have generated Unix Makefiles for building Geant4. To run the build, simply execute make in the build directory:

$ make -jN

where N is the number of parallel jobs you require.

The build will now run, and will output information on the progress of the build and current operations. If you need more output to help resolve issues or simply for information, run make as

$ make -jN VERBOSE=1

Once the build has completed, you can install Geant4 to the directory you specified earlier in CMAKE_INSTALL_PREFIX by running

$ make install

in the build directory. The libraries, headers, and resource files are installed under your chosen install prefix in a standard Unix-style hierarchy of directories. To uninstall Geant4 you can run

$ make uninstall

which will remove all installed files but not any installed directories.

Building and Installing on Windows Platforms[edit | edit source]

Unpack the Geant4 source package, geant4_10_00.zip to a location of your choice. This directory will be referred to as the source directory. For simplicity's sake, let's assume that the source directory is named C:\Users\Ben\Documents\geant4\. This way, the Geant4 source package resides in a subdirectory called C:\Users\Ben\Documents\geant4\geant4_10_00.

While CMake can be used from the Windows cmd program, you may also use the CMake GUI for configuring the build. The steps required to use CMake GUI and Visual Studio to build and install Geant4 are described below:

Open the CMake (cmake-gui) executable, and click on the Browse Source... button in the top right hand corner of the window. Use the file browser popup to locate the Geant4 source directory, and click OK.
Next you will create a directory in which to create the Visual Studio project files and hold the build products. This directory should not be the same as or inside of the source directory. Here you will create this build directory alongside the source directory. Click on the Browse Build... button in the top right hand side of the CMake GUI window. Use the file browser popup to browse back to C:\Users\Ben\Documents\geant4\, and click on the Make New Folder button. Rename the created folder to geant4.10.0-build, and click on the OK button. The two text entries at the top of the GUI should now contain C:/Users/Ben/Documents/geant4/geant4_10_00 and C:/Users/Ben/Documents/geant4/geant4.10.0-build respectively. (Note: CMake always represents Windows paths with forward slashes).
Click on the Configure button on the bottom left hand side of the GUI. In the popup window, select Visual Studio 2010. Ensure only the Use default native compilers radio box is checked. Then click on the Finish button.
CMake will then run to check features and provide an initial configuration. All being well, you will see red highlighted entries in the main options window including CMAKE and GEANT4 entries. Note that the red highlighting means CMake has not fully resolved all configuration variables yet, no that there has been an error. On Express editions of Visual Studio, you may see a warning about missing system runtime libraries in the logging window at the bottom of the GUI, but this can be ignored for a standard install. On the latest versions of CMake, you may also see warnings relating to LINK_INTERFACE_LIBRARIES and these can be ignored. Any other errors will be reported in this logging window.
By default, CMake will configure the build to install Geant4 under C:/Program Files/Geant4. If you do not wish to use this directory, or do not have permission to install there, you can change the installation location. Click on the arrow next to the CMAKE entry in the central options display to expand all CMake specific configuration options. Scroll down to locate the CMAKE_INSTALL_PREFIX entry. Click on the entry and edit the path directly or via the file browser popup. In this example we will modify this install directory to C:/Users/Ben/Documents/geant4/geant4.10.0-install.
If you need to activate extra components of Geant4, click on the expansion arrow next to the GEANT4 entry in the central options display to expand all Geant4 specific configuration options. Simply click on the tick box next to an option to select it if you require.
Once you have adjusted any options, click on the Configure button again. After this has finished, all the options listed in the central option display should be white. If you still have entries in red, click Configure to reconfigure until all entries are white.
Now click on the Generate button to generate the Visual Studio project. If everything is correct, CMake will generate the solution files and report Configuring done, Generating done in the logging window at the bottom of the GUI. You can now close the CMake GUI.
Now start up Visual Studio and choose Open Project. Browse to the build directory and open the Geant4.sln Microsoft Visual Studio Solution file. Note that it may take some time to fully configure, open and parse all files in the solution.
By default, the Visual Studio solution builds the Debug Configuration, so if you want an optimized build, you should select the Release option from the drop down Solutions Configurations menu in the toolbar Visual Studio 2010).
In the Solution Explorer, right click on the INSTALL solution and select Build from the popup menu. The solution will now build and install to the directory you chose for CMAKE_INSTALL_PREFIX earlier. If you wish to build a different configuration (Release if you built Debug first, for example), then simply change the solution configuration as described in the previous paragraph, and build the INSTALL solution again.
If you see a successful build, you can exit Visual Studio.

Setting Up and Using an Install of Geant4[edit | edit source]

If you choose the default installation paths, then your install of Geant4 is completely contained under the directory you chose for CMAKE_INSTALL_PREFIX, with the following structure:

+- CMAKE_INSTALL_PREFIX
    +- bin/
    |  +- geant4-config   (UNIX ONLY)
    |  +- geant4.csh      (UNIX ONLY)
    |  +- geant4.sh       (UNIX ONLY)
    |  +- G4global.dll    (WINDOWS ONLY)
    |  +- ...
    +- include/
    |  +- Geant4/
    |     +- G4global.hh
    |     +- ...
    |     +- CLHEP/       (WITH INTERNAL CLHEP ONLY)
    |     +- tools/
    +- lib/               (MAY BE lib64 on LINUX)
    |  +- libG4global.so  (AND/OR .a, OR G4Global.lib ON WINDOWS)
    |  +- ...
    |  +- Geant4-10.0.0/
    |     +- Geant4Config.cmake
    |     +- Geant4ConfigVersion.cmake
    |     +- Geant4LibraryDepends.cmake
    |     +- Geant4LibraryDepends-Release.cmake
    |     +- UseGeant4.cmake
    |     +- Linux-g++    (OR Darwin-g++ UNIX ONLY SOFTLINK -> ..)
    |     +- Modules/
    +- share
       +- Geant4-10.0.0
          +- data/        (IF GEANT4_INSTALL_DATA WAS SET)
          +- examples/
          +- geant4make/
             +- geant4make.csh
             +- geant4make.sh
             +- config/

Unix[edit | edit source]

If you wish to make the Geant4 binaries and libraries available via your PATH and library path (LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on Mac OS X), together with default environment variables for locating datasets, you should source the relevant script in CMAKE_INSTALL_PREFIX/bin

On interactive bourne shells (e.g. bash), do (assuming you are in CMAKE_INSTALL_PREFIX/bin):

$ . geant4.sh

This command can also be used to setup the Geant4 environment in other Bourne shell scripts. You can also supply the full path to the script rather than changing to the directory containing it.

On interactive C shells, do (assuming you are in CMAKE_INSTALL_PREFIX/bin):

$ source geant4.csh

In an interactive session you can also supply the full path to the script rather than changing to the directory containing it. The C shell script cannot be sourced directly inside other shell scripts due to a limitation of the C shell which prevents the script being able to locate itself. If you need to source the C shell script inside another, then you can use the command

cd CMAKE_INSTALL_PREFIX/bin ; source geant4.csh

where you should replace CMAKE_INSTALL_PREFIX/bin with the directory you installed geant4.csh in. You can also use the command

source CMAKE_INSTALL_PREFIX/bin/geant4.csh CMAKE_INSTALL_PREFIX/bin

where as above you should replace CMAKE_INSTALL_PREFIX/bin with the directory where geant4.csh is located.

Windows[edit | edit source]

On Windows, you should add the directory containing the Geant4 dll files to your PATH environment variable. On Windows 7/XP, this can be done via the Control Panel as follows

Open the Windows Control Panel.
Open the System item in the Control Panel.
Click on the Advanced system settings link on the System window (on Windows XP, click on the Advanced tab).
Click on the Environment Variables button in the System Properties window.
Select the PATH entry in the User variables list, and click the Edit button. If PATH is not present, click on the New and create it.
In the popup Edit User Variable window, append the directory in which the Geant4 dlls are installed to the Variable value entry of the PATH variable (Note that on Windows, path entries are separated by semicolons). It's very important to append the Geant4 dll path if you have an existing PATH, otherwise other programs may stop working correctly! If the Variable value entry of the PATH variable is empty, or you've just created it, you can simply set the value to the directory in which the Geant4 dlls are installed. Once you have edited, click OK.

Building Applications[edit | edit source]

To build an application that uses the Geant4 toolkit, it is necessary to include Geant4 headers in the application sources and link the application to the Geant4 libraries. The details of how to implement source code for an application are described in detail in the Geant4 User's Guide for Application Developers. Here, the guide describes how you can build your sources into an application and compile and link it against Geant4.

This guide provides three main tools to help with building applications: a CMake "Geant4Config.cmake" config file, a GNUMake module "binmake.gmk" and a UNIX-only command line program "geant4-config". The following sections give an overview of each tool and how to use them to build a simple application.

Using CMake to build Applications: Geant4Config.cmake[edit | edit source]

Geant4 installs a file named Geant4Config.cmake located in:

+- CMAKE_INSTALL_PREFIX
   +- lib/
      +- Geant4-10.0.0/
         +- Geant4Config.cmake

which is designed for use with the CMake scripting language find_package command. Building a Geant4 application using CMake therefore involves writing a CMake script CMakeLists.txt using this and other CMake commands to locate Geant4 and describe the build of your application against it. Whilst it requires a bit of effort to write the script, CMake provides a very powerful and flexible tool, especially if you are working on multiple platforms. It is therefore the method we recommend for building Geant4 applications.

We'll use Basic Example B1, which you may find in the Geant4 source directory under examples/basic/B1, to demonstrate the use of CMake to build a Geant4 application. You'll find links to the latest CMake documentation for the commands used throughout, so please follow these for further information. The application sources and scripts are arranged in the following directory structure:

+- B1/
   +- CMakeLists.txt
   +- exampleB1.cc
   +- include/
   |  ... headers.hh ...
   +- src/
      ... sources.cc ...

Here, exampleB1.cc contains main() for the application, with include/ and src/ containing the implementation class headers and sources respectively. This arrangement of source files is not mandatory when building with CMake, apart from the location of the CMakeLists.txt file in the root directory of the application.

The text file CMakeLists.txt is the CMake script containing commands which describe how to build the exampleB1 application:

 # (1)
 cmake_minimum_required(VERSION 2.6 FATAL_ERROR)
 project(B1)

 # (2)
 option(WITH_GEANT4_UIVIS "Build example with Geant4 UI and Vis drivers"        ON)
 if(WITH_GEANT4_UIVIS)
   find_package(Geant4 REQUIRED ui_all vis_all)
 else()
   find_package(Geant4 REQUIRED)
 endif()

 # (3)
 include(${Geant4_USE_FILE})
 include_directories(${PROJECT_SOURCE_DIR}/include)

 # (4)      
 file(GLOB sources ${PROJECT_SOURCE_DIR}/src/*.cc)
 file(GLOB headers ${PROJECT_SOURCE_DIR}/include/*.hh)

 # (5)
 add_executable(exampleB1 exampleB1.cc ${sources} ${headers})
 target_link_libraries(exampleB1 ${Geant4_LIBRARIES})

 # (6)
 set(EXAMPLEB1_SCRIPTS
   exampleB1.in
   exampleB1.out
   init.mac
   init_vis.mac
   run1.mac
   run2.mac
   vis.mac
   )

 foreach(_script ${EXAMPLEB1_SCRIPTS})
   configure_file(
     ${PROJECT_SOURCE_DIR}/${_script}
     ${PROJECT_BINARY_DIR}/${_script}
     COPYONLY
     )
 endforeach()

 # (7)
 install(TARGETS exampleB1 DESTINATION bin)

For clarity, the above listing has stripped out the main comments (CMake comments begin with a "#") you'll find in the actual file to highlight each distinct task:

Basic Configuration:
The cmake_minimum_required command simply ensures we're using a suitable version of CMake. The project command sets the name of the project and enables and configures C and C++ compilers.
Find and Configure Geant4:
The aforementioned find_package command is used to locate and configure Geant4 (we'll see how to specify the location later when we run CMake), the REQUIRED argument being supplied so that CMake will fail with an error if it cannot find Geant4. The option command specifies a boolean variable which defaults to ON , and which can be set when running CMake via a -D command line argument, or toggled in the CMake GUI interfaces. We wrap the calls to find_package in a conditional block on the option value. This allows us to configure the use of Geant4 UI and Visualization drivers by exampleB1 via the ui_all vis_all "component" arguments to find_package . These components and their usage is described later.
Configure the Project to Use Geant4 and B1 Headers
To automatically configure the header path, compiler flags adn compiler definitions needed for linking to Geant4, we use the include command to load a CMake script supplied by Geant4. The CMake variable named Geant4_USE_FILE is set to the path to this module when Geant4 is located by find_package. We use the include_directories command to add the B1 header directory to the compiler's header search path. The CMake variable PROJECT_SOURCE_DIR points to the top level directory of the project and is set by the earlier call to the project command.
List the Sources to Build the Application
Use the globbing functionality of the file command to prepare lists of the B1 source and header files.
Define and Link the Executable
The add_executable command defines the build of an application, outputting an executable named by its first argument, with the sources following. After adding the executable use the target_link_libraries command to link it with the Geant4 libraries. The Geant4_LIBRARIES variable is set by find_package when Geant4 is located, and is a list of all the libraries needed to link against to use Geant4.
Copy any Runtime Scripts to the Build Directory
Because we want to support out of source builds so that we won't mix CMake generated files with our actual sources, we copy any scripts used by the B1 application to the build directory. We use foreach to loop over the list of scripts we constructed, and configure_file to perform the actual copy. Here, the CMake variable PROJECT_BINARY_DIR is set by the earlier call to the project command and points to the directory where we run CMake to configure the build.
If Requred, Install the Executable
Use the install command to create an install target that will install the executable to a bin directory under CMAKE_INSTALL_PREFIX. If you don't intend your application to be unstable, i.e. you only want to use it locally when built, you can leave this out.

This sequence of commands is the most basic needed to compile and link an application with Geant4, and is easily extendable to more involved use cases such as using other third party packages (via find_package ) or platform specific configuration.

With the CMake script in place, using it to build an application is a two step process. First CMake is run to generate buildscripts to describe the build. By default, these will be Makefiles on Unix platforms, and Visual Studio solutions on Windows, but you can generate scripts for other tools like Xcode and Eclipse if you wish. Second, the buildscripts are run by the chosen build tool to compile and link the application.

A key concept with CMake is that we generate the buildscripts and run the build in a separate directory, the so-called build directory, from the directory in which the sources reside, the so-called source directory. This is the exact same technique we used when building Geant4 itself. Whilst this may seem awkward to begin with, it is a very useful technique to employ. It prevents mixing of CMake generated files with those of your application, and allows you to have multiple builds against a single source without having to clean up, reconfigure and rebuild.

For using Geant4Make to build Applications, read the CERN guide here.

For writing your own makefiles, or using other Unix build systems, read the CERN guide here.