Skip to main content

Crate crate_plugin_kit

Crate crate_plugin_kit 

Source
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

PointDetail
No host-specific names in this cratemyapp / myapp-plugin.toml / the entry symbol all come from KitConfig
Generics instead of type erasureload() on CratePluginKit<T> returns a *const T (a thin pointer), so no fat-pointer conversion between dyn Trait vtables
No ABI validationThat is the host contract crate’s job (only it knows what is inside T). This crate only resolves the symbol
Fully synchronousNo async runtime. Installing a plugin = running cargo build; loading it = dlopen
build-host is the defaultIt 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 wrapperpack_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 / plugins

This 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 dlopen loading.
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_unwind helpers.
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.