Pre-parse plugin options hook for dynamic plugin option registration

maureeungaro · maureeungaro · commit 2536e091ec78 · 2026-06-09T09:33:57.000-04:00
diff --git a/gemc.cc b/gemc.cc
@@ -24,7 +24,9 @@
 
 int main(int argc, char* argv[]) {
 
-	auto gopts = std::make_shared<GOptions>(argc, argv, gemc::defineOptions());
+	auto base_schema = gemc::defineOptions();
+	base_schema += gemc::collectPluginOptions(argc, argv);
+	auto gopts = std::make_shared<GOptions>(argc, argv, base_schema);
 	auto log   = std::make_shared<GLogger>(gopts, SFUNCTION_NAME, GENERAL_LOGGER);
 
 	auto gui      = gopts->getSwitch("gui");
diff --git a/gemc_options.cc b/gemc_options.cc
@@ -3,6 +3,17 @@
 #include "gemc_options.h"
 #include "gemcConventions.h"
 
+// yaml-cpp — needed by collectPluginOptions for the bootstrap YAML scan
+#include "yaml-cpp/yaml.h"
+
+// POSIX dynamic loading
+#include <dlfcn.h>
+
+// c++
+#include <filesystem>
+#include <set>
+#include <sstream>
+
 // options definitions
 #include "dbselect_options.h"
 #include "gstreamer_options.h"
@@ -83,4 +94,103 @@ namespace gemc {
     }
 
 
+    GOptions collectPluginOptions(int argc, char* argv[]) {
+        GOptions merged;
+
+        // Build the plugin search path from three sources, checked in priority order:
+        //   1. -plugin_path=... on the command line (not yet parsed)
+        //   2. plugin_path: value in any YAML file listed in argv
+        //   3. GEMC_PLUGIN_PATH environment variable
+        // Source 1 is extracted first; source 2 is accumulated while scanning YAML files
+        // below; source 3 is appended after both.
+        std::string search_path;
+        for (int i = 1; i < argc; ++i) {
+            std::string_view arg = argv[i];
+            if (arg.size() > 13 && arg.substr(0, 13) == "-plugin_path=") {
+                const auto val = std::string(arg.substr(13));
+                if (!search_path.empty()) search_path += ':';
+                search_path += val;
+            }
+        }
+
+        // Scan every YAML file present in argv. For each file:
+        //   - collect any plugin_path value declared there
+        //   - collect gsystem names to probe for a definePluginOptions symbol
+        std::set<std::string> seen_names;  // deduplicate across multiple YAML files
+        for (int i = 1; i < argc; ++i) {
+            const std::string arg = argv[i];
+            if (!std::filesystem::exists(arg)) continue;
+
+            YAML::Node root;
+            try { root = YAML::LoadFile(arg); } catch (...) { continue; }
+
+            // Pick up plugin_path declared in this YAML file (prepend so YAML paths
+            // take priority over the env var but not over command-line paths).
+            if (root["plugin_path"]) {
+                try {
+                    const auto yaml_pp = root["plugin_path"].as<std::string>();
+                    if (!yaml_pp.empty()) {
+                        search_path = search_path.empty()
+                                      ? yaml_pp
+                                      : search_path + ':' + yaml_pp;
+                    }
+                } catch (...) {}
+            }
+
+            if (!root["gsystem"]) continue;
+            for (const auto& entry : root["gsystem"]) {
+                if (!entry["name"]) continue;
+                std::string name;
+                try { name = entry["name"].as<std::string>(); } catch (...) { continue; }
+                if (name.empty() || !seen_names.insert(name).second) continue;
+
+                // Resolve <name>.gplugin using the accumulated search path plus
+                // GEMC_PLUGIN_PATH and, as a last resort, the current directory.
+                std::string full_search = search_path;
+                if (const char* env = std::getenv("GEMC_PLUGIN_PATH")) {
+                    if (!full_search.empty()) full_search += ':';
+                    full_search += env;
+                }
+
+                const std::string basename = name + ".gplugin";
+                std::string       lib_path;
+
+                if (!full_search.empty()) {
+                    std::istringstream ss(full_search);
+                    std::string        dir;
+                    while (std::getline(ss, dir, ':')) {
+                        if (dir.empty()) continue;
+                        const auto candidate = dir + "/" + basename;
+                        if (std::filesystem::exists(candidate)) { lib_path = candidate; break; }
+                    }
+                }
+                if (lib_path.empty() && std::filesystem::exists(basename)) lib_path = basename;
+                if (lib_path.empty()) continue;  // no plugin for this system — normal
+
+                // Open the library. On Linux, RTLD_NODELETE keeps it resident so that the
+                // later GManager dlopen gets the exact same handle without re-executing
+                // static initialisers. On macOS the reference count achieves the same effect.
+#if defined(__linux__) && defined(RTLD_NODELETE)
+                const auto h = dlopen(lib_path.c_str(), RTLD_NOW | RTLD_NODELETE);
+#else
+                const auto h = dlopen(lib_path.c_str(), RTLD_NOW);
+#endif
+                if (!h) continue;  // library not loadable — skip silently
+
+                // The definePluginOptions symbol is optional. Plugins that need no custom
+                // options simply omit it and are silently skipped here.
+                // The symbol returns GOptions* (heap-allocated) so that extern "C" linkage
+                // is not applied to a by-value C++ return type.
+                using opt_fptr = GOptions* (*)();
+                const auto sym = reinterpret_cast<opt_fptr>(dlsym(h, "definePluginOptions"));
+                if (!sym) continue;
+
+                std::unique_ptr<GOptions> plugin_opts(sym());
+                merged += *plugin_opts;
+            }
+        }
+
+        return merged;
+    }
+
 }
