Skip to main content

crate_plugin_kit/
lib.rs

1//! # crate-plugin-kit
2//!
3//! A cargo-based plugin system: install cdylib plugins from crates.io and load them
4//! at runtime.
5//!
6//! It is the counterpart of npm's [`npm-plugin-kit`](https://github.com/imba97/npm-plugin-kit),
7//! moving "install a plugin, then load it" onto cargo / `dlopen`.
8//!
9//! ## The core problem it solves
10//!
11//! `cargo install` only recognizes bin targets. A crate with
12//! `crate-type = ["cdylib"]` has no bin, so `cargo install` fails outright. cdylib
13//! plugins therefore cannot be distributed with `cargo install`.
14//!
15//! What this crate does instead is generate a tiny wrapper project, leaving the plugin
16//! crate itself a plain rlib:
17//!
18//! ```text
19//! plugin crate (a plain rlib on crates.io)
20//!     ↓  as a dependency
21//! wrapper project (generated by this crate, a few dozen lines, [lib] crate-type = ["cdylib"])
22//!     ↓  cargo build --release
23//! libxxx.so / xxx.dll / libxxx.dylib
24//!     ↓  copied to <data-dir>/plugins/<crate>/
25//! runtime dlopen
26//! ```
27//!
28//! ## Quick start
29//!
30//! ```no_run
31//! use crate_plugin_kit::{CratePluginKit, KitConfig};
32//!
33//! # #[repr(C)]
34//! # struct MyHostEntry { pub abi_version: u32, /* ... */ }
35//! let mut cfg = KitConfig::new("myapp");
36//! cfg.crate_prefix = "myapp-plugin-".into();
37//! cfg.entry_symbol = b"myapp_plugin_entry_v1".to_vec();
38//! cfg.contract_crate = "myapp-plugin".into();
39//! cfg.wrapper_body = "myapp_plugin::export!({crate_ident}::create);\n".into();
40//!
41//! let kit = CratePluginKit::<MyHostEntry>::new(cfg)?;
42//!
43//! kit.install("foo", None)?;                   // installs myapp-plugin-foo
44//! let infos = kit.list()?;
45//! let plugin = kit.load("myapp-plugin-foo")?;  // *const MyHostEntry
46//! # Ok::<(), crate_plugin_kit::KitError>(())
47//! ```
48//!
49//! ## Design points
50//!
51//! | Point | Detail |
52//! | ---- | ---- |
53//! | No host-specific names in this crate | `myapp` / `myapp-plugin.toml` / the entry symbol all come from [`KitConfig`] |
54//! | Generics instead of type erasure | `load()` on [`CratePluginKit<T>`] returns a `*const T` (a thin pointer), so no fat-pointer conversion between `dyn Trait` vtables |
55//! | No ABI validation | That is the host contract crate's job (only it knows what is inside `T`). This crate only resolves the symbol |
56//! | Fully synchronous | No async runtime. Installing a plugin = running `cargo build`; loading it = `dlopen` |
57//! | build-host is the default | It goes through `cargo` and therefore uses the registry / mirror the user already configured; prebuilt downloads from GitHub bypass those, so it is only an accelerator |
58//! | Publishing is the same wrapper | [`pack_plugin`] builds the wrapper from a local checkout and names the two files the download path looks for, so a release does not need a second implementation of any of this |
59//!
60//! ## Division of labor with the host contract crate
61//!
62//! ```text
63//! crate-plugin-kit  <- generic: install/uninstall, list, dlopen, crates.io queries, file lock
64//!      ↑ depends on
65//! host contract crate <- host-specific: ABI struct definitions, abi_version checks,
66//!                        calling the entry function, cross-boundary memory ownership,
67//!                        catch_unwind placement
68//!      ↑ depends on
69//! host program / plugins
70//! ```
71//!
72//! This crate does not know and should not know what is inside `T`. The more it knows,
73//! the less generic it is.
74
75#![deny(missing_docs)]
76#![warn(clippy::all)]
77
78pub mod cache;
79pub mod config;
80pub mod error;
81pub mod install;
82pub mod loader;
83pub mod lock;
84pub mod manifest;
85pub mod pack;
86pub mod panic;
87pub mod registry;
88pub mod store;
89
90mod wrapper;
91
92pub use config::{KitConfig, KitPaths, DEFAULT_LOCK_TIMEOUT};
93pub use error::{KitError, KitResult};
94pub use loader::{find_library, library_candidates, LoadedPlugin};
95pub use manifest::{LibSection, PluginManifest, PluginSection};
96pub use pack::{build as pack_plugin, PackOptions, PackedAssets};
97pub use registry::{CrateInfo, CrateSummary, Registry};
98pub use store::{CratePluginKit, PluginInfo};
99
100/// Target triple injected at compile time, such as `x86_64-pc-windows-msvc`.
101///
102/// prebuilt asset names are built from it. See `build.rs`.
103pub const TARGET_TRIPLE: &str = env!("CPK_TARGET");
104
105/// Version of this crate.
106pub const VERSION: &str = env!("CARGO_PKG_VERSION");