Expand description
§crate-plugin-kit
A cargo-based plugin system: install cdylib plugins from crates.io and load them at runtime.
It is the counterpart of npm’s npm-plugin-kit,
moving “install a plugin, then load it” onto cargo / dlopen.
§The core problem it solves
cargo install only recognizes bin targets. A crate with
crate-type = ["cdylib"] has no bin, so cargo install fails outright. cdylib
plugins therefore cannot be distributed with cargo install.
What this crate does instead is generate a tiny wrapper project, leaving the plugin crate itself a plain rlib:
plugin crate (a plain rlib on crates.io)
↓ as a dependency
wrapper project (generated by this crate, a few dozen lines, [lib] crate-type = ["cdylib"])
↓ cargo build --release
libxxx.so / xxx.dll / libxxx.dylib
↓ copied to <data-dir>/plugins/<crate>/
runtime dlopen§Quick start
use crate_plugin_kit::{CratePluginKit, KitConfig};
let mut cfg = KitConfig::new("myapp");
cfg.crate_prefix = "myapp-plugin-".into();
cfg.entry_symbol = b"myapp_plugin_entry_v1".to_vec();
cfg.contract_crate = "myapp-plugin".into();
cfg.wrapper_body = "myapp_plugin::export!({crate_ident}::create);\n".into();
let kit = CratePluginKit::<MyHostEntry>::new(cfg)?;
kit.install("foo", None)?; // installs myapp-plugin-foo
let infos = kit.list()?;
let plugin = kit.load("myapp-plugin-foo")?; // *const MyHostEntry§Design points
| Point | Detail |
|---|---|
| No host-specific names in this crate | myapp / myapp-plugin.toml / the entry symbol all come from KitConfig |
| Generics instead of type erasure | load() on CratePluginKit<T> returns a *const T (a thin pointer), so no fat-pointer conversion between dyn Trait vtables |
| No ABI validation | That is the host contract crate’s job (only it knows what is inside T). This crate only resolves the symbol |
| Fully synchronous | No async runtime. Installing a plugin = running cargo build; loading it = dlopen |
| build-host is the default | It goes through cargo and therefore uses the registry / mirror the user already configured; prebuilt downloads from GitHub bypass those, so it is only an accelerator |
| Publishing is the same wrapper | pack_plugin builds the wrapper from a local checkout and names the two files the download path looks for, so a release does not need a second implementation of any of this |
§Division of labor with the host contract crate
crate-plugin-kit <- generic: install/uninstall, list, dlopen, crates.io queries, file lock
↑ depends on
host contract crate <- host-specific: ABI struct definitions, abi_version checks,
calling the entry function, cross-boundary memory ownership,
catch_unwind placement
↑ depends on
host program / pluginsThis crate does not know and should not know what is inside T. The more it knows,
the less generic it is.
Re-exports§
pub use config::KitConfig;pub use config::KitPaths;pub use config::DEFAULT_LOCK_TIMEOUT;pub use error::KitError;pub use error::KitResult;pub use loader::find_library;pub use loader::library_candidates;pub use loader::LoadedPlugin;pub use manifest::LibSection;pub use manifest::PluginManifest;pub use manifest::PluginSection;pub use pack::build as pack_plugin;pub use pack::PackOptions;pub use pack::PackedAssets;pub use registry::CrateInfo;pub use registry::CrateSummary;pub use registry::Registry;pub use store::CratePluginKit;pub use store::PluginInfo;
Modules§
- cache
- Install record cache
<plugins>/.plugins.json. - config
KitConfig: parametrizes every host-application-specific name used by a kit instance.- error
- Error types.
- install
- Installation: turning a plugin crate on crates.io into a loadable cdylib plus its manifest on disk.
- loader
- Generic
dlopenloading. - lock
- Exclusive file lock held during install / uninstall.
- manifest
- Reading and writing the plugin manifest.
- pack
- Producing the two files a plugin release carries.
- panic
catch_unwindhelpers.- registry
- crates.io queries.
- store
CratePluginKit: the facade of this crate.
Constants§
- TARGET_
TRIPLE - Target triple injected at compile time, such as
x86_64-pc-windows-msvc. - VERSION
- Version of this crate.