We'll assume, for illustration only, that you've copied the exampleB1 sources into a directory under your home area so that we have

      /home/you/B1/
      +- CMakeLists.txt
      +- exampleB1.cc
      +- exampleB1.in
      +- exampleB1.out
      +- include/
      |  +- B1DetectorConstruction.hh
      |  +- B1EventAction.hh
      |  +- B1PrimaryGeneratorAction.hh
      |  +- B1RunAction.hh
      |  +- B1SteppingAction.hh
      +- src/
      |  +- B1DetectorConstruction.cc
      |  +- B1EventAction.cc
      |  +- B1PrimaryGeneratorAction.cc
      |  +- B1RunAction.cc
      |  +- B1SteppingAction.cc
      +- init.mac
      +- init_vis.mac
      +- run1.mac
      +- run2.mac
      +- vis.mac
    

Here, our source directory is /home/you/B1, in other words the directory holding the CMakeLists.txt file.

We will also assume that you have already installed Geant4 in your home area under, for illustration only, /home/you/geant4-install.

Our first step is to create a build directory in which to perform the build. We will create this alongside our B1 source directory as follows:

    $ cd $HOME
    $ mkdir B1-build
  

We now change to this build directory and run CMake to generate the Makefiles needed to build the B1 application. We pass CMake two arguments:

    $ cd $HOME/B1-build
    $ cmake -DGeant4_DIR=/home/you/geant4-install/lib64/Geant4-9.5.0 $HOME/B1
  

Here, the first argument points CMake to our install of Geant4. Specifically, it is the location of the Geant4Config.cmake file that Geant4 installs to help CMake find and use Geant4. You should of course adapt the value of this variable to the location of your actual Geant4 install.

The second argument is the path to the source directory of the application we want to build, here it's just the B1 directory as discussed earlier. You should of course adapt the value of that variable to where you copied the B1 source directory.

CMake will now run to configure the build and generate Makefiles. On Linux, you will see the output

    $ cmake -DGeant4_DIR=/home/you/geant4-install/lib64/Geant4-9.5.0 $HOME/B1
    -- The C compiler identification is GNU
    -- The CXX compiler identification is GNU
    -- Check for working C compiler: /usr/bin/gcc
    -- Check for working C compiler: /usr/bin/gcc -- works
    -- Detecting C compiler ABI info
    -- Detecting C compiler ABI info - done
    -- Check for working CXX compiler: /usr/bin/c++
    -- Check for working CXX compiler: /usr/bin/c++ -- works
    -- Detecting CXX compiler ABI info
    -- Detecting CXX compiler ABI info - done
    -- Configuring done
    -- Generating done
    -- Build files have been written to: /home/you/B1-build
  

On Mac OS X, you will see slightly different output, but the last three lines should be identical.

If you now list the contents of you build directory, you can see the files generated:

    $ ls
    CMakeCache.txt       exampleB1.in   init_vis.mac  run2.mac
    CMakeFiles           exampleB1.out  Makefile      vis.mac
    cmake_install.cmake  init.mac       run1.mac
  

Note the Makefile and that all the scripts for running the exampleB1 application we're about to build have been copied across. With the Makefile available, we can now build by simply running make:

    $ make -jN
  

CMake generated Makefiles support parallel builds, so can set N suitable for the number of cores on your machine (e.g. on a dual core processor, you could set N to 2). When make runs, you should see the output

    $ make
    Scanning dependencies of target exampleB1
    [ 16%] Building CXX object CMakeFiles/exampleB1.dir/exampleB1.cc.o
    [ 33%] Building CXX object CMakeFiles/exampleB1.dir/src/B1PrimaryGeneratorAction.cc.o
    [ 50%] Building CXX object CMakeFiles/exampleB1.dir/src/B1EventAction.cc.o
    [ 66%] Building CXX object CMakeFiles/exampleB1.dir/src/B1RunAction.cc.o
    [ 83%] Building CXX object CMakeFiles/exampleB1.dir/src/B1DetectorConstruction.cc.o
    [100%] Building CXX object CMakeFiles/exampleB1.dir/src/B1SteppingAction.cc.o
    Linking CXX executable exampleB1
    [100%] Built target exampleB1
  

CMake Unix Makefiles are quite terse, but you can make them more verbose by running make with the VERBOSE argument:

    $ make VERBOSE=1
  

If you now list the contents of your build directory you will see the exampleB1 application executable:

    $ ls
    CMakeCache.txt       exampleB1      init.mac      run1.mac
    CMakeFiles           exampleB1.in   init_vis.mac  run2.mac
    cmake_install.cmake  exampleB1.out  Makefile      vis.mac
  