diff --git a/gemc_options.h b/gemc_options.h
@@ -9,6 +9,39 @@ namespace gemc {
 
     GOptions defineOptions();
 
+    /**
+     * \brief Scans YAML files in argv for gsystem names and probes each corresponding
+     *        .gplugin for an optional \c definePluginOptions symbol.
+     *
+     * Called before the main GOptions parsing constructor so that plugin-specific
+     * options are registered in the schema and appear in --help, saved config, and
+     * command-line parsing alongside core GEMC options.
+     *
+     * The search path for plugins is assembled from (in priority order):
+     * -# \c -plugin_path=... command-line arguments found in argv
+     * -# \c plugin_path: entries found in YAML files listed in argv
+     * -# the \c GEMC_PLUGIN_PATH environment variable
+     * -# the current working directory
+     *
+     * Failures (missing plugin, missing symbol, bad YAML) are silently skipped;
+     * not every system has a plugin and not every plugin declares custom options.
+     *
+     * \param argc  Argument count from \c main().
+     * \param argv  Argument vector from \c main().
+     * Plugin contract: the symbol must be declared as
+     * \code{.cpp}
+     *   extern "C" GOptions* definePluginOptions();
+     * \endcode
+     * The returned pointer is heap-allocated and owned by the caller (deleted immediately
+     * after merging). Returning a pointer rather than a value avoids the C-linkage /
+     * non-trivial-return-type warning that clang emits for by-value C++ returns across
+     * an \c extern "C" boundary.
+     *
+     * \return A \c GOptions containing only the option schema contributions from plugins.
+     *         Values are not parsed yet; that happens in the main constructor.
+     */
+    GOptions collectPluginOptions(int argc, char* argv[]);
+
 }
 
 
diff --git a/releases/0.3.md b/releases/0.3.md
@@ -9,6 +9,7 @@ This version includes:
 - Volume inspection from the geometry tree
 - Unified `value*unit` notation for `gparticle` kinematic fields
 - `GEMC_PLUGIN_PATH` and `-plugin_path` for external plugin discovery
