KAHIBARO
Building and Running
Table of Contents
Creating a build directory
Once your source code and CMake configuration are in place, you must build the project in a separate directory. Geant4 strongly recommends out-of-source builds. This keeps generated files and compiled objects away from your src and include trees, which makes cleaning and rebuilding much easier.
Typically, your project will have a top-level directory that contains CMakeLists.txt, for example:
MyGeant4App/
Inside this directory, create a dedicated build directory. You can choose any name, but build is conventional:
On Linux or macOS you can do this from a terminal:
cd MyGeant4App
mkdir build
cd build
The build directory will hold CMake cache files, makefiles or project files, and all compiled binaries. If you ever want to start from scratch, you can remove only this directory without touching your source code.
It is important that you run CMake and the compilation commands from inside this build directory. Running CMake directly in the source directory mixes generated and source files and is discouraged for Geant4 projects.
Running CMake
Inside the build directory, you use CMake to configure the project and to find the Geant4 installation. At this point you must already have Geant4 installed and its environment set up, so that the Geant4Config.cmake file is discoverable. Usually this is done by sourcing a script such as:
source /path/to/geant4-install/bin/geant4.sh
You generally run CMake with the path to the project source directory, which is typically one level up from build:
cd MyGeant4App/build
cmake ..
CMake reads the CMakeLists.txt in the source directory, locates Geant4 using find_package(Geant4 REQUIRED), and generates the build system for your platform. On Unix-like systems this is usually a set of Makefiles, on Windows it may be Visual Studio project files or another generator you have selected.
If CMake cannot find Geant4, it will print an error. In that case, confirm that you have sourced the Geant4 environment script, or specify the Geant4 install path explicitly, for example:
cmake -DGeant4_DIR=/path/to/geant4-install/lib/Geant4-11.2.0 ..The exact version directory will depend on the Geant4 version you installed.
Pay attention to the messages printed by CMake. You should see lines indicating that Geant4 has been found and which components are enabled, including visualization and analysis backends if you requested them in your CMakeLists.txt.
CMake must be run from the build directory, not from the source directory, and it must point to the source tree (for example cmake ..). Ensure the Geant4 environment is set before running CMake, or specify Geant4_DIR manually, otherwise the configuration will fail.
Compiling the application
After CMake completes successfully, you can compile the application using the native build tool that CMake generated for. On Linux or macOS with the default generator, this is usually make:
cd MyGeant4App/build
make
By default, this will build all targets defined in your CMakeLists.txt. The main executable is often named according to your project, for example MyGeant4App or exampleB1. When the build finishes, the executable will appear in the build directory or in a subdirectory such as bin, depending on how your CMake configuration is written.
You can also run parallel builds to speed up compilation:
make -j4
Here 4 is the number of parallel jobs. You can adjust this to match the number of CPU cores available on your system.
If you are using a different generator, such as Ninja, you would instead run:
ninja
If compilation fails, the compiler error messages refer to the source files in your src and include directories. You correct the code there, then simply rerun make or the corresponding build command in the build directory. CMake only needs to be rerun if you change the build configuration, such as adding a new source file to CMakeLists.txt.
Always compile from within the build directory using the build tool generated by CMake, such as make or ninja. Do not try to compile Geant4 applications by calling the compiler directly on individual source files.
Starting Geant4
Once the application has compiled successfully, you can start Geant4 by running the executable that was produced. Assuming the executable is created in the build directory and is named MyGeant4App, you would run:
cd MyGeant4App/build
./MyGeant4AppIf your application uses interactive mode with a terminal UI or a graphical UI, you may see a prompt such as:
Idle>At this prompt you can enter Geant4 macro commands directly, for example:
/run/initialize
/run/beamOn 10
In many applications, especially examples, the program is designed to read an initial macro file automatically. For instance, your main() may call something like:
UImanager->ApplyCommand("/control/execute init.mac");In that case you can start Geant4 and pass the macro file as an argument from the command line:
./MyGeant4App init.mac
The program will then execute the commands inside init.mac, which typically set up visualization, initialize the run, and perhaps fire a small number of events.
If your build has visualization enabled, and your application is configured for it, starting the program may open a graphics window for geometry and tracks. You interact with the application using either the GUI, the terminal prompt, or both, depending on how you configured the UI session in your main program.
For batch runs without any user interface, you can pass a macro that contains all needed commands, such as run initialization and a large /run/beamOn command. This lets you run long simulations noninteractively, for example on a cluster:
./MyGeant4App run.macRun the executable from a shell where the Geant4 environment is set, especially if your application depends on Geant4 data libraries and visualization drivers. Use macro files to control the simulation, so you do not need to recompile for simple parameter changes.
Views: 10