feat: dlopen-based geometry *module* support (#5253)

This PR adds a (completely optional) mechanism to compile a geometry *module*. This module exposes a C API to construct a tracking geometry and send it to a host program over a shared library boundary opened via `dlopen`.
The host library manages lifetime of the geomerty transparently.

Author: paulgessinger

.github/workflows/builds.yml

@@ -117,8 +117,10 @@ jobs:
       - name: Downstream build
         run: cmake --build build-downstream
 
-      - name: Downstream run
-        run: ./build-downstream/bin/ShowActsVersion
+      - name: Downstream tests
+        run: >
+          CI/dependencies/run.sh .env
+          ctest --test-dir build-downstream --output-on-failure
 
   linux_examples_test:
     runs-on: ubuntu-latest
@@ -318,8 +320,8 @@ jobs:
       - name: Downstream build
         run: cmake --build build-downstream
 
-      - name: Downstream run
-        run: ./build-downstream/bin/ShowActsVersion
+      - name: Downstream tests
+        run: ctest --test-dir build-downstream --output-on-failure
 
   macos:
     runs-on: macos-26
@@ -406,8 +408,8 @@ jobs:
       - name: Downstream build
         run: cmake --build build-downstream
 
-      - name: Downstream run
-        run: ./build-downstream/bin/ShowActsVersion
+      - name: Downstream tests
+        run: ctest --test-dir build-downstream --output-on-failure
 
   external_eic-shell:
     runs-on: ubuntu-latest

.gitlab-ci.yml

@@ -253,8 +253,8 @@ build_linux_ubuntu:
     # Downstream build
     - cmake --build build-downstream
 
-    # Downstream run
-    - ./build-downstream/bin/ShowActsVersion
+    # Downstream tests
+    - ctest --test-dir build-downstream --output-on-failure
 
   after_script:
    - !reference [.spack_cleanup, after_script]
@@ -369,8 +369,8 @@ linux_physmon:
     # Downstream build
     - cmake --build build-downstream
 
-    # Downstream run
-    - ./build-downstream/bin/ShowActsVersion
+    # Downstream tests
+    - ctest --test-dir build-downstream --output-on-failure
 
   after_script:
    - !reference [.spack_cleanup, after_script]

CI/check_unused_files.py

@@ -75,6 +75,8 @@ def main():
         "Core/include/Acts/EventData/detail/ParameterTraits.hpp",
         "Core/include/Acts/Seeding/PathSeeder.hpp",
         "Tests/CommonHelpers/include/ActsTests/CommonHelpers/TestSpacePoint.hpp",
+        "GeometryModule.h",
+        "runtime_geometry_modules.md",
     )
 
     suffix_header = (

Core/CMakeLists.txt

@@ -10,6 +10,16 @@ target_sources(ActsCore PRIVATE src/ActsVersion.cpp)
 
 target_compile_features(ActsCore PUBLIC ${ACTS_CXX_STANDARD_FEATURE})
 
+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
+    "${_acts_geometry_module_abi_tag}"
+    CACHE INTERNAL
+    "ACTS geometry module ABI tag"
+)
+
 target_include_directories(
     ActsCore
     PUBLIC
@@ -19,6 +29,14 @@ target_include_directories(
         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 target_link_libraries(ActsCore PUBLIC Boost::boost Eigen3::Eigen)
+if(CMAKE_DL_LIBS)
+    target_link_libraries(ActsCore PRIVATE ${CMAKE_DL_LIBS})
+endif()
+
+target_compile_definitions(
+    ActsCore
+    PRIVATE ACTS_GEOMETRY_MODULE_ABI_TAG="${_acts_geometry_module_abi_tag}"
+)
 
 if(ACTS_PARAMETER_DEFINITIONS_HEADER)
     target_compile_definitions(

Core/include/Acts/Geometry/GeometryModule.h

@@ -0,0 +1,18 @@
+// 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/.
+
+#pragma once
+
+struct ActsGeometryModuleV1 {
+  const char* module_abi_tag;
+  const char* user_data_type;
+  void* (*build)(const void* user_data, const void* logger);
+  void (*destroy)(void* handle);
+};
+
+extern "C" const ActsGeometryModuleV1* acts_geometry_module_v1(void);

Core/include/Acts/Geometry/GeometryModuleHelper.hpp

@@ -0,0 +1,45 @@
+// 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/.
+
+#pragma once
+
+#include "Acts/Geometry/GeometryModule.h"
+#include "Acts/Geometry/TrackingGeometry.hpp"
+
+#include <memory>
+
+namespace Acts::detail {
+using BuildFunction = std::unique_ptr<TrackingGeometry> (*)(const Logger&);
+const ActsGeometryModuleV1* getGeometryModule(const char* module_abi_tag,
+                                              const char* user_data_type,
+                                              BuildFunction buildFunc);
+// Low-level shared helper: accepts a raw build function pointer matching the
+// C ABI struct's .build field. Handles static struct init and destroy.
+const ActsGeometryModuleV1* getGeometryModuleFromRaw(
+    const char* module_abi_tag, const char* user_data_type,
+    void* (*buildFunc)(const void*, const void*));
+}  // namespace Acts::detail
+
+// Internal — do not use directly.
+#define ACTS_IMPL_GEOMETRY_MODULE_ENTRY(get_module_expr)                 \
+  extern "C" const ActsGeometryModuleV1* acts_geometry_module_v1(void) { \
+    return (get_module_expr);                                            \
+  }
+
+// Emit a clear error only when the macro is actually expanded without the tag,
+// rather than at include time — Acts internal code includes this header too.
+#ifdef ACTS_GEOMETRY_MODULE_ABI_TAG
+#define ACTS_DEFINE_GEOMETRY_MODULE(build_function)                \
+  ACTS_IMPL_GEOMETRY_MODULE_ENTRY(Acts::detail::getGeometryModule( \
+      ACTS_GEOMETRY_MODULE_ABI_TAG, nullptr, (build_function)))
+#else
+#define ACTS_DEFINE_GEOMETRY_MODULE(build_function)                  \
+  static_assert(false,                                               \
+                "ACTS_GEOMETRY_MODULE_ABI_TAG must be provided via " \
+                "CMake (use acts_add_geometry_module).")
+#endif

Core/include/Acts/Geometry/GeometryModuleLoader.hpp

@@ -0,0 +1,47 @@
+// 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/.
+
+#pragma once
+
+#if !defined(__unix__) && !defined(__APPLE__)
+#error \
+    "Runtime geometry modules are only supported on Unix-like systems (Linux, macOS)."
+#endif
+
+#include "Acts/Utilities/Logger.hpp"
+
+#include <filesystem>
+#include <memory>
+
+namespace Acts {
+
+class TrackingGeometry;
+
+/// Load a module shared library, validate ABI compatibility, build and return
+/// 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());
+
+namespace detail {
+/// Low-level loader used by typed wrappers (e.g. loadDD4hepGeometryModule).
+/// Validates that the module's ABI tag matches \a expectedAbiTag.
+/// Validates that the module's user_data_type matches \a expectedUserDataType
+/// (nullptr means the module must declare no user data requirement).
+std::shared_ptr<TrackingGeometry> loadGeometryModuleImpl(
+    const std::filesystem::path& modulePath, const char* expectedAbiTag,
+    const char* expectedUserDataType, const void* userData,
+    const Logger& logger);
+}  // namespace detail
+
+}  // namespace Acts

Core/src/Geometry/CMakeLists.txt

@@ -16,6 +16,8 @@ target_sources(
         GenericApproachDescriptor.cpp
         GenericCuboidVolumeBounds.cpp
         GeometryIdentifier.cpp
+        GeometryModuleHelper.cpp
+        GeometryModuleLoader.cpp
         GlueVolumesDescriptor.cpp
         Layer.cpp
         LayerArrayCreator.cpp

Core/src/Geometry/GeometryModuleHelper.cpp

@@ -0,0 +1,64 @@
+// 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/GeometryModuleHelper.hpp"
+
+#include "Acts/Geometry/GeometryModule.h"
+#include "Acts/Geometry/TrackingGeometry.hpp"
+#include "Acts/Utilities/Logger.hpp"
+
+#include <exception>
+#include <memory>
+
+namespace Acts::detail {
+
+const ActsGeometryModuleV1* getGeometryModuleFromRaw(
+    const char* module_abi_tag, const char* user_data_type,
+    void* (*buildFunc)(const void*, const void*)) {
+  static const ActsGeometryModuleV1 s_module = {
+      .module_abi_tag = module_abi_tag,
+      .user_data_type = user_data_type,
+      .build = buildFunc,
+      .destroy =
+          [](void* handle) noexcept {
+            if (handle == nullptr) {
+              return;
+            }
+
+            delete static_cast<TrackingGeometry*>(handle);
+          },
+  };
+
+  return &s_module;
+}
+
+const ActsGeometryModuleV1* getGeometryModule(const char* module_abi_tag,
+                                              const char* user_data_type,
+                                              BuildFunction buildFunc) {
+  static BuildFunction s_buildFunc = buildFunc;
+
+  return getGeometryModuleFromRaw(
+      module_abi_tag, user_data_type,
+      [](const void* /*userData*/, const void* loggerPtr) noexcept -> void* {
+        if (loggerPtr == nullptr) {
+          return nullptr;
+        }
+        const auto& logger = *static_cast<const Logger*>(loggerPtr);
+        try {
+          return s_buildFunc(logger).release();
+        } catch (const std::exception& e) {
+          ACTS_ERROR("Failed to build geometry module: " << e.what());
+          return nullptr;
+        } catch (...) {
+          ACTS_ERROR("Failed to build geometry module");
+          return nullptr;
+        }
+      });
+}
+
+}  // namespace Acts::detail