# crate-plugin-kit
[](https://github.com/imba97/crate-plugin-kit/actions/workflows/release.yaml)
[](https://crates.io/crates/crate-plugin-kit)
[](https://docs.rs/crate-plugin-kit)
[](#license)
[](#requirements)
> 中文版见 [README_CN.md](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`](https://github.com/imba97/npm-plugin-kit) —
"install a plugin, then load it" — moved onto cargo.
```console
$ 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 `cdylib`s, `dlopen`ed on
demand. Nothing is linked into your binary.
- 🧩 **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.
- 📦 **Install straight from crates.io** — one call, no manual downloads or vendoring.
- 🔨 **Build-host by default** — installs go through `cargo build`, so whatever registry or
mirror you already configured just works.
- ⚡ **Prebuilt accelerator** — optionally pull a ready-made cdylib from GitHub Releases,
falling back to a local build on any failure.
- 📄 **The manifest travels with the code** — a plugin's metadata lives in its own repo root
and is copied at install time, so it can never drift from the implementation.
- 🔒 **Cross-process install lock** — two terminals cannot corrupt the store.
- 🚫 **Refuses unsafe unloads** — unlinking a library that is still loaded is rejected, not
attempted. Guessing wrong there is UB.
- 🪶 **Zero async** — no runtime, no `tokio`. Installing is a subprocess, loading is `dlopen`.
- 📚 **Fully documented public API** — `#![deny(missing_docs)]`.
## Contents
- [Why this exists](#why-this-exists)
- [Install](#install)
- [Quick start](#quick-start)
- [Configuration](#configuration)
- [On-disk layout](#on-disk-layout)
- [How install works](#how-install-works)
- [Prebuilt assets](#prebuilt-assets)
- [Where the manifest comes from](#where-the-manifest-comes-from)
- [What it does not do](#what-it-does-not-do)
- [Development](#development)
- [Repository](#repository)
- [License](#license)
## Why this exists
`cargo install` only installs **bin targets**. A crate with `crate-type = ["cdylib"]` has no
bin, so installing it fails outright:
```console
$ cargo install my-plugin
error: there is nothing to install
```
Adding a bin target does not help either — `cargo install` would put that bin in
`~/.cargo/bin` and still leave the cdylib nowhere useful. And building the plugin crate
directly does not work, because Cargo builds dependencies as rlibs and never emits a cdylib
for them.
So this crate generates a tiny **wrapper project** instead, which lets the plugin itself stay
an ordinary rlib:
```text
plugin crate (an ordinary rlib on crates.io)
│ as a dependency
▼
wrapper project (generated here, ~30 lines, [lib] crate-type = ["cdylib"])
│ 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`;
- its author writes **no `#[no_mangle]` at all** — the cdylib's shape is generated by the
host contract crate's `export!` macro.
## Install
```bash
cargo add crate-plugin-kit
```
### Requirements
- **Rust 1.88+** to build (this is the MSRV — `libloading` 0.9 requires 1.88).
- **`cargo` on `PATH`** at run time, for the default build-host install path. It is not linked
in — installs are a subprocess. The prebuilt path does not need it.
- Linux, macOS and Windows.
## Quick start
```rust
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);
}
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`](https://docs.rs/crate-plugin-kit/latest/crate_plugin_kit/struct.KitConfig.html)
is where **every host-specific name lives**. This crate hardcodes none of them.
| `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.
### Why `local_overrides` is needed
The wrapper lives under `<data-dir>/build/`, so it **cannot see your project's
`.cargo/config.toml`**. To make a wrapper build against a local checkout during development,
the host has to say so explicitly, and this crate writes it into the wrapper's own
`[patch.crates-io]`.
## On-disk layout
```text
~/.{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/
└── .lock ← cross-process install lock
```
`.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
Two paths. **build-host is the default**, because it shells out to `cargo` and therefore
honours whatever registry or mirror the user already configured. The prebuilt path goes to
GitHub, which bypasses all of that — so it is only ever an accelerator.
| **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 |
```text
install(name, version)
├─ take the lock at <data-dir>/.lock
├─ normalise the crate name (add the prefix)
├─ resolve the version (query crates.io when None)
├─ drop any previous install directory
├─ [prefer_prebuilt] try prebuilt ── ok ──▶ done
│ └─ unavailable ─┐
└─────────────────────────────────────────────────◄─┘
generate wrapper → cargo metadata → cargo build --release
→ find the cdylib → copy cdylib + manifest → update .plugins.json
```
If prebuilt is unavailable for any reason — never published, 404, network failure — install
**silently falls back to build-host**. The two paths are independent, and the `cargo` one
often succeeds where GitHub is unreachable.
`cargo build` inherits stdio, so you see its progress. That step can take minutes; 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:
```text
```
For example:
```text
myapp-plugin-foo-0.1.0-x86_64-pc-windows-msvc.dll
myapp-plugin-foo-0.1.0-x86_64-pc-windows-msvc.toml
```
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.
## Where the manifest comes from
The plugin crate ships `<manifest_name>` at its source root. During a build-host install,
this crate locates the crate source through `cargo metadata` and copies the file into the
install directory:
```text
cargo metadata --format-version 1 --manifest-path <wrapper>/Cargo.toml
→ find the entry in packages[] whose name matches the plugin crate
→ take the parent of its manifest_path — that is the crate source directory
→ copy <manifest_name> from there
```
This keeps a single source of truth: a plugin's metadata travels with its code. And detection
at runtime stays a plain file read — **no `dlopen` is needed just to list plugins**.
## What it does not do
- **No ABI validation.** It has no idea what is inside `T`. Checking `abi_version` is the host
contract crate's job.
- **No `catch_unwind` call sites.** A helper is provided (`panic::guard`), but the contract
crate is what knows *which* calls cross the boundary, so *it* must wrap them.
- **No async.** Installing starts a `cargo build`; loading is `dlopen`. Both are synchronous.
- **No source restrictions.** No allowlist, no signature checks, no sandbox — the same trust
model as `cargo install`.
The dividing line is one question: **does the operation need to know what is inside `T`?**
| 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 |
## Development
```text
crate-plugin-kit/
├── Cargo.toml # [package] + single-element [workspace]
├── build.rs # injects the target triple
├── docs/proposal.md # design notes
├── src/
│ ├── lib.rs # public exports + crate docs
│ ├── config.rs # KitConfig / KitPaths
│ ├── error.rs # KitError
│ ├── manifest.rs # manifest schema + read/write
│ ├── store.rs # CratePluginKit<T>
│ ├── loader.rs # generic dlopen, no type erasure
│ ├── lock.rs # cross-process file lock
│ ├── cache.rs # .plugins.json
│ ├── registry.rs # crates.io queries
│ ├── panic.rs # catch_unwind helper
│ └── install/
│ ├── build_host.rs # generated wrapper + cargo build (default)
│ └── prebuilt.rs # GitHub Releases download (accelerator)
└── tests/
├── load.rs # end-to-end: build a cdylib, dlopen it, call across
└── fixtures/toy-plugin/ # the zero-dependency cdylib used by that test
```
```bash
cargo fmt --all --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked
cargo package --locked
```
`tests/load.rs` is the one that matters most: it compiles the fixture into a real
`cdylib`, copies it into a temporary plugin store, then `dlopen`s it and calls a function
pointer across the boundary. Everything else is file I/O and string derivation.
### On `rust-toolchain.toml`
There deliberately isn't one. Two reasons:
1. A pinned channel would override the CI job that tests the MSRV, which is the thing
`rust-version` in `Cargo.toml` actually promises;
2. pinning an exact version forces contributors to download a whole extra toolchain,
while `rust-version` plus CI already covers the real problem.
The generated wrapper does not get one either — it inherits whatever toolchain you are
already using.
## Repository
<https://github.com/imba97/crate-plugin-kit>
## License
MIT — see [LICENSE](LICENSE).