You can now run the application in place:

    $ ./exampleB1
    *************************************************************
     Geant4 version Name: geant4-09-05-ref-00    (2-December-2011)
                          Copyright : Geant4 Collaboration
                          Reference : NIM A 506 (2003), 250-303
                                WWW : http://cern.ch/geant4
    *************************************************************

    <<< Geant4 Physics List simulation engine: QGSP_BIC_EMY 1.1

    Checking overlaps for volume Envelope ... OK! 
    Checking overlaps for volume Shape1 ... OK! 
    Checking overlaps for volume Shape2 ... OK! 
    ### Adding tracking cuts for neutron  TimeCut(ns)= 10000  KinEnergyCut(MeV)= 0
    Visualization Manager instantiating with verbosity "warnings (3)"...
    Visualization Manager initialising...
    Registering graphics systems...
  

further output and behaviour will depend on what UI and Visualization drivers your Geant4 install supports. By default, CMake builds of the Geant4 examples activate everything available.

Other Geant4 examples may be built in the same way using CMake. If you edit the code of the example in its source directory, you only need to rerun make in the corresponding build directory to pick up and compile the changes.

We'll assume, for illustration only, that you've copied the exampleB1 sources into a directory

      C:\Users\Ben\Documents\examples\basic\B1
    

If you browse the contents of this directory you can see that it contains the CMakeLists.txt. So our source directory is C:\Users\Ben\Documents\examples\basic\B1 , in other words the directory holding the CMakeLists.txt file.

We will now use the CMake GUI to configure the build and generate a Visual Studio solution for it, and then use Visual Studio to build the application from this solution. This process involves several steps, which we break down as follows, and which can also be viewed as a slide show.

As noted above, you can also run the application through the Visual Studio debugger, although we have seen issues with setting the directory to run in correctly. The executable locates the macro files by assuming they are in the current working directory, so the executable must be run from a directory containing the macros.

If you have written Geant4 Applications before using a GNUmakefile, then Geant4Make is the system Geant4 used behind the scenes to build your application. So whilst we now refer to this old system as 'Geant4Make' the concepts should be familiar. This system, whilst deprecated for building Geant4 itself, is still supplied so that your applications using Geant4Make will continue to build using the new CMake build and install of Geant4. However, due to incompatibilities between the way Geant4Make expects Geant4 to be installed and the standard install hierarchy now used, we do not support Geant4Make on Windows platfroms, and encourage users to migrate to CMake to build their applications.

The Geant4Make GNUmake system is controlled by series of GNUmake script files which are installed under the share/Geant4-X.Y.Z/geant4make/config (where X.Y.Z is the Geant4 version number) subdirectory of the installation prefix of Geant4.

The behaviour of these script files can be controlled by the use of environment variables or equivalently variables set in your GNUmakefile before the Geant4Make script files are included). As Geant4Make makes certain assumptions about the Geant4 install, the CMake build installs shell scripts:

  +- CMAKE_INSTALL_PREFIX (where you installed Geant)
     +- share/Geant4-X.Y.Z/geant4make/geant4make.sh
     +- share/Geant4-X.Y.Z/geant4make/geant4make.csh

to map the new install structure to the expectations on Geant4Make. The appropriate script for your shell should therefore be sourced to correctly set up the Environment Variables needed by Geant4Make. If you are familiar with the old Configure/Make system and the env.(c)sh shell scripts, these new geant4make.(c)sh scripts are almost exactly equivalent.

The core GNUmake script files which control and run Geant4Make are:

Geant4Make uses a working directory set via the environment variable $G4WORKDIR to store build products. By default, the geant4make.(c)sh scripts set this to $HOME/geant4_workdir, but you can change this if you need. Geant4Make also defines a variable $G4SYSTEM which specifies the system architecture and compiler in use, e.g. Linux-g++. Executable binaries are placed in $G4WORKDIR/bin/$G4SYSTEM, and temporary files (object-files and data products of the compilation process) in $G4WORKDIR/tmp/$G4SYSTEM.

For more information on how to build and install Geant4 libraries and, refer to the "Installation Guide".

The compilation process to build an executable using Geant4Make, such as an example from examples, is started by invoking the "make" command from the (sub)directory in which you are interested. To build, for instance, exampleB1 in your $G4WORKDIR area, you should copy the module examples to your $G4WORKDIR and do the following actions:

  $ cd $G4WORKDIR/examples/basic/B1
  $ gmake

This will create, in $G4WORKDIR/bin/$G4SYSTEM, the "exampleB1" executable, which you can invoke and run. You should actually add $G4WORKDIR/bin/$G4SYSTEM to $PATH in your environment.