CMake generates buildscripts (e.g. Makefiles, Xcode projects) for the build tool (e.g. make, Xcode) of your choice. The first step after setting up the source and build trees is therefore to run CMake in the build tree to generate the needed scripts. We shall assume in the following that we are on *NIX, where CMake defaults to generating Makefiles, and we shall use the CMake command line interface. CMake has other interfaces such as the Curses based ccmake, and if you wish to use these, you should consult the documentation supplied with CMake.

If you wish to generate, e.g. Xcode projects, consult the CMake documentation for the -G option which allows you to select another tool. The GUI interface to CMake available on some platforms also has a switch to choose the build tool.

Our first step is to move into the build tree directory and then run CMake, pointing it to the source tree, and setting the CMAKE_INSTALL_PREFIX variable to set where geant4 will be installed. Using our example source and build trees from above, and assuming you want to install Geant4 under /install/location (NB $ denotes the prompt, not a literal '$')

            $ cd /path/to/geant4.9.4-build
            $ cmake -DCMAKE_INSTALL_PREFIX=/install/location ../geant4.9.4
        

The cmake command is the basic command line interface to CMake. All being well, you will see some platform dependent output (not complete)

            $ cmake -DCMAKE_INSTALL_PREFIX=/install/location ../geant4.9.4
            -- 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
            -- setting default compiler flags for CXX
            -- 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
        

CMake will then proceed to check for needed external packages. Assuming these are all installed correctly, then it should continue, giving the output (on Linux with GNU compiler)

            -- Found CLHEP version: CLHEP 2.1.0.1
            -- Found CLHEP: TRUE
            -- Geant4 backwards compatible system name: Linux
            -- Geant4 backwards compatible compiler name: g++
            -- Geant4 backwards compatible variable G4SYSTEM : Linux-g++
            -- Geant4 backwards compatible variable G4INSTALL: /install/location/share/geant4-9.4.0
            -- Geant4 backwards compatible variable G4INCLUDE: /install/location/include/geant4
            -- Geant4 backwards compatible variable G4LIB    : /install/location/lib/geant4-9.4.0
            -- The following Geant4 features are enabled:

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

Depending on the speed of your computer and/or filesystem, there may be pauses at the Configuring and Generating stages as CMake actually writes out files.

The detection of CLHEP relies on having the clhep-config script in the PATH, and if this is not the case on your system, you may see an error

            CMake Error at /usr/share/share/cmake-2.8/Modules/FindPackageHandleStandardArgs.cmake:70 (MESSAGE):
              Failed to find CLHEP (missing: CLHEP_VERSION_OK CLHEP_LIBRARIES
              CLHEP_INCLUDE_DIRS)
            Call Stack (most recent call first):
              cmake/Modules/FindCLHEP.cmake:118 (find_package_handle_standard_args)
              CMakeLists.txt:114 (find_package)


            -- Configuring incomplete, errors occurred!
        

If you see this error, you should either add the location of clhep-config to your PATH and re-run cmake as above, or re-run cmake and pass it the full path to clhep-config as

            $ cmake -DCLHEP_CONFIG_EXECUTABLE=/full/path/to/clhep-config ../geant4.9.4
        

You should then see a successfull configuration as above.

If you now list the contents of your build directory, it will contain something like

            $  ls
            CMakeCache.txt  cmake_install.cmake  CPackSourceConfig.cmake  outputs
            CMakeFiles      CPackConfig.cmake    Makefile                 source
        

Here a Makefile has been created, and if you choose to use one of the other generators, different files will be visible.

The proceedure for running CMake described in the preceeding section configures a default build of Geant4

Extra features can be enabled by passing extra -D command line arguments to CMake, as was done to tweak the install prefix above through CMAKE_INSTALL_PREFIX. Available options to enable extra features and tweak paths are listed below.

Note that if you enable a USE option, extra system checks will be triggered to check for the needed headers and libraries. If you encounter errors at this point, the error message should give you details on the cause.

Further variables are available for accurately locating needed programs and libraries, tuning the install and selecting advanced options.

It is strongly recommend to build global libraries. Granular libraries are only intended as a tool for Geant4 developers to cleanly debug and test their code.

Once CMake has configured the build, we simply need to run the appropriate build tool with the generated build scripts. In our example we have generated Makefiles, so in our build directory, we simply type

            $ make
        

to build. All being well, you should see the output

            $ make
            Scanning dependencies of target G4global
            [  1%] Building CXX object source/global/CMakeFiles/G4global.dir/HEPNumerics/src/G4AnalyticalPolSolver.cc.o
            [  1%] Building CXX object source/global/CMakeFiles/G4global.dir/HEPNumerics/src/G4ChebyshevApproximation.cc.o
...
        

By default, CMake Makefiles produce a summary output of what's being built. If you wish to see more detail, you can run make with

            $ make VERBOSE=1
        

which will output a very detailed report of everything being done.

CMake Makefiles also support parallel builds, so you can also do

            $ make -jN
        

where N should be selected based on the number of cores your machine has available. If there are errors in the build, make will immediately exit except in parallel mode where it will exit at the next branch point.

You can also build parts of Geant4 selectively.

            $ make help
        

will print a list of all targets that can be built.

If the build is successful, you can run

            $ make install
        

to install Geant4 under the location specified by CMAKE_INSTALL_PREFIX from earlier. As noted, this defaults to /usr/local on *NIX, so you will need to change it as described if you don't have write permission there. Note that you can also do a staged install using DESTDIR as

            $ make install DESTDIR=/path/to/stage
        

If you are not using Makefiles, you will need to consult the documentation of your buildtool. However, CMake generally works by the book of these tools and so using the generated buildscripts should be straightforward.