feat(sdk): static plugin registry + static dialog for no-dlopen (WASM) builds (#132)

facontidavide · claude · web-flow · commit 6e91268fa7d9 · 2026-06-21T20:23:05.000+02:00
* feat(sdk): static plugin registry for WASM / no-dlopen builds

Add a static-linking path alongside the dlopen one, for Qt-for-WebAssembly
(and any single-binary build) where many plugins are linked into the host:

- PJ_{DATA_SOURCE,TOOLBOX,MESSAGE_PARSER}_PLUGIN, under #ifdef PJ_STATIC_PLUGINS,
  emit a uniquely class-keyed `pj_static_get_*_vtable_&lt;Class&gt;()` instead of the
  fixed `extern "C" PJ_get_*_vtable` symbol (which would collide across plugins
  in one binary). The C-ABI vtable contract is unchanged.
- {DataSource,MessageParser,Toolbox}Library::loadStatic(vtable): wrap a
  statically-linked vtable with a sentinel shared_ptr owner (no DSO), so
  valid()/createHandle() work unchanged.
- PluginRuntimeCatalog::registerStatic{DataSource,MessageParser,Toolbox}(vtable):
  read the embedded manifest JSON and register without a disk scan.
- CMakeLists: append -Wno-error under EMSCRIPTEN (wasm32 size_t is 32-bit).

Pure additions (+243/-0); the dlopen path and desktop behavior are untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* feat(sdk): static PJ_DIALOG_PLUGIN variant (no-collision, WASM)

Under PJ_STATIC_PLUGINS many plugins link into one binary; the fixed
`extern "C" PJ_get_dialog_vtable` symbol (+ the ABI-version export) PJ_DIALOG_PLUGIN
emits would collide across them at link. Emit a uniquely class-keyed
pj_static_get_dialog_vtable_&lt;Class&gt;() instead (keeping the dialogVtableFor&lt;Class&gt;
specialization), completing the static-export pattern the other three family
macros already follow. The static registry resolves dialogs by this getter, not
the dlsym entry point.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* chore(release): bump version to 0.11.0

MINOR: backward-compatible API additions for static (no-dlopen) plugin
linking — the static plugin registry + static dialog variant used by the
Qt-for-WebAssembly build. All already-built plugins keep working unchanged.

Also normalize clang-format (backslash-continuation alignment) on the
static-plugin macro headers.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;

* refactor(sdk): collapse the three registerStatic* bodies into one helper

registerStaticDataSource/MessageParser/Toolbox were near-verbatim copies
differing only in library type, runtime struct, family label, and the one
family-specific field. Extract a `registerStaticPlugin&lt;&gt;` helper that does the
shared load-static + parse-manifest + fill-common-fields + push body; each
method now passes only the family-specific fill lambda. No behavior change.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -35,6 +35,13 @@ else()
     -Wall -Wextra -Werror -Wshadow -Wnon-virtual-dtor -Wold-style-cast
     -Wcast-qual -Wconversion -Woverloaded-virtual -Wpedantic
   )
+  # On wasm32 size_t is 32-bit, so many uint64_t->size_t conversions trip
+  # -Wshorten-64-to-32 / -Wsign-conversion that never fire on 64-bit desktop
+  # (see SUSTAINABILITY.md T0-3). Keep the warnings visible but don't fail the
+  # build for the WASM prototype. TODO: make the ABI/size types 32-bit-clean.
+  if(EMSCRIPTEN)
+    list(APPEND PJ_WARNING_FLAGS -Wno-error)
+  endif()
 endif()
 
 # ---------------------------------------------------------------------------
@@ -111,7 +118,7 @@ endif()
 if(PJ_INSTALL_SDK)
   include(CMakePackageConfigHelpers)
 
