docs with examples and compiles snippets

paulgessinger · paulgessinger · commit 0ca5549dde71 · 2026-03-20T09:54:12.000+01:00
diff --git a/Core/CMakeLists.txt b/Core/CMakeLists.txt
@@ -14,7 +14,7 @@ set(ACTS_GEOMETRY_MODULE_CAPI 1)
 set(_acts_geometry_module_abi_tag
     "acts-${Acts_VERSION}|sys-${CMAKE_SYSTEM_NAME}|arch-${CMAKE_SYSTEM_PROCESSOR}|cxx-${CMAKE_CXX_COMPILER_ID}-${CMAKE_CXX_COMPILER_VERSION}|capi-${ACTS_GEOMETRY_MODULE_CAPI}"
 )
-set(ACTS_GEOMETRY_MODULE_ABI_TAG_VALUE
+set(ACTS_GEOMETRY_MODULE_ABI_TAG
     "${_acts_geometry_module_abi_tag}"
     CACHE INTERNAL
     "ACTS geometry module ABI tag"
diff --git a/Core/include/Acts/Geometry/GeometryModuleLoader.hpp b/Core/include/Acts/Geometry/GeometryModuleLoader.hpp
@@ -26,6 +26,9 @@ class TrackingGeometry;
 /// the tracking geometry. The returned deleter keeps the module loaded until
 /// the geometry is destroyed. Throws if the module requires user data (e.g.
 /// a DD4hep module) — use the appropriate typed loader instead.
+/// @param modulePath Path to the geometry module shared library.
+/// @param logger Logger instance used by the module loader.
+/// @return Shared pointer to the loaded tracking geometry.
 std::shared_ptr<TrackingGeometry> loadGeometryModule(
     const std::filesystem::path& modulePath,
     const Logger& logger = getDummyLogger());
diff --git a/Plugins/DD4hep/include/ActsPlugins/DD4hep/GeometryModuleLoader.hpp b/Plugins/DD4hep/include/ActsPlugins/DD4hep/GeometryModuleLoader.hpp
@@ -30,6 +30,10 @@ class TrackingGeometry;
 /// validate ABI compatibility, build and return the tracking geometry.
 /// The returned deleter keeps the module loaded until the geometry is
 /// destroyed.
+/// @param modulePath Path to the geometry module shared library.
+/// @param detector DD4hep detector instance passed to the module.
+/// @param logger Logger instance used by the module loader.
+/// @return Shared pointer to the loaded tracking geometry.
 std::shared_ptr<TrackingGeometry> loadDD4hepGeometryModule(
     const std::filesystem::path& modulePath, const dd4hep::Detector& detector,
     const Logger& logger = getDummyLogger());
diff --git a/cmake/ActsConfig.cmake.in b/cmake/ActsConfig.cmake.in
@@ -16,7 +16,7 @@
 set(Acts_COMPONENTS @_components@)
 set(Acts_COMMIT_HASH "@_acts_commit_hash@")
 set(Acts_COMMIT_HASH_SHORT "@_acts_commit_hash_short@")
-set(Acts_GEOMETRY_MODULE_ABI_TAG "@ACTS_GEOMETRY_MODULE_ABI_TAG_VALUE@")
+set(ACTS_GEOMETRY_MODULE_ABI_TAG "@ACTS_GEOMETRY_MODULE_ABI_TAG@")
 
 # print version and components information
 if(NOT Acts_FIND_QUIETLY)
diff --git a/cmake/ActsDD4hepGeometryModuleHelpers.cmake b/cmake/ActsDD4hepGeometryModuleHelpers.cmake
@@ -7,12 +7,12 @@ function(acts_add_dd4hep_geometry_module target)
         )
     endif()
     if(
-        NOT DEFINED Acts_GEOMETRY_MODULE_ABI_TAG
-        OR Acts_GEOMETRY_MODULE_ABI_TAG STREQUAL ""
+        NOT DEFINED ACTS_GEOMETRY_MODULE_ABI_TAG
+        OR ACTS_GEOMETRY_MODULE_ABI_TAG STREQUAL ""
     )
         message(
             FATAL_ERROR
-            "Acts_GEOMETRY_MODULE_ABI_TAG is not set; cannot configure DD4hep geometry module target '${target}'."
+            "ACTS_GEOMETRY_MODULE_ABI_TAG is not set; cannot configure DD4hep geometry module target '${target}'."
         )
     endif()
 
@@ -21,6 +21,6 @@ function(acts_add_dd4hep_geometry_module target)
     target_link_libraries(${target} PRIVATE Acts::PluginDD4hep)
     target_compile_definitions(
         ${target}
-        PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${Acts_GEOMETRY_MODULE_ABI_TAG}"
+        PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${ACTS_GEOMETRY_MODULE_ABI_TAG}"
     )
 endfunction()
diff --git a/cmake/ActsGeometryModuleHelpers.cmake b/cmake/ActsGeometryModuleHelpers.cmake
@@ -7,12 +7,12 @@ function(acts_add_geometry_module target)
         )
     endif()
     if(
-        NOT DEFINED Acts_GEOMETRY_MODULE_ABI_TAG
-        OR Acts_GEOMETRY_MODULE_ABI_TAG STREQUAL ""
+        NOT DEFINED ACTS_GEOMETRY_MODULE_ABI_TAG
+        OR ACTS_GEOMETRY_MODULE_ABI_TAG STREQUAL ""
     )
         message(
             FATAL_ERROR
-            "Acts_GEOMETRY_MODULE_ABI_TAG is not set; cannot configure geometry module target '${target}'."
+            "ACTS_GEOMETRY_MODULE_ABI_TAG is not set; cannot configure geometry module target '${target}'."
         )
     endif()
 
