crate-plugin-kit
中文版见 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;updaterebuilds 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 adyn 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
- Install
- Quick start
- Configuration
- On-disk layout
- How install works
- Prebuilt assets
- Where the manifest comes from
- What it does not do
- Repository
- License
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
The asset tool (plugin authors only)
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:
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 —
libloading0.9 requires 1.88). cargoonPATHat 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 ;
// The `#[repr(C)]` entry struct your contract crate defines.
let mut cfg = new;
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 = new?;
kit.install?; // installs myapp-plugin-foo
for info in kit.list?
let plugin = kit.load?; // *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:
# 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.