-  set(PJ_PACKAGE_VERSION "0.10.0")
+  set(PJ_PACKAGE_VERSION "0.11.0")
   set(PJ_PACKAGE_CMAKE_DIR ${CMAKE_INSTALL_LIBDIR}/cmake/plotjuggler_sdk)
 
   install(EXPORT plotjuggler_sdkTargets
diff --git a/conanfile.py b/conanfile.py
@@ -6,7 +6,7 @@
   plugin_sdk   — umbrella for plugin authors (base + dialog SDK + parser SDK)
   plugin_host  — umbrella for host loaders (data_source/parser/toolbox/dialog)
 
-A consuming Conan recipe declares e.g. `plotjuggler_sdk/0.10.0` and then:
+A consuming Conan recipe declares e.g. `plotjuggler_sdk/0.11.0` and then:
 
     find_package(plotjuggler_sdk REQUIRED COMPONENTS plugin_sdk)
     target_link_libraries(my_plugin PRIVATE plotjuggler_sdk::plugin_sdk)
@@ -30,7 +30,7 @@
 
 class PlotjugglerSdkConan(ConanFile):
     name = "plotjuggler_sdk"
-    version = "0.10.0"
+    version = "0.11.0"
     # Apache-2.0 covers the whole SDK (pj_base + pj_plugins). See LICENSE.
     license = "Apache-2.0"
     url = "https://github.com/PlotJuggler/plotjuggler_sdk"
diff --git a/pj_base/include/pj_base/sdk/data_source_plugin_base.hpp b/pj_base/include/pj_base/sdk/data_source_plugin_base.hpp
@@ -250,3 +250,26 @@ class DataSourcePluginBase {
         manifest);                                                                                       \
     return vt;                                                                                           \
   }
+
+// --- Static-link variant (WASM / no dlopen) ----------------------------------
+// With PJ_STATIC_PLUGINS the plugin is linked into the host binary. The fixed
+// `extern "C" PJ_get_data_source_vtable` symbol would collide across plugins in
+// one binary, so emit a uniquely-named (class-keyed) C++ function instead. The
+// host's static registry declares these extern and passes them to
+// PluginRuntimeCatalog::registerStaticDataSource().
+#ifdef PJ_STATIC_PLUGINS
+#undef PJ_DATA_SOURCE_PLUGIN
+#define PJ_DATA_SOURCE_PLUGIN(ClassName, manifest)                                         \
+  const PJ_data_source_vtable_t* pj_static_get_data_source_vtable_##ClassName() noexcept { \
+    static const PJ_data_source_vtable_t* vt = PJ::DataSourcePluginBase::vtableWithCreate( \
+        []() noexcept -> void* {                                                           \
+          try {                                                                            \
+            return new ClassName();                                                        \
+          } catch (...) {                                                                  \
+            return nullptr;                                                                \
+          }                                                                                \
+        },                                                                                 \
+        manifest);                                                                         \
+    return vt;                                                                             \
+  }
+#endif
diff --git a/pj_base/include/pj_base/sdk/toolbox_plugin_base.hpp b/pj_base/include/pj_base/sdk/toolbox_plugin_base.hpp
@@ -250,3 +250,21 @@ class ToolboxPluginBase {
         manifest);                                                                           \
     return vt;                                                                               \
   }
+
+// --- Static-link variant (WASM / no dlopen) ---  see data_source_plugin_base.hpp
+#ifdef PJ_STATIC_PLUGINS
+#undef PJ_TOOLBOX_PLUGIN
+#define PJ_TOOLBOX_PLUGIN(ClassName, manifest)                                      \
+  const PJ_toolbox_vtable_t* pj_static_get_toolbox_vtable_##ClassName() noexcept {  \
+    static const PJ_toolbox_vtable_t* vt = PJ::ToolboxPluginBase::vtableWithCreate( \
+        []() noexcept -> void* {                                                    \
+          try {                                                                     \
+            return new ClassName();                                                 \
+          } catch (...) {                                                           \
+            return nullptr;                                                         \
+          }                                                                         \
+        },                                                                          \
+        manifest);                                                                  \
+    return vt;                                                                      \
+  }
+#endif
diff --git a/pj_plugins/dialog_protocol/include/pj_plugins/sdk/dialog_plugin_base.hpp b/pj_plugins/dialog_protocol/include/pj_plugins/sdk/dialog_plugin_base.hpp
@@ -303,3 +303,33 @@ PJ_borrowed_dialog_t borrowDialog(DialogT& dialog) noexcept {
     return PJ_get_dialog_vtable();                                                          \
   }                                                                                         \
   }
