plugin — a runtime plugin loader for C++

Overview

The reference manual describes the plugin public API in cppreference-style one-page-per-symbol format. The generated Doxygen tree is the exhaustive machine-produced companion — every signature, every private helper, the class / collaboration / include / call graphs. This manual is the human-written one: same symbols, the why rather than only the what.

The three modules

Module	Header prefix	Namespace	Artefact
catalog & registration	`plugin/`	`plugin::`	header-only (`plugin`)
the loader	`dso/`	`fedem::dso`	`libdsold.so`
signing & trust	`sign/`	`fedem::sign`	`libplugin-sign.a`

#include <plugin/Plugin.hh>          // Plugin<Base>, create(), CATALOG
#include <plugin/PluginRegister.hh>  // REGISTER, REGISTER_WITH_CONFIG, ...
#include <plugin/PluginCatalog.hh>   // PluginCatalog<Base>, CREATECATALOG
#include <dso/DSOLoader.hh>          // fedem::dso::DSOLoader
#include <dso/DSOExceptions.hh>      // fedem::exception::FileNotFound, SignatureRejected
#include <sign/Verifier.hh>          // fedem::sign::Verifier, VerifyResult
#include <sign/TrustLevel.hh>        // fedem::sign::TrustLevel
#include <sign/Manifest.hh>          // fedem::sign::Manifest, ManifestData

Symbols

plugin/ — catalog & registration

Symbol	Kind	One-line summary
`Plugin<Base>`	class template	CRTP base; gives `Base` its static `create` / `load` / `catalog`.
`PluginCatalog<Base>`	class template	Thread-safe map of key → `Creator<Base>`.
`Creator<Base>`	class template	Holds a default and an optional config factory callable.
`PluginRegisterer` / macros	class templates + macros	Insert on construction, erase on destruction.

dso/ — the loader

Symbol	Kind	One-line summary
`DSOLoader`	class (static-only)	Thread-safe `dlopen` wrapper; load one, a directory, or a path.
`SignedLoadResult`	struct	Return of `loadSigned` — `loaded`, `soPath`, `trust`, `detail`.

sign/ — signing & trust

Symbol	Kind	One-line summary
`TrustLevel`	enum class	`TRUSTED` / `UNKNOWN` / `UNSIGNED` / `REJECTED`.
`Manifest`	class (static-only)	Read / write the `.dso_manifest` + `.dso_sig` ELF sections.
`Verifier`	class (static-only)	Ed25519-verify a DSO; per-path result cache.
`fedem::exception::*`	classes	`FileNotFound`, `SignatureRejected`.

For new readers

Start with User Guide › Getting Started — it walks the whole model in one page. Then come back here for the per-symbol detail.

Design decisions worth knowing about

One catalog per Base, defined once. Plugin<Base>::catalog() is declared by the template and defined by CREATECATALOG(Base) in exactly one translation unit — the host's. Every REGISTER in every DSO resolves to that one object (via RTLD_GLOBAL). See CREATECATALOG.

Unknown key → nullptr, not an exception. A missing key almost always means a plugin DSO did not load. Genuine misuse (wrong config type) throws.

Config is type-erased through std::any. REGISTER_WITH_CONFIG stores a factory that std::any_casts to the registered Config type; a mismatch is a runtime std::bad_any_cast. There is no compile-time link between the caller's config type and the plugin's.

Handles live for the process. DSOLoader never exposes unload — see the FAQ.