KAHIBARO
4.1 Project Structure
Table of Contents
Source directory
In a typical beginner Geant4 application, the source directory is the place where you put all your .cc implementation files. This is where the executable logic of your simulation lives. For a small project, you can start with just a few source files, for example a main program and the three mandatory user initialization classes.
A minimal layout might look like this:
| Path | Typical content |
|---|---|
src/main.cc | The main() function and run manager setup |
src/DetectorConstruction.cc | Geometry creation |
src/PhysicsList.cc | Physics list or physics configuration |
src/ActionInitialization.cc | Registration of user actions |
src/RunAction.cc | Optional, run level actions |
src/EventAction.cc | Optional, event level actions |
src/SteppingAction.cc | Optional, step level actions |
Geant4 expects you to write C++ subclasses of its abstract base classes. These subclasses are usually implemented in the source directory. Their corresponding class declarations live in the include directory, but the implementation code and function bodies are here.
At the CMake level you will usually tell CMake to build an executable from all .cc files in src. A simple pattern is to use add_executable with a list of source files. As your project grows, you can group related functionality in separate .cc files for clarity. For example, you might add DetectorMessenger.cc for geometry control commands, or Analysis.cc for histograms.
Try to keep the source directory focused on C++ implementation files only. Avoid mixing in data tables, macros, or input files. This separation makes your build system and version control cleaner and less confusing.
Include directory
The include directory contains the header files for your own C++ classes. In Geant4 projects, these headers almost always have the .hh extension instead of .h. For example, you pair DetectorConstruction.hh with DetectorConstruction.cc.
Typical content looks like this:
| Path | Purpose |
|---|---|
include/DetectorConstruction.hh | Declares the detector geometry class |
include/PhysicsList.hh | Declares your physics configuration class |
include/ActionInitialization.hh | Declares the action initialization class |
include/RunAction.hh | Declares run level actions |
include/EventAction.hh | Declares event level actions |
include/SteppingAction.hh | Declares step level actions |
Each header normally contains the class declaration, any member variables, and the public interface. The corresponding .cc file in src then defines the member functions declared in the header.
You will usually configure CMake to add the include directory to the compiler search path. This allows you to write straightforward includes such as
#include "DetectorConstruction.hh"
#include "PhysicsList.hh"
#include "ActionInitialization.hh"from anywhere in your project, without hard coding relative paths.
Keeping all your user class declarations in one include directory makes it easier to reuse them in other Geant4 applications. For example, a detector geometry class defined here can be compiled into several different executables, each with different primary generators or analysis code.
As your project grows in complexity, you can create subdirectories inside include to group related headers, but the basic concept remains unchanged. The include directory is the public face of your code, and the src directory is the implementation behind it.
Always keep header and source files consistent:
every class declaration in include/.hh must match its definition in src/.cc, and any change in public members must be reflected in both.
Build directory
The build directory is where CMake generates all build files and where the compiler places object files and your final executable. For a clean project structure you should keep the build directory separate from your source and include directories. This is called an out of source build.
A typical top level layout might look like:
| Path | Content |
|---|---|
CMakeLists.txt | Top level CMake configuration |
src/ | Implementation files |
include/ | Header files |
build/ | All generated build files and binaries |
macros/ | Macro command files |
data/ | Optional input or configuration data |
You do not put any source code inside the build directory. Instead, you create this directory, change into it, and run CMake there pointing back to your project root. For example, from the project root:
mkdir build
cd build
cmake ..
cmake --build .
The build directory will then contain platform specific build files, such as Makefiles or Visual Studio project files, plus a subdirectory for the compiled executable. A common pattern is that CMake places the executable directly in build/, for example build/myApplication.
Because the build directory only contains generated files, you can delete it at any time and recreate it. If your build becomes broken or Geant4 is upgraded, removing and recreating the build directory is a clean way to reconfigure everything.
Keeping build artifacts out of your source tree also simplifies version control. You usually add the build directory to .gitignore so that only the real project files in src, include, and other input directories are tracked.
Macro files
Macro files, usually with the .mac extension, contain command sequences for the Geant4 user interface. They are not C++ code, and they are not compiled. Instead, they are read at runtime by your executable. To keep them organized, it is convenient to place them in a dedicated directory, for example macros/.
Typical macro files are:
| Path | Purpose |
|---|---|
macros/init.mac | Initialization commands before a run |
macros/vis.mac | Visualization setup and drawing commands |
macros/run1.mac | Beam configuration and /run/beamOn for a test |
macros/production.mac | Settings for a longer production simulation |
Inside a macro file you place UI commands exactly as you would type them in an interactive session. For example, you can configure the physics list options, set the primary particle, change energies, open a visualization window, or start a run.
Macro files are an important part of the project structure because they let you control many simulation parameters without recompiling. You can provide several macros that share the same compiled executable, but perform different studies.
When you organize your project, treat the macros directory as part of the user interface. You can document each macro in comments at the top of the file so that others know what it does and how to use it with the executable.
To run a macro, you typically launch your built application from the build directory and pass the macro path as an argument, for example:
./myApplication macros/init.macor, from within the Geant4 user interface, you can execute:
/control/execute macros/run1.macKeeping macro files in a separate directory, and referring to them by relative paths, helps you move your project between systems without editing the macros themselves.
Views: 9