+
+// --- Static-link variant (WASM / no dlopen) ---  see data_source_plugin_base.hpp.
+// Many statically-linked plugins each carry a PJ_DIALOG_PLUGIN, so the fixed
+// `extern "C" PJ_get_dialog_vtable` symbol (and the ABI-version export) would
+// collide at link. The static registry never resolves a dialog via dlsym (the
+// host short-circuits the dialog path on WASM), so emit only a uniquely
+// class-keyed getter — kept so dialogVtableFor<ClassName>() still resolves for
+// any in-binary caller.
+#ifdef PJ_STATIC_PLUGINS
+#undef PJ_DIALOG_PLUGIN_WITH_MANIFEST
+#define PJ_DIALOG_PLUGIN_WITH_MANIFEST(ClassName, ManifestJson)                             \
+  inline const PJ_dialog_vtable_t* pj_static_get_dialog_vtable_##ClassName() noexcept {     \
+    static const PJ_dialog_vtable_t* vt = PJ::DialogPluginBase::vtableWithCreate(           \
+        []() noexcept -> void* {                                                            \
+          try {                                                                             \
+            return static_cast<PJ::DialogPluginBase*>(new ClassName());                     \
+          } catch (...) {                                                                   \
+            return nullptr;                                                                 \
+          }                                                                                 \
+        },                                                                                  \
+        ManifestJson);                                                                      \
+    return vt;                                                                              \
+  }                                                                                         \
+  namespace PJ {                                                                            \
+  template <>                                                                               \
+  [[maybe_unused]] inline const PJ_dialog_vtable_t* dialogVtableFor<ClassName>() noexcept { \
+    return pj_static_get_dialog_vtable_##ClassName();                                       \
+  }                                                                                         \
+  }
+#endif  // PJ_STATIC_PLUGINS
diff --git a/pj_plugins/include/pj_plugins/host/data_source_library.hpp b/pj_plugins/include/pj_plugins/host/data_source_library.hpp
@@ -51,6 +51,10 @@ class DataSourceLibrary {
   /// Load a plugin from @p path. Returns an error string on failure.
   [[nodiscard]] static Expected<DataSourceLibrary> load(std::string_view path);
 
+  /// Wrap a statically-linked plugin vtable (no dlopen; for WASM/static builds).
+  /// @p vtable must have static storage duration (valid for the program lifetime).
+  [[nodiscard]] static Expected<DataSourceLibrary> loadStatic(const PJ_data_source_vtable_t* vtable);
+
   /// True if the library was loaded and the vtable resolved successfully.
   [[nodiscard]] bool valid() const {
     return handle_ != nullptr && vtable_ != nullptr;
diff --git a/pj_plugins/include/pj_plugins/host/message_parser_library.hpp b/pj_plugins/include/pj_plugins/host/message_parser_library.hpp
@@ -51,6 +51,10 @@ class MessageParserLibrary {
   /// Load a plugin from @p path. Returns an error string on failure.
   [[nodiscard]] static Expected<MessageParserLibrary> load(std::string_view path);
 
+  /// Wrap a statically-linked plugin vtable (no dlopen; for WASM/static builds).
+  /// @p vtable must have static storage duration (valid for the program lifetime).
+  [[nodiscard]] static Expected<MessageParserLibrary> loadStatic(const PJ_message_parser_vtable_t* vtable);
+
   /// True if the library was loaded and the vtable resolved successfully.
   [[nodiscard]] bool valid() const {
     return handle_ != nullptr && vtable_ != nullptr;
diff --git a/pj_plugins/include/pj_plugins/host/plugin_runtime_catalog.hpp b/pj_plugins/include/pj_plugins/host/plugin_runtime_catalog.hpp
@@ -81,6 +81,14 @@ class PluginRuntimeCatalog {
   // Reconciles loaded state with disk and returns true if it changed.
   [[nodiscard]] bool reload();
 
+  // --- Static plugin registration (WASM/static builds; no dlopen) -------------
+  // Register a statically-linked plugin by its vtable. The vtable must outlive
+  // this catalog (static storage duration); the manifest is read from
+  // vtable->manifest_json. Returns false (and reports a diagnostic) on failure.
+  bool registerStaticDataSource(const PJ_data_source_vtable_t* vtable);
+  bool registerStaticMessageParser(const PJ_message_parser_vtable_t* vtable);
+  bool registerStaticToolbox(const PJ_toolbox_vtable_t* vtable);
+
   // Returns loaded DataSource plugins.
   [[nodiscard]] const std::vector<RuntimeDataSourcePlugin>& dataSources() const {
     return data_sources_;
diff --git a/pj_plugins/include/pj_plugins/host/toolbox_library.hpp b/pj_plugins/include/pj_plugins/host/toolbox_library.hpp
@@ -51,6 +51,10 @@ class ToolboxLibrary {
   /// Load a plugin from @p path. Returns an error string on failure.
   [[nodiscard]] static Expected<ToolboxLibrary> load(std::string_view path);
 
+  /// Wrap a statically-linked plugin vtable (no dlopen; for WASM/static builds).
+  /// @p vtable must have static storage duration (valid for the program lifetime).
+  [[nodiscard]] static Expected<ToolboxLibrary> loadStatic(const PJ_toolbox_vtable_t* vtable);
+
   /// True if the library was loaded and the vtable resolved successfully.
   [[nodiscard]] bool valid() const {
     return handle_ != nullptr && vtable_ != nullptr;
diff --git a/pj_plugins/include/pj_plugins/sdk/message_parser_plugin_base.hpp b/pj_plugins/include/pj_plugins/sdk/message_parser_plugin_base.hpp
@@ -376,3 +376,21 @@ class MessageParserPluginBase {
         manifest);                                                                                                \
     return vt;                                                                                                    \
   }
+
+// --- Static-link variant (WASM / no dlopen) ---  see data_source_plugin_base.hpp
+#ifdef PJ_STATIC_PLUGINS
+#undef PJ_MESSAGE_PARSER_PLUGIN
+#define PJ_MESSAGE_PARSER_PLUGIN(ClassName, manifest)                                            \
+  const PJ_message_parser_vtable_t* pj_static_get_message_parser_vtable_##ClassName() noexcept { \
+    static const PJ_message_parser_vtable_t* vt = PJ::MessageParserPluginBase::vtableWithCreate( \
+        []() noexcept -> void* {                                                                 \
+          try {                                                                                  \
+            return new ClassName();                                                              \
+          } catch (...) {                                                                        \
+            return nullptr;                                                                      \
+          }                                                                                      \
+        },                                                                                       \
+        manifest);                                                                               \
+    return vt;                                                                                   \
+  }
+#endif
diff --git a/pj_plugins/src/data_source_library.cpp b/pj_plugins/src/data_source_library.cpp
@@ -70,6 +70,26 @@ Expected<DataSourceLibrary> DataSourceLibrary::load(std::string_view path) {
   return DataSourceLibrary(std::move(handle), vtable, std::string(path));
 }
 
+Expected<DataSourceLibrary> DataSourceLibrary::loadStatic(const PJ_data_source_vtable_t* vtable) {
+  if (vtable == nullptr) {
+    return unexpected("static DataSource vtable is null");
+  }
+  if (vtable->protocol_version != PJ_DATA_SOURCE_PROTOCOL_VERSION) {
+    return unexpected("DataSource protocol version mismatch");
+  }
+  if (vtable->struct_size < PJ_DATA_SOURCE_MIN_VTABLE_SIZE) {
+    return unexpected("DataSource vtable smaller than v4.0 baseline");
+  }
+  if (auto status = detail::validateRequiredSlots(vtable); !status) {
+    return unexpected(status.error());
+  }
+  // Statically linked: no DSO to keep alive, but valid()/createHandle() expect a
+  // non-null owner. Use a sentinel shared_ptr with a no-op deleter.
+  static char anchor = 0;
+  std::shared_ptr<void> handle(&anchor, [](void*) {});
+  return DataSourceLibrary(std::move(handle), vtable, "static://");
+}
+
 Expected<const PJ_dialog_vtable_t*> DataSourceLibrary::resolveDialogVtable() const {
   auto sym = detail::resolveSymbol(handle_.get(), "PJ_get_dialog_vtable");
   if (!sym) {
diff --git a/pj_plugins/src/message_parser_library.cpp b/pj_plugins/src/message_parser_library.cpp
@@ -68,6 +68,24 @@ Expected<MessageParserLibrary> MessageParserLibrary::load(std::string_view path)
   return MessageParserLibrary(std::move(handle), vtable, std::string(path));
 }
 
+Expected<MessageParserLibrary> MessageParserLibrary::loadStatic(const PJ_message_parser_vtable_t* vtable) {
+  if (vtable == nullptr) {
+    return unexpected("static MessageParser vtable is null");
+  }
+  if (vtable->protocol_version != PJ_MESSAGE_PARSER_PROTOCOL_VERSION) {
+    return unexpected("MessageParser protocol version mismatch");
+  }
+  if (vtable->struct_size < PJ_MESSAGE_PARSER_MIN_VTABLE_SIZE) {
+    return unexpected("MessageParser vtable smaller than v4.0 baseline");
+  }
+  if (auto status = detail::validateRequiredSlots(vtable); !status) {
+    return unexpected(status.error());
+  }
+  static char anchor = 0;
+  std::shared_ptr<void> handle(&anchor, [](void*) {});
+  return MessageParserLibrary(std::move(handle), vtable, "static://");
+}
+
 Expected<const PJ_dialog_vtable_t*> MessageParserLibrary::resolveDialogVtable() const {
   auto sym = detail::resolveSymbol(handle_.get(), "PJ_get_dialog_vtable");
   if (!sym) {
diff --git a/pj_plugins/src/plugin_runtime_catalog.cpp b/pj_plugins/src/plugin_runtime_catalog.cpp
@@ -150,6 +150,92 @@ bool PluginRuntimeCatalog::reload() {
   return changed;
 }
 
+namespace {
+
+// Parse a plugin's embedded manifest JSON. Returns false on invalid JSON.
+bool parseStaticManifest(const char* manifest_json, nlohmann::json& out) {
+  try {
+    out = nlohmann::json::parse(manifest_json ? manifest_json : "");
+    return out.is_object();
+  } catch (const std::exception&) {
+    return false;
+  }
+}
+
+std::vector<std::string> readManifestStringArray(const nlohmann::json& j, const char* key) {
+  std::vector<std::string> values;
+  if (auto it = j.find(key); it != j.end() && it->is_array()) {
+    for (const auto& v : *it) {
+      if (v.is_string()) {
+        values.push_back(v.get<std::string>());
+      }
+    }
+  }
+  return values;
+}
+
+// Shared body for the three registerStatic* methods: load the static vtable,
+// parse the embedded manifest, fill the common Runtime*Plugin fields, and push.
+// `fill` adds the family-specific fields (capabilities / extensions / encodings);
+// `report` bridges to the catalog's private diagnostic sink.
+template <typename LibraryT, typename RuntimeT, typename ReportFn, typename FillFn>
+bool registerStaticPlugin(
+    const auto* vtable, std::vector<RuntimeT>& out, const char* family, const ReportFn& report, const FillFn& fill) {
+  auto result = LibraryT::loadStatic(vtable);
+  if (!result) {
+    report(DiagnosticLevel::kError, std::string{}, "static " + std::string(family) + ": " + result.error());
+    return false;
+  }
+  nlohmann::json j;
+  if (!parseStaticManifest(vtable->manifest_json, j)) {
+    report(DiagnosticLevel::kError, std::string{}, "static " + std::string(family) + ": invalid manifest JSON");
+    return false;
+  }
+  RuntimeT loaded;
+  loaded.library = std::move(*result);
+  loaded.id = j.value("id", std::string{});
+  loaded.name = j.value("name", std::string{});
+  loaded.version = j.value("version", std::string{});
+  loaded.path = "static://" + loaded.id;
+  loaded.loaded_mtime = std::filesystem::file_time_type{};
+  fill(loaded, j);
+  report(DiagnosticLevel::kInfo, loaded.id, "Registered static " + std::string(family) + " " + loaded.name);
+  out.push_back(std::move(loaded));
+  return true;
+}
+
+}  // namespace
+
+bool PluginRuntimeCatalog::registerStaticDataSource(const PJ_data_source_vtable_t* vtable) {
+  return registerStaticPlugin<DataSourceLibrary>(
+      vtable, data_sources_, "DataSource",
+      [this](DiagnosticLevel level, const std::string& id, std::string msg) { report(level, id, std::move(msg)); },
+      [](RuntimeDataSourcePlugin& loaded, const nlohmann::json& j) {
+        loaded.capabilities = loaded.library.createHandle().capabilities();
+        for (auto& ext : readManifestStringArray(j, "file_extensions")) {
+          loaded.file_extensions.push_back(normalizeExtension(std::move(ext)));
+        }
+      });
+}
+
+bool PluginRuntimeCatalog::registerStaticMessageParser(const PJ_message_parser_vtable_t* vtable) {
+  return registerStaticPlugin<MessageParserLibrary>(
+      vtable, message_parsers_, "MessageParser",
+      [this](DiagnosticLevel level, const std::string& id, std::string msg) { report(level, id, std::move(msg)); },
+      [](RuntimeMessageParserPlugin& loaded, const nlohmann::json& j) {
+        loaded.encodings = readManifestStringArray(j, "encoding");
+      });
+}
+
+bool PluginRuntimeCatalog::registerStaticToolbox(const PJ_toolbox_vtable_t* vtable) {
+  return registerStaticPlugin<ToolboxLibrary>(
+      vtable, toolbox_plugins_, "Toolbox",
+      [this](DiagnosticLevel level, const std::string& id, std::string msg) { report(level, id, std::move(msg)); },
+      [](RuntimeToolboxPlugin& loaded, const nlohmann::json& /*j*/) {
+        loaded.capabilities = loaded.library.createHandle().capabilities();
+      });
+}
+
 bool PluginRuntimeCatalog::loadAndRegister(const PluginDescriptor& descriptor) {
   switch (descriptor.family) {
     case PluginFamily::kDataSource:
diff --git a/pj_plugins/src/toolbox_library.cpp b/pj_plugins/src/toolbox_library.cpp
@@ -67,6 +67,24 @@ Expected<ToolboxLibrary> ToolboxLibrary::load(std::string_view path) {
   return ToolboxLibrary(std::move(handle), vtable, std::string(path));
 }
 
+Expected<ToolboxLibrary> ToolboxLibrary::loadStatic(const PJ_toolbox_vtable_t* vtable) {
+  if (vtable == nullptr) {
+    return unexpected("static Toolbox vtable is null");
+  }
+  if (vtable->protocol_version != PJ_TOOLBOX_PLUGIN_PROTOCOL_VERSION) {
+    return unexpected("Toolbox protocol version mismatch");
+  }
+  if (vtable->struct_size < PJ_TOOLBOX_MIN_VTABLE_SIZE) {
+    return unexpected("Toolbox vtable smaller than v4.0 baseline");
+  }
+  if (auto status = detail::validateRequiredSlots(vtable); !status) {
+    return unexpected(status.error());
+  }
+  static char anchor = 0;
+  std::shared_ptr<void> handle(&anchor, [](void*) {});
+  return ToolboxLibrary(std::move(handle), vtable, "static://");
+}
+
 Expected<const PJ_dialog_vtable_t*> ToolboxLibrary::resolveDialogVtable() const {
   auto sym = detail::resolveSymbol(handle_.get(), "PJ_get_dialog_vtable");
   if (!sym) {
diff --git a/recipe.yaml b/recipe.yaml
@@ -1,7 +1,7 @@
 schema_version: 1
 
 context:
-  version: "0.10.0"
+  version: "0.11.0"
 
 package:
   name: plotjuggler_sdk