@@ -21,6 +21,6 @@ function(acts_add_geometry_module target)
     target_link_libraries(${target} PRIVATE Acts::Core)
     target_compile_definitions(
         ${target}
-        PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${Acts_GEOMETRY_MODULE_ABI_TAG}"
+        PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${ACTS_GEOMETRY_MODULE_ABI_TAG}"
     )
 endfunction()
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -33,5 +33,33 @@ set_target_properties(docs-examples PROPERTIES EXCLUDE_FROM_ALL TRUE)
 target_sources(
     docs-examples
     PRIVATE examples/logging.cpp examples/units.cpp examples/errors.cpp
+            examples/geometry_module.cpp
 )
 target_link_libraries(docs-examples PRIVATE Acts::Core)
+
+if(ACTS_BUILD_PLUGIN_DD4HEP)
+    target_link_libraries(docs-examples PRIVATE Acts::PluginDD4hep)
+    target_compile_definitions(docs-examples PRIVATE ACTS_BUILD_PLUGIN_DD4HEP)
+endif()
+
+# Compile the module writing templates as real geometry modules so the
+# snippet examples are verified at build time.
+#! [Plain Module CMake]
+include(ActsGeometryModuleHelpers)
+acts_add_geometry_module(
+    docs-geometry-module-template
+    examples/geometry_module_template.cpp
+)
+#! [Plain Module CMake]
+add_dependencies(docs-examples docs-geometry-module-template)
+
+if(ACTS_BUILD_PLUGIN_DD4HEP)
+    #! [DD4hep Module CMake]
+    include(ActsDD4hepGeometryModuleHelpers)
+    acts_add_dd4hep_geometry_module(
+        docs-geometry-module-template-dd4hep
+        examples/geometry_module_template_dd4hep.cpp
+    )
+    #! [DD4hep Module CMake]
+    add_dependencies(docs-examples docs-geometry-module-template-dd4hep)
+endif()
diff --git a/docs/examples/geometry_module.cpp b/docs/examples/geometry_module.cpp
@@ -0,0 +1,42 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 CERN for the benefit of the ACTS project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+#include "Acts/Geometry/GeometryModuleLoader.hpp"
+#include "Acts/Utilities/Logger.hpp"
+
+#include <filesystem>
+
+#ifdef ACTS_BUILD_PLUGIN_DD4HEP
+#include "ActsPlugins/DD4hep/GeometryModuleLoader.hpp"
+
+#include <DD4hep/Detector.h>
+#endif
+
+void exampleLoadPlainModule(const Acts::Logger& logger,
+                            const std::filesystem::path& modulePath) {
+  //! [Load Plain Module]
+  auto geometry = Acts::loadGeometryModule(modulePath, logger);
+  // 'geometry' is a std::shared_ptr<Acts::TrackingGeometry>.
+  // The shared library stays loaded until 'geometry' is destroyed.
+  //! [Load Plain Module]
+  (void)geometry;
+}
+
+#ifdef ACTS_BUILD_PLUGIN_DD4HEP
+void exampleLoadDD4hepModule(const dd4hep::Detector& detector,
+                             const Acts::Logger& logger,
+                             const std::filesystem::path& modulePath) {
+  //! [Load DD4hep Module]
+  auto geometry =
+      Acts::loadDD4hepGeometryModule(modulePath, detector, logger);
+  // 'geometry' is a std::shared_ptr<Acts::TrackingGeometry>.
+  // The shared library stays loaded until 'geometry' is destroyed.
+  //! [Load DD4hep Module]
+  (void)geometry;
+}
+#endif
diff --git a/docs/examples/geometry_module_template.cpp b/docs/examples/geometry_module_template.cpp
@@ -0,0 +1,25 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 CERN for the benefit of the ACTS project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+//! [Write Plain Module]
+#include "Acts/Geometry/GeometryModuleHelper.hpp"
+#include "Acts/Geometry/TrackingGeometry.hpp"
+
+#include <stdexcept>
+
+namespace {
+std::unique_ptr<Acts::TrackingGeometry> buildMyGeometry(
+    const Acts::Logger& logger) {
+  ACTS_INFO("Building my geometry");
+  // ... construct and return a TrackingGeometry ...
+  throw std::logic_error("not implemented");
+}
+}  // namespace
+
+ACTS_DEFINE_GEOMETRY_MODULE(buildMyGeometry)
+//! [Write Plain Module]
diff --git a/docs/examples/geometry_module_template_dd4hep.cpp b/docs/examples/geometry_module_template_dd4hep.cpp
@@ -0,0 +1,27 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 CERN for the benefit of the ACTS project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+//! [Write DD4hep Module]
+#include "ActsPlugins/DD4hep/GeometryModuleHelper.hpp"
+#include "Acts/Geometry/TrackingGeometry.hpp"
+
+#include <DD4hep/Detector.h>
+#include <stdexcept>
+
+namespace {
+std::unique_ptr<Acts::TrackingGeometry> buildMyGeometry(
+    const dd4hep::Detector& detector, const Acts::Logger& logger) {
+  (void)detector;
+  ACTS_INFO("Building DD4hep geometry");
+  // ... use detector to build and return a TrackingGeometry ...
+  throw std::logic_error("not implemented");
+}
+}  // namespace
+
+ACTS_DEFINE_DD4HEP_GEOMETRY_MODULE(buildMyGeometry)
+//! [Write DD4hep Module]
diff --git a/docs/groups/detector_descr/runtime_geometry_modules.md b/docs/groups/detector_descr/runtime_geometry_modules.md
@@ -0,0 +1,156 @@
+@defgroup geometry_module_loading Runtime geometry module loading
+@ingroup geometry
+@brief Loading tracking geometries from runtime shared libraries.
+
+This topic documents the runtime geometry module loading entry points:
+
+- @ref Acts::loadGeometryModule for modules that do not require user data.
+- @ref Acts::loadDD4hepGeometryModule for DD4hep-based modules.
+
+Both loaders validate module ABI compatibility before constructing the
+@ref Acts::TrackingGeometry, and keep the shared library loaded for the
+lifetime of the returned geometry object.
+
+## Overview
+
+Runtime geometry modules allow tracking geometries to be compiled as
+independent shared libraries (`.so`/`.dylib`) and loaded at runtime without
+recompiling the host application. This is useful when:
+
+- The geometry changes frequently and recompiling the full framework is costly.
+- Different geometry variants need to be swapped at runtime.
+- The geometry is developed and distributed independently from the experiment
+  framework.
+
+@note Runtime geometry modules rely on `dlopen`/`dlsym` and are
+      only supported on Unix-like systems (Linux, macOS).
+
+## The module ABI
+
+Every geometry module must export a single C-linkage entry point:
+
+```c
+extern "C" const ActsGeometryModuleV1* acts_geometry_module_v1(void);
+```
+
+The returned `ActsGeometryModuleV1` struct (defined in
+`Acts/Geometry/GeometryModule.h`) carries four fields:
+
+| Field              | Type                                      | Purpose                                                  |
+|--------------------|-------------------------------------------|----------------------------------------------------------|
+| `module_abi_tag`   | `const char*`                             | Build-time ABI tag matched against the host library      |
+| `user_data_type`   | `const char*`                             | Type name of the extra context the module needs, or null |
+| `build`            | `void* (*)(const void* user_data, const void* logger)` | Constructs the geometry; returns a heap-allocated `TrackingGeometry*` or null on failure |
+| `destroy`          | `void (*)(void* handle)`                  | Deletes the geometry object returned by `build`          |
+
+You never fill this struct manually. Use the provided helper macros instead
+(see @ref geometry_module_writing "Writing a geometry module" below).
+
+## ABI compatibility
+
+Each ACTS build is tagged with an opaque string (`Acts_GEOMETRY_MODULE_ABI_TAG`)
+that encodes the library version. The loader checks that
+`module_abi_tag` from the shared library matches the tag compiled into the host
+`ActsCore` library. A mismatch causes an immediate `std::runtime_error`, so a
+module built against one ACTS version cannot accidentally be loaded by a
+different one.
+
+## Loading a module
+
+### Plain module (no extra context)
+
+Include `Acts/Geometry/GeometryModuleLoader.hpp`, then:
+
+@snippet{trimleft} examples/geometry_module.cpp Load Plain Module
+
+### DD4hep module
+
+Include `ActsPlugins/DD4hep/GeometryModuleLoader.hpp`, then:
+
+@snippet{trimleft} examples/geometry_module.cpp Load DD4hep Module
+
+The loader passes a pointer to `detector` through the opaque `void* user_data`
+argument. It validates that the module declares `user_data_type == "dd4hep::Detector"`;
+trying to load a plain module with `loadDD4hepGeometryModule` (or vice-versa)
+throws a descriptive `std::runtime_error`.
+
+@anchor geometry_module_writing
+## Writing a geometry module
+
+### Plain module
+
+1. Create a source file with a build function:
+
+@snippet{trimleft} examples/geometry_module_template.cpp Write Plain Module
+
+2. Register it in CMake using `acts_add_geometry_module`:
+
+@snippet{trimleft} CMakeLists.txt Plain Module CMake
+
+The CMake helper creates a `SHARED` library target, links it against
+`Acts::Core`, and injects the `ACTS_GEOMETRY_MODULE_ABI_TAG` compile definition
+required by `ACTS_DEFINE_GEOMETRY_MODULE`.
+
+### DD4hep module
+
+1. Create a source file with a build function that takes a `dd4hep::Detector`:
+
+@snippet{trimleft} examples/geometry_module_template_dd4hep.cpp Write DD4hep Module
+
+2. Register it in CMake using `acts_add_dd4hep_geometry_module`:
+
+@snippet{trimleft} CMakeLists.txt DD4hep Module CMake
+
+This links against `Acts::PluginDD4hep` instead of `Acts::Core` and sets the
+same ABI tag compile definition.
+
+## Lifetime management
+
+The `std::shared_ptr<TrackingGeometry>` returned by both loaders uses a custom
+deleter that:
+
+1. Calls `descriptor->destroy()` to delete the `TrackingGeometry` object via
+   the module's own destructor (important for correct cross-boundary `delete`).
+2. Keeps a `shared_ptr<void>` to the `dlopen` handle alive, so the shared
+   library is only unloaded **after** the geometry is destroyed — preventing
+   use-after-unload of virtual dispatch tables or static data.
+
+## Error handling
+
+All errors are reported as `std::runtime_error`. The loader performs several
+checks in order before invoking the build function:
+
+- **File not found.** The path is checked with `std::filesystem::exists` before
+  calling `dlopen`. This gives a clearer error than the linker error that
+  `dlopen` would produce for a missing file.
+
+- **`dlopen` failure.** If the operating system cannot load the shared library
+  (e.g. missing transitive dependencies, wrong architecture), the error string
+  from `dlerror` is included in the exception message.
+
+- **Missing entry point.** The loader looks up the symbol
+  `acts_geometry_module_v1` via `dlsym`. If it is absent the module was either
+  not built with `ACTS_DEFINE_GEOMETRY_MODULE` / `ACTS_DEFINE_DD4HEP_GEOMETRY_MODULE`,
+  or the symbol was stripped or hidden by the linker.
+
+- **Null or incomplete descriptor.** The struct returned by the entry point must
+  be non-null and have `module_abi_tag` set and both function-pointer fields (`build`, `destroy`)
+  non-null. A null or partially initialized descriptor indicates a
+  programming error in the module.
+
+- **ABI tag mismatch.** `module_abi_tag` is compared against the tag baked into
+  the host `ActsCore` library at its own build time. A mismatch means the module
+  and the host were built from different ACTS versions and cannot safely
+  interoperate. Rebuild the module against the same ACTS installation.
+
+- **User-data type mismatch.** The `user_data_type` field in the descriptor is
+  compared against the type the loader expects. If you call `loadGeometryModule`
+  on a module that declares a `user_data_type` (i.e. it needs extra context such
+  as a `dd4hep::Detector`), or call a typed loader (e.g. `loadDD4hepGeometryModule`)
+  on a plain module, a `std::runtime_error` is thrown with a hint pointing to
+  the correct loader to use.
+
+- **`build` returns null.** The module's build function returned a null pointer,
+  which means it failed to construct the geometry. Exceptions thrown inside
+  `build` are caught by the helper and logged via `ACTS_ERROR` before the null
+  is returned, so check the log for the underlying cause.

Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,7 @@ set(ACTS_GEOMETRY_MODULE_CAPI 1)`
`14`	`14`	`set(_acts_geometry_module_abi_tag`
`15`	`15`	`"acts-${Acts_VERSION}\|sys-${CMAKE_SYSTEM_NAME}\|arch-${CMAKE_SYSTEM_PROCESSOR}\|cxx-${CMAKE_CXX_COMPILER_ID}-${CMAKE_CXX_COMPILER_VERSION}\|capi-${ACTS_GEOMETRY_MODULE_CAPI}"`
`16`	`16`	`)`
`17`		`-set(ACTS_GEOMETRY_MODULE_ABI_TAG_VALUE`
	`17`	`+set(ACTS_GEOMETRY_MODULE_ABI_TAG`
`18`	`18`	`"${_acts_geometry_module_abi_tag}"`
`19`	`19`	`CACHE INTERNAL`
`20`	`20`	`"ACTS geometry module ABI tag"`
Original file line number	Diff line number	Diff line change
`@@ -7,12 +7,12 @@ function(acts_add_dd4hep_geometry_module target)`
`7`	`7`	`)`
`8`	`8`	`endif()`
`9`	`9`	`if(`
`10`		`- NOT DEFINED Acts_GEOMETRY_MODULE_ABI_TAG`
`11`		`- OR Acts_GEOMETRY_MODULE_ABI_TAG STREQUAL ""`
	`10`	`+ NOT DEFINED ACTS_GEOMETRY_MODULE_ABI_TAG`
	`11`	`+ OR ACTS_GEOMETRY_MODULE_ABI_TAG STREQUAL ""`
`12`	`12`	`)`
`13`	`13`	`message(`
`14`	`14`	`FATAL_ERROR`
`15`		`- "Acts_GEOMETRY_MODULE_ABI_TAG is not set; cannot configure DD4hep geometry module target '${target}'."`
	`15`	`+ "ACTS_GEOMETRY_MODULE_ABI_TAG is not set; cannot configure DD4hep geometry module target '${target}'."`
`16`	`16`	`)`
`17`	`17`	`endif()`
`18`	`18`
`@@ -21,6 +21,6 @@ function(acts_add_dd4hep_geometry_module target)`
`21`	`21`	`target_link_libraries(${target} PRIVATE Acts::PluginDD4hep)`
`22`	`22`	`target_compile_definitions(`
`23`	`23`	`${target}`
`24`		`- PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${Acts_GEOMETRY_MODULE_ABI_TAG}"`
	`24`	`+ PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${ACTS_GEOMETRY_MODULE_ABI_TAG}"`
`25`	`25`	`)`
`26`	`26`	`endfunction()`
Original file line number	Diff line number	Diff line change
`@@ -7,12 +7,12 @@ function(acts_add_geometry_module target)`
`7`	`7`	`)`
`8`	`8`	`endif()`
`9`	`9`	`if(`
`10`		`- NOT DEFINED Acts_GEOMETRY_MODULE_ABI_TAG`
`11`		`- OR Acts_GEOMETRY_MODULE_ABI_TAG STREQUAL ""`
	`10`	`+ NOT DEFINED ACTS_GEOMETRY_MODULE_ABI_TAG`
	`11`	`+ OR ACTS_GEOMETRY_MODULE_ABI_TAG STREQUAL ""`
`12`	`12`	`)`
`13`	`13`	`message(`
`14`	`14`	`FATAL_ERROR`
`15`		`- "Acts_GEOMETRY_MODULE_ABI_TAG is not set; cannot configure geometry module target '${target}'."`
	`15`	`+ "ACTS_GEOMETRY_MODULE_ABI_TAG is not set; cannot configure geometry module target '${target}'."`
`16`	`16`	`)`
`17`	`17`	`endif()`
`18`	`18`
`@@ -21,6 +21,6 @@ function(acts_add_geometry_module target)`
`21`	`21`	`target_link_libraries(${target} PRIVATE Acts::Core)`
`22`	`22`	`target_compile_definitions(`
`23`	`23`	`${target}`
`24`		`- PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${Acts_GEOMETRY_MODULE_ABI_TAG}"`
	`24`	`+ PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${ACTS_GEOMETRY_MODULE_ABI_TAG}"`
`25`	`25`	`)`
`26`	`26`	`endfunction()`