feat(apps): build individual subsystems from build_geometry

README.md

@@ -71,10 +71,22 @@ ctest --test-dir build
 # Build the complete SHiP geometry
 ./build/apps/build_geometry [output_file.db]
 
+# Build a single subsystem on its own
+./build/apps/build_geometry <Name> [output_file.db]
+
+# List the available subsystem names
+./build/apps/build_geometry --list
+
 # View in gmex
 gmex output_file.db
 ```
 
+With no subsystem named, the complete detector is built. Naming a subsystem
+(as spelled by `--list`, e.g. `Calorimeter`) builds just that subsystem in its
+own local frame. A token ending in `.db` is taken as the output file; the
+default is `ship_geometry.db` for the full build, or `<Name>.db` for a single
+subsystem.
+
 ### Installing
 
 ```bash
@@ -96,20 +108,39 @@ GeoModelTools automatically.
 
 ### Factory Pattern
 
-Each subsystem is implemented as a factory class:
+Each subsystem is a self-contained factory class that builds its geometry,
+describes where it belongs, and registers itself:
 
 ```cpp
 class FooFactory {
 public:
     explicit FooFactory(SHiPMaterials& materials);
     GeoPhysVol* build();
+
+    // Self-description consumed by the assembler:
+    // name, tree node, id, placement (x/y/z mm), and whether it is the world.
+    static SubsystemDescriptor descriptor() {
+        return {"Foo", "/SHiP/foo", 42, 0.0, 0.0, 12345.0, /*isWorld=*/false};
+    }
 private:
     SHiPMaterials& m_materials;
 };
 ```
 
-`SHiPGeometryBuilder::build()` orchestrates all factories, creating the world
-volume (Cavern) and placing each subsystem at its global z-position.
+with a single registration line in the factory's `.cpp` (inside
+`namespace SHiPGeometry`):
+
+```cpp
+REGISTER_SUBSYSTEM(FooFactory)
+```
+
+The assembler names no subsystem. `assembleGeometry()` — also reachable via
+the unchanged `SHiPGeometryBuilder::build()` — iterates the registry, builds
+the world (the subsystem whose descriptor sets `isWorld`, i.e. the Cavern),
+and places every other registered subsystem at its declared position, ordered
+by `(z, id)`. A single subsystem can be built on its own, in its local frame,
+with `buildSubsystem("Foo")`. The registry, descriptor type, and macro live in
+`include/SHiPGeometry/SubsystemRegistry.h`.
 
 ### Materials
 
@@ -128,21 +159,27 @@ To add a new material, edit `src/SHiPMaterials.cpp`:
 ## Adding or Modifying a Subsystem
 
 1. **Header**: `subsystems/<Name>/include/<Name>/<Name>Factory.h` — declare
-   the factory class with dimension constants as `static constexpr` members
+   the factory class with dimension constants as `static constexpr` members,
+   plus `static SubsystemDescriptor descriptor()` returning its name, tree
+   node, id, and placement
 2. **Implementation**: `subsystems/<Name>/src/<Name>Factory.cpp` — implement
    `build()` using GeoModel primitives (`GeoBox`, `GeoTubs`, `GeoLogVol`,
    `GeoPhysVol`, `GeoTransform`, etc.)
