# 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.
- 🧪 **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](#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)
- [Repository](#repository)
- [License](#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:
```text
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
```bash
cargo add crate-plugin-kit
```
### The asset tool (plugin authors only)
```bash
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](#prebuilt-assets).
Every release also carries the same tool as a prebuilt archive, so it can be installed
without compiling it:
```bash
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
```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);
// 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`](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.
`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
```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/
│ └── 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
| **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:
```text
```
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:
```bash
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 `dlopen`s 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:
| `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`?**
| 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](LICENSE).