+- Pre-parse plugin options hook for dynamic plugin option registration
 - ROOT gstreamer and event-action bug fixes
 
 <br/>
@@ -349,3 +350,18 @@ Both x86_64 and ARM64 platforms are supported.
   the fallback warning. The Lund file reader pre-converts its computed doubles
   via `gutilities::getG4Number(value, unit)` before passing them to the
   constructor.
+- Added `gemc::collectPluginOptions(int argc, char* argv[])` declared in `gemc_options.h` and
+  implemented in `gemc_options.cc`. Before the main `GOptions` parsing constructor is called in
+  `main()`, GEMC scans every YAML file listed in `argv` for `gsystem` entries, resolves each
+  `<name>.gplugin` using the plugin search path, and probes for an optional
+  `extern "C" GOptions* definePluginOptions()` symbol. Options declared there are merged into
+  the schema so plugin-specific options appear in `gemc <config>.yaml -h`, are saved to the
+  configuration snapshot, and can be set from the command line or YAML alongside core options.
+  The pre-parse search path honours `-plugin_path=` CLI arguments, `plugin_path:` YAML keys,
+  and the `GEMC_PLUGIN_PATH` environment variable in that priority order. On Linux,
+  `RTLD_NODELETE` keeps the probed library resident so the later `GManager::dlopen` during
+  detector construction gets the same OS handle without re-executing static initialisers; on
+  macOS, reference counting achieves the same effect. Plugin verbosity keys are registered by
+  passing the channel name to the single-argument `GOptions` constructor inside
+  `definePluginOptions`, adding `verbosity.<plugin>` to the schema independently of the global
+  `gdigitization` verbosity.
diff --git a/releases/dev.md b/releases/dev.md
@@ -1,6 +1,20 @@
 
 ## Commits on main since 2026-05-21
 
+- 2026-06-09 **c5e743b** — fixed field options loading plugin path _(by Maurizio Ungaro)_
+- 2026-06-09 **fde83ef** — utility functions _(by Maurizio Ungaro)_
+- 2026-06-09 **9c8ddec** — documenting processGTouchableModifiersImpl _(by Maurizio Ungaro)_
+- 2026-06-08 **f6ec9c2** — added GEMC_PLUGIN_PATH and fixed case where nullptr for GDigitizedData was not picked up in gEventAction.cc _(by Maurizio Ungaro)_
+- 2026-06-08 **81da0ee** — less aggressive images cleanup and added explicit units in gparticle _(by Maurizio Ungaro)_
+- 2026-06-06 **e0aa4e4** — testing new test deploy and binary workflow _(by Maurizio Ungaro)_
+- 2026-06-06 **5cc9897** — Merge pull request #140 from Jah-yee/main _(by Mauri)_
+- 2026-06-06 **32a25c2** — fix: remove dead birkConstant branch in getMaterialPropertyFromString _(by Jah-yee)_
+- 2026-06-05 **b44333f** — added passive and active g4placements, default to active _(by Maurizio Ungaro)_
+- 2026-06-05 **1f5d536** — gui tweaks and added inspection button _(by Maurizio Ungaro)_
+- 2026-06-05 **096ce27** — replaced view buttons with svg _(by Maurizio Ungaro)_
+- 2026-06-05 **2fb4662** — added color buttons for scale and frame, and cleaned up ui _(by Maurizio Ungaro)_
+- 2026-06-05 **dd4e36f** — added description to gvolume _(by Maurizio Ungaro)_
+- 2026-06-05 **32227f9** — added center and twinkle button _(by Maurizio Ungaro)_
 - 2026-06-05 **ccd929f** — moved g4dialog at the bottom in the src _(by Maurizio Ungaro)_
 - 2026-06-05 **af0bfc3** — moved g4dialog at the bottom _(by Maurizio Ungaro)_
 - 2026-06-05 **686151c** — doxygen style was missing _(by Maurizio Ungaro)_
