4.2 CMake Configuration

Table of Contents

`CMakeLists.txt`

For a Geant4 beginner project, the CMakeLists.txt file is the central configuration that tells CMake how to build your application. It is a plain text file placed in your project’s top-level source directory, typically next to your src and include directories.

At the top of the file you normally declare the minimum CMake version and the project name. The project name is arbitrary, but should match how you refer to the application in documentation and code comments. A minimal header looks like this:

cmake

cmake_minimum_required(VERSION 3.16)
project(MyFirstGeant4Project)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

The standard setting controls which C++ features are available to your Geant4 code. Geant4 supports modern C++ standards, but you must ensure that the standard you request is supported by both your compiler and the Geant4 installation.

Next, you add the list of your source files. For a simple application with a single main and a few implementation files in src, you can either list them manually or collect them with file(GLOB ...). Beginners are usually better off listing them explicitly so that you see exactly what gets compiled. For example:

cmake

set(SOURCES
  src/main.cc
  src/DetectorConstruction.cc
  src/PhysicsList.cc
  src/ActionInitialization.cc
)

You can also add include directories where your header files (.hh) live. If you keep headers in an include directory, add:

cmake

include_directories(${PROJECT_SOURCE_DIR}/include)

Finally, you define the executable that will be built:

cmake

add_executable(myApp ${SOURCES})

The name myApp is the name of the binary that will be created in your build directory. You will later run this binary to start Geant4.

Keep the CMakeLists.txt as simple as possible when you begin. You can always add more options later, such as enabling multithreading or analysis, but the basic structure must provide a project definition, C++ standard, your source files, and a target executable.

In every Geant4 project, the CMakeLists.txt file is mandatory and must define at least:

A minimum CMake version.
A project name.
An executable target containing your source files.

Finding Geant4

The key Geant4 specific step in CMakeLists.txt is to locate the Geant4 package that you previously installed. Geant4 provides a CMake configuration module, so you typically add a single find_package command.

First, you include CMake’s own module helper:

cmake

include(${CMAKE_CURRENT_LIST_DIR}/cmake/FindGeant4.cmake OPTIONAL)

However, for most standard installations, you do not need custom modules and can rely on the configuration that Geant4 installs. The usual pattern is:

cmake

find_package(Geant4 REQUIRED)

The REQUIRED keyword tells CMake to stop with an error if Geant4 is not found. When Geant4 is correctly installed and your environment variables are set, this command discovers Geant4’s headers, libraries, and data paths.

Geant4 also ships CMake macros to help you set up include directories and compilation definitions. After the find_package call you normally include the Geant4 use file:

cmake

include(${Geant4_USE_FILE})

This line pulls in settings such as compiler flags, preprocessor definitions, and include directories that are needed for your application to use Geant4.

If you installed Geant4 in a nonstandard location, you may have to help CMake find it. One common method is to set the Geant4_DIR variable when running CMake, pointing it to the directory that contains Geant4Config.cmake, for example:

bash

cmake -DGeant4_DIR=/path/to/geant4/lib/Geant4-11.2.0 ..

Once Geant4 is found, you must link your executable target to the Geant4 libraries so that all Geant4 symbols are resolved. You do this with target_link_libraries:

cmake

target_link_libraries(myApp ${Geant4_LIBRARIES})

The variable ${Geant4_LIBRARIES} is defined by the find_package(Geant4 ...) command and usually expands to a list of all required Geant4 components. This links your application against the correct shared or static libraries, depending on how Geant4 was built.

If your Geant4 installation is compiled with optional features such as multithreading or visualization, you do not normally change find_package for those features. They are part of the installed configuration, and your build will simply link to whichever capabilities are available.

Your application cannot compile or link without Geant4 being found correctly. The critical CMake steps are:

find_package(Geant4 REQUIRED)
include(${Geant4_USE_FILE})
target_link_libraries(myApp ${Geant4_LIBRARIES})
All three must be present and must refer to the same Geant4 installation.

Building the application

Once CMakeLists.txt is prepared and Geant4 is located, you build the application by using a separate build directory. This keeps generated files away from your source code and is the standard CMake workflow.

Assume your project directory has the structure:

text

MyFirstGeant4Project/
  CMakeLists.txt
  src/
  include/

You first create a build directory, either inside the project or elsewhere. A typical setup is:

bash

cd MyFirstGeant4Project
mkdir build
cd build

Inside the build directory, you run CMake and point it back to the source directory (the directory containing CMakeLists.txt). For example:

bash

cmake ..

CMake reads ../CMakeLists.txt, finds Geant4, and generates build files for your chosen generator (for example Unix Makefiles). If Geant4 is not found, you may need to provide -DGeant4_DIR=... as described earlier.

After configuration succeeds, you compile the application by invoking the build tool. For Makefiles, you would run:

bash

cmake --build .

or equivalently:

bash

make

If the compilation completes without errors, the executable myApp (or whatever name you used in add_executable) appears inside the build directory. You can then run your Geant4 simulation directly from there:

bash

./myApp

If your application expects macro files or input data, you must either run it from a directory where those files are accessible or provide full paths. Many users keep macro files in a macros or run directory next to src and include. You can then run:

bash

./myApp macros/init.mac

depending on how your main function is written.

If you change your C++ source files, you do not need to rerun CMake. You only need to rebuild:

bash

cmake --build .

You must rerun CMake only when you change CMakeLists.txt or when you move or reinstall Geant4.

For every Geant4 project using CMake, the correct build workflow is:

Create a separate build directory.
Run cmake <path-to-source> to configure and find Geant4.
Run cmake --build . (or make, ninja, etc.) to compile.
Run the produced executable from the build directory, ensuring that any required macro files are accessible.
Never compile directly in the source directory, and do not edit generated CMake files manually.

4.2 CMake Configuration

`CMakeLists.txt`

Finding Geant4

Building the application

Comments

Where to Move