crate-plugin-kit 0.3.2

Installs and loads cdylib plugins and builds their prebuilt assets.
Documentation
# crate-plugin-kit

[![Release](https://github.com/imba97/crate-plugin-kit/actions/workflows/release.yaml/badge.svg)](https://github.com/imba97/crate-plugin-kit/actions/workflows/release.yaml)
[![crates.io](https://img.shields.io/crates/v/crate-plugin-kit.svg)](https://crates.io/crates/crate-plugin-kit)
[![docs.rs](https://img.shields.io/docsrs/crate-plugin-kit)](https://docs.rs/crate-plugin-kit)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](#license)
[![MSRV](https://img.shields.io/badge/rust-1.88%2B-blue.svg)](#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.

| 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

```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

| 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:

```text
{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:

```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:

| 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](LICENSE).