-3. **Registration**: add a `build()` + placement call in
-   `src/SHiPGeometry.cpp` (`SHiPGeometryBuilder::build()`)
-4. **CMake**: add sources/headers to `subsystems/<Name>/CMakeLists.txt`
+3. **Registration**: add one line — `REGISTER_SUBSYSTEM(<Name>Factory)` — at
+   the end of the factory `.cpp`, inside `namespace SHiPGeometry`. The
+   subsystem registers itself; **do not** edit `src/SHiPGeometry.cpp`, which
+   names no subsystem.
+4. **CMake**: add sources/headers to `subsystems/<Name>/CMakeLists.txt`, and
+   add the new library to the `--whole-archive` block in `src/CMakeLists.txt`
+   so its self-registration initializer is not dropped by the linker
 5. **Docs**: update the subsystem `README.md` with geometry tree, materials,
    and status
 
 ## Structure
 
 ```
 geometry/
-├── include/SHiPGeometry/   # Public headers (SHiPGeometry, SHiPMaterials)
+├── include/SHiPGeometry/   # Public headers (SHiPGeometry, SHiPMaterials, SubsystemRegistry)
 ├── src/                     # Core implementation
 ├── subsystems/              # Detector subsystem factories
 │   ├── Cavern/

apps/build_geometry.cpp

@@ -1,47 +1,97 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 // Copyright (C) CERN for the benefit of the SHiP Collaboration
+//
+// Build the SHiP GeoModel geometry and serialise it to a GeoModel SQLite (.db).
+//
+// Usage:
+//   build_geometry                     # full detector          -> ship_geometry.db
+//   build_geometry out.db              # full detector          -> out.db
+//   build_geometry Calorimeter         # just that subsystem    -> Calorimeter.db
+//   build_geometry Calorimeter c.db    # just that subsystem    -> c.db
+//   build_geometry --list              # list available subsystems
+//
+// A token ending in ".db" is the output file; any other token names a
+// subsystem. With no subsystem named, the complete detector is built.
 
 #include "SHiPGeometry/SHiPGeometry.h"
+#include "SHiPGeometry/SubsystemRegistry.h"
 
 #include <GeoModelDBManager/GMDBManager.h>
 #include <GeoModelKernel/GeoPhysVol.h>
 #include <GeoModelWrite/WriteGeoModel.h>
 
 #include <filesystem>
 #include <iostream>
+#include <string>
+#include <vector>
+
+namespace {
+bool endsWith(const std::string& s, const std::string& suffix) {
+    return s.size() >= suffix.size() &&
+           s.compare(s.size() - suffix.size(), suffix.size(), suffix) == 0;
+}
+}  // namespace
 
 int main(int argc, char* argv[]) {
-    std::string outputFile = "ship_geometry.db";
-    if (argc > 1) {
-        outputFile = argv[1];
+    std::string outputFile;
+    std::vector<std::string> names;  // requested subsystem(s)
+
+    for (int i = 1; i < argc; ++i) {
+        const std::string arg = argv[i];
+        if (arg == "--list") {
+            for (const auto& n : SHiPGeometry::subsystemNames())
+                std::cout << n << "\n";
+            return 0;
+        }
+        if (endsWith(arg, ".db")) {
+            outputFile = arg;
+        } else {
+            names.push_back(arg);
+        }
     }
 
-    std::cout << "Building SHiP geometry..." << std::endl;
+    GeoVPhysVol* geometry = nullptr;
+    std::string label;
 
-    SHiPGeometry::SHiPGeometryBuilder builder;
-    GeoPhysVol* world = builder.build();
+    if (names.empty()) {
+        // Default: the complete detector (unchanged behaviour).
+        SHiPGeometry::SHiPGeometryBuilder builder;
+        geometry = builder.build();
+        label = "full SHiP geometry";
+        if (outputFile.empty())
+            outputFile = "ship_geometry.db";
+    } else if (names.size() == 1) {
+        // A single subsystem, on its own (local frame).
+        try {
+            geometry = SHiPGeometry::buildSubsystem(names[0]);
+        } catch (const std::exception& e) {
+            std::cerr << "Error: " << e.what() << "\nAvailable subsystems:\n";
+            for (const auto& n : SHiPGeometry::subsystemNames())
+                std::cerr << "  " << n << "\n";
+            return 1;
+        }
+        label = names[0];
+        if (outputFile.empty())
+            outputFile = names[0] + ".db";
+    } else {
+        std::cerr << "Error: build at most one subsystem at a time (got " << names.size() << ").\n";
+        return 1;
+    }
 
-    if (!world) {
-        std::cerr << "Error: Geometry not yet implemented" << std::endl;
+    if (!geometry) {
+        std::cerr << "Error: geometry is null (not yet implemented?)." << std::endl;
         return 1;
     }
 
-    // Remove existing output file
     if (std::filesystem::exists(outputFile)) {
         std::filesystem::remove(outputFile);
     }
 
-    std::cout << "Writing geometry to " << outputFile << std::endl;
-
+    std::cout << "Writing " << label << " to " << outputFile << std::endl;
     GMDBManager db(outputFile);
     GeoModelIO::WriteGeoModel writer(db);
-
-    // Traverse the geometry tree
-    world->exec(&writer);
-
-    // Save to database
+    geometry->exec(&writer);
     writer.saveToDB();
-
     std::cout << "Done." << std::endl;
     return 0;
 }

include/SHiPGeometry/SubsystemRegistry.h

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (C) CERN for the benefit of the SHiP Collaboration
+
+#pragma once
+
+#include <GeoModelKernel/GeoPhysVol.h>  // complete GeoPhysVol/GeoVPhysVol for the macro's upcast
+
+#include <cstdio>
+#include <cstdlib>
+#include <functional>
+#include <map>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace SHiPGeometry {
+
+class SHiPMaterials;
+
+/**
+ * @brief A subsystem's self-description: everything the assembler needs.
+ *
+ * This is the "required input to the geometry builder" that each subsystem
+ * yields about itself. It is a plain data type (no GeoModel dependency).
+ * Translations are in millimetres from the world origin.
+ */
+struct SubsystemDescriptor {
+    const char* name;      ///< registry key / CLI name, e.g. "Calorimeter"
+    const char* node;      ///< GeoNameTag, e.g. "/SHiP/calorimeter"
+    int id;                ///< GeoIdentifierTag
+    double x_mm;           ///< placement translation X (mm)
+    double y_mm;           ///< placement translation Y (mm)
+    double z_mm;           ///< placement translation Z, beam direction (mm)
+    bool isWorld = false;  ///< true for the mother/world volume (the cavern)
+};
+
+/// A registered subsystem: its descriptor plus how to build it (local frame).
+struct SubsystemInfo {
+    SubsystemDescriptor desc;
+    std::function<GeoVPhysVol*(SHiPMaterials&)> build;
+};
+
+/**
+ * @brief The global subsystem registry.
+ *
+ * A Meyers singleton (function-local static in an inline function) so it is
+ * a single shared instance across all translation units and is guaranteed to
+ * exist before any static registration runs. No file names any subsystem;
+ * subsystems add themselves via REGISTER_SUBSYSTEM.
+ */
+inline std::map<std::string, SubsystemInfo>& registry() {
+    static std::map<std::string, SubsystemInfo> instance;
+    return instance;
+}
+
+/// Add a subsystem to the registry. Returns true (usable as a static
+/// initialiser). A duplicate name is a programming error (two subsystems
+/// declaring the same descriptor name): it is reported and aborts, rather
+/// than being silently dropped by emplace(). Runs at static-init, so this
+/// diagnoses to stderr and aborts instead of throwing.
+inline bool registerSubsystem(const SubsystemDescriptor& desc,
+                              std::function<GeoVPhysVol*(SHiPMaterials&)> build) {
+    const auto result = registry().emplace(desc.name, SubsystemInfo{desc, std::move(build)});
+    if (!result.second) {
+        std::fprintf(stderr,
+                     "SHiPGeometry: duplicate subsystem name '%s' registered; "
+                     "each subsystem's descriptor() must return a unique name.\n",
+                     desc.name);
+        std::abort();
+    }
+    return true;
+}
+
+// ── Generic consumers — these name no subsystem ─────────────────────────────
+
+/// Assemble the world plus a selection of subsystems (empty selection = all),
+/// each placed at its own declared position. Returns the world volume.
+GeoPhysVol* assembleGeometry(const std::vector<std::string>& only = {});
+
+/// Build a single subsystem on its own, in its local frame (no world, no
+/// placement). Throws std::runtime_error if the name is not registered.
+GeoVPhysVol* buildSubsystem(const std::string& name);
+
+/// The names of all registered subsystems (including the world), sorted.
+std::vector<std::string> subsystemNames();
+
+}  // namespace SHiPGeometry
+
+/**
+ * @brief Register a subsystem factory with the global registry.
+ *
+ * Placed once in each subsystem's own .cpp (inside namespace SHiPGeometry).
+ * The factory must expose `static SubsystemDescriptor descriptor()` and be
+ * constructible from `SHiPMaterials&` with a `build()` returning a volume.
+ *
+ * NOTE: nothing references this registration, so the subsystem library would
+ * otherwise be dropped from a consumer's DT_NEEDED by the toolchain's default
+ * --as-needed and the initialiser would never run. src/CMakeLists.txt applies
+ * -Wl,--no-as-needed as an INTERFACE link option on SHiPGeometry so the flag
+ * lands on each executable's link line. Do not remove it.
+ */
+#define REGISTER_SUBSYSTEM(FACTORY)                                                             \
+    namespace {                                                                                 \
+    const bool FACTORY##_registered = ::SHiPGeometry::registerSubsystem(                        \
+        FACTORY::descriptor(), [](::SHiPGeometry::SHiPMaterials& materials) -> ::GeoVPhysVol* { \
+            return FACTORY(materials).build();                                                  \
+        });                                                                                     \
+    }

src/CMakeLists.txt

@@ -1,16 +1,13 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) CERN for the benefit of the SHiP Collaboration
 
-# Create SHiPGeometry library
 add_library(SHiPGeometry SHiPMaterials.cpp SHiPGeometry.cpp)
-
 target_include_directories(
     SHiPGeometry
     PUBLIC
         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
         $<INSTALL_INTERFACE:include>
 )
-
 target_link_libraries(
     SHiPGeometry
     PUBLIC
@@ -28,3 +25,14 @@ target_link_libraries(
         TimingDetector
         Calorimeter
 )
+
+# The subsystems are referenced only through their REGISTER_SUBSYSTEM static
+# initialisers, so the toolchain's default --as-needed drops them from the
+# DT_NEEDED of every executable that links SHiPGeometry, and their
+# registrations never run. INTERFACE puts --no-as-needed on the *consumer's*
+# link line, which is where the entries were being dropped.
+target_link_options(SHiPGeometry INTERFACE "-Wl,--no-as-needed")
+
+if(UNIX AND NOT APPLE)
+    target_link_options(SHiPGeometry INTERFACE "-Wl,--no-as-needed")
+endif()