crate-plugin-kit 0.3.2

Installs and loads cdylib plugins and builds their prebuilt assets.
Documentation

crate-plugin-kit

Release crates.io docs.rs license MSRV

中文版见 README_CN.md

A cargo-based plugin system: install cdylib plugins from crates.io and load them at runtime. The Rust counterpart of npm-plugin-kit — "install a plugin, then load it" — moved onto cargo.

$ cargo install my-plugin          # the plugin is a cdylib crate
error: there is nothing to install

$ # crate-plugin-kit does this instead:
  myapp-plugin-foo  0.1.0
    wrapper   ~/.myapp/build/myapp-plugin-foo/          cargo build --release
    library   ~/.myapp/plugins/myapp-plugin-foo/libmyapp_plugin_foo.so
    manifest  ~/.myapp/plugins/myapp-plugin-foo/myapp-plugin.toml

Features

  • 🔌 Runtime loading, zero compile-time coupling — plugins are cdylibs, dlopened on demand. Nothing is linked into your binary.
  • 🧪 Install from a local checkout — install_from_path(".") builds and lands the same two files a published plugin gets, so a plugin author can use what they are working on before publishing it; update rebuilds that directory.
  • 📦 Install straight from crates.io — builds locally through cargo, so whatever registry or mirror you already configured just works. Prebuilt assets are an optional accelerator, never a requirement.
  • 🧩 Generic, not type-erased — load() hands back a thin *const T, never a dyn Trait. No fat-pointer conversion, so no UB at the boundary.
  • 🏷️ Every host-specific name is configuration — app id, manifest name, crate prefix, entry symbol, wrapper body. This crate hardcodes none of them.
  • 🔒 Safe under concurrency and removal — a cross-process install lock, and a refusal to unlink a library that is still loaded.

Contents

Why this exists

cargo install only installs bin targets, so a crate-type = ["cdylib"] crate has nothing to install. Adding a bin target does not help — it lands in ~/.cargo/bin and the cdylib still goes nowhere useful. Building the plugin crate directly does not work either: Cargo builds dependencies as rlibs and never emits a cdylib for them.

So this crate generates a tiny wrapper project (~30 lines, [lib] crate-type = ["cdylib"]) that depends on the plugin, leaving the plugin itself an ordinary rlib:

plugin crate  (an ordinary rlib on crates.io)
    │  as a dependency
    ▼
wrapper project  (generated here)
    │  cargo build --release
    ▼
libxxx.so / xxx.dll / libxxx.dylib
    │  copied to <data-dir>/plugins/<crate>/
    ▼
dlopen at runtime

Because the plugin stays an rlib, it is an ordinary crate to the rest of the ecosystem, it can be unit-tested with a plain use without going anywhere near dlopen, and its author writes no #[no_mangle] at all — the cdylib's shape is generated by the host contract crate's export! macro.

Install

cargo add crate-plugin-kit

The asset tool (plugin authors only)

cargo install crate-plugin-kit --bin plugin-asset

Optional, and not needed to use the library. It is what produces the files a plugin release publishes — see Prebuilt assets.

Every release also carries the same tool as a prebuilt archive, so it can be installed without compiling it:

cargo binstall crate-plugin-kit --bin plugin-asset

That downloads crate-plugin-kit-<target>.{tar.gz,zip} from the release and unpacks plugin-asset + LICENSE out of the top level. cargo install stays the documented default — it works everywhere, including behind a mirror; cargo binstall goes straight to GitHub and is seconds instead of minutes.

Requirements

  • Rust 1.88+ to build (the MSRV — libloading 0.9 requires 1.88).
  • cargo on PATH at run time, for the default build-host path. Installs are a subprocess; nothing is linked in. The prebuilt path does not need it.
  • Linux, macOS and Windows.

Quick start

use crate_plugin_kit::{CratePluginKit, KitConfig};

// The `#[repr(C)]` entry struct your contract crate defines.
#[repr(C)]
struct MyHostEntry {
    abi_version: u32,
    // ...
}

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
for info in kit.list()? {
    println!("{} {}", info.name, info.version);

    // Your own sections came along with the summary — `[detect]`, `[context]`, whatever
    // your host defines. The kit carries them through; reading them is your business,
    // and you do not have to open the manifest a second time to get them.
    let my_sections = info.extra.get("detect");
}

let plugin = kit.load("myapp-plugin-foo")?;   // *const MyHostEntry
let entry: *const MyHostEntry = plugin.entry();

name accepts a short name ("foo", the crate prefix is added for you) or a full crate name. Pass None as the version to take the latest from crates.io.

Configuration

KitConfig is where every host-specific name lives. This crate hardcodes none of them.

Field Meaning
id App id. Data dir becomes ~/.{id}. Also used in the HTTP User-Agent.
manifest_name Plugin manifest filename, e.g. myapp-plugin.toml.
crate_prefix Plugin crate prefix. install("foo") → myapp-plugin-foo.
entry_symbol Exported symbol to look up, e.g. myapp_plugin_entry_v1.
lib_stem_prefix cdylib filename prefix, e.g. myapp_plugin_.
contract_crate / contract_version The host's contract crate — the generated wrapper depends on it.
wrapper_edition / wrapper_body Generated wrapper's edition and src/lib.rs body. {crate_ident} is substituted.
data_dir Override ~/.{id}. Useful for tests.
lock_timeout How long to wait for the install lock. Default 30s.
prefer_prebuilt Try GitHub Releases before falling back to a local build. Default true.
target_triple Override the compile-time target.
registry crates.io base URL. Point it at a mirror if you like.
local_overrides crate name → local path. Becomes the wrapper's [patch.crates-io]. Dev only.

KitConfig::new(id) fills in conservative defaults; you must at least set crate_prefix, entry_symbol, lib_stem_prefix, contract_crate and wrapper_body, or the generated wrapper will not compile.

local_overrides exists because the wrapper lives under <data-dir>/build/ and cannot see your project's .cargo/config.toml. To build a wrapper against a local checkout the host has to say so explicitly, and this crate writes it into the wrapper's own [patch.crates-io].

On-disk layout

~/.{id}/
├── plugins/
│   ├── myapp-plugin-foo/
│   │   ├── myapp-plugin.toml     ← manifest (written at install time)
│   │   └── libmyapp_plugin_foo.so
│   └── .plugins.json             ← install record cache
├── build/                        ← generated wrappers
│   └── myapp-plugin-foo/
│       └── target/               ← cargo's build cache, kept between installs
└── .lock                         ← cross-process install lock

The wrapper's generated files are rewritten on every install, but build/<crate>/target/ is not: it is cargo's cache, and it is what lets update recompile the plugin and not the plugin's entire dependency graph along with it. plugin rm removes the installed plugin, not this directory — clear <data-dir>/build/ by hand if the disk space matters more than the next build being fast.

.plugins.json is a cache, not a source of truth. Lose it or corrupt it and list() rebuilds from the manifests on disk.

How install works

Path What it does Requires
build-host (default) generate wrapper → cargo build --release → copy artifact a Rust toolchain
prebuilt download cdylib + manifest from GitHub Releases the plugin author published assets

If prebuilt is unavailable for any reason — never published, 404, network failure — install silently falls back to build-host, which often succeeds where GitHub is unreachable. cargo build inherits stdio, so you see its progress; that step can take minutes and swallowing the output would be a poor experience. Versions are pinned exactly (=x.y.z), so the version recorded in .plugins.json and the cdylib that was actually built can never disagree.

Prebuilt assets

Two raw files rather than an archive, which saves pulling in the tar, gzip and zip crates:

{crate}-{version}-{target}.{so|dylib|dll}   ← the cdylib
{crate}-{version}-{target}.toml             ← the manifest

For example myapp-plugin-foo-0.1.0-x86_64-pc-windows-msvc.dll plus the matching .toml.

Producing them

This crate ships the tool that writes both files, so a release does not need a second implementation of the wrapper, the lib name, or the naming convention:

cargo install crate-plugin-kit --bin plugin-asset
plugin-asset --id myapp
# dist/myapp-plugin-foo-0.1.0-x86_64-unknown-linux-gnu.so
# dist/myapp-plugin-foo-0.1.0-x86_64-unknown-linux-gnu.toml

--id is the same string the host passes to KitConfig::new. Run it in the plugin's checkout; --manifest-path, --out-dir, --target and --target-dir are all overridable (--help lists them). It refuses to run when the plugin manifest's [plugin] version and Cargo.toml's version disagree, and — when the target is the machine it is running on — it dlopens the result to confirm the entry symbol is really exported.

So a release matrix only has to name the target it builds for, one runner per target:

Runner Target triple Asset extension
ubuntu-latest x86_64-unknown-linux-gnu .so
windows-latest x86_64-pc-windows-msvc .dll
macos-13 x86_64-apple-darwin .dylib
macos-14 aarch64-apple-darwin .dylib

The extension follows the target triple, not the machine doing the packing, and the lookup at install time follows the host's own triple — so an asset is only ever used by a host built for the same target. An asset for a triple nobody runs is simply never downloaded.

How they are found

The repository URL comes from the crate's repository field on crates.io — at that point the plugin is not installed yet, so the registry is the only thing that can be asked. Both files sit on the tag v{version} of that repository; the version inside the .toml has to match, or the download is rejected.

Where the manifest comes from

The plugin crate ships <manifest_name> at its source root. A build-host install locates that source directory through cargo metadata and copies the file into the install directory, so a plugin's metadata travels with its code and can never drift from the implementation. Runtime detection therefore stays a plain file read — listing plugins needs no dlopen.

What it does not do

The dividing line is one question: does the operation need to know what is inside T?

Operation Needs T's contents? Owner
install / uninstall / list no this crate
dlopen, look up the symbol, cast to *const T no this crate
query crates.io no this crate
validate abi_version yes contract crate
call command() / name() yes contract crate
manage cross-boundary string lifetimes yes contract crate

It has no idea what is inside T, so ABI validation, catch_unwind call sites and cross-boundary lifetimes all belong to the contract crate — a panic::guard helper is provided, but only the contract crate knows which calls cross the boundary. There is no async either, and no source restrictions: no allowlist, no signature checks, no sandbox, the same trust model as cargo install.

Repository

https://github.com/imba97/crate-plugin-kit

License

MIT — see LICENSE.