Expand description
§crate-plugin-kit
一个基于 cargo 的插件系统:从 crates.io 安装 cdylib 插件,并在运行时加载。
定位上对标 npm 生态的 npm-plugin-kit,
把「插件安装 + 运行时加载」这套东西搬到 cargo / dlopen 这边。
§它解决的核心问题
cargo install 只认 bin target。一个 crate-type = ["cdylib"] 的 crate
没有 bin,cargo install 会直接失败。所以 cdylib 插件不能靠 cargo install 分发。
本 crate 的做法是生成一个极小的 wrapper 工程,让插件本体的 crate 保持普通 rlib:
插件 crate(crates.io 上的普通 rlib)
↓ 作为依赖
wrapper 工程(本 crate 生成,几十行,[lib] crate-type = ["cdylib"])
↓ cargo build --release
libxxx.so / xxx.dll / libxxx.dylib
↓ 拷到 <data-dir>/plugins/<crate>/
运行时 dlopen§快速上手
use crate_plugin_kit::{CratePluginKit, KitConfig};
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)?; // 装 myapp-plugin-foo
let infos = kit.list()?;
let plugin = kit.load("myapp-plugin-foo")?; // *const MyHostEntry§设计要点
| 要点 | 说明 |
|---|---|
| 本 crate 不含任何宿主专有名字 | myapp / myapp-plugin.toml / 入口符号全都由 KitConfig 提供 |
| 泛型而非类型擦除 | CratePluginKit<T> 的 load() 返回 *const T(瘦指针),不存在 dyn Trait 的 fat pointer 互转 |
| 不做 ABI 校验 | 那是宿主契约 crate 的职责(它才知道 T 里有什么)。本 crate 只负责把符号取出来 |
| 全栈同步 | 没有 async runtime。装插件 = 起 cargo build、加载 = dlopen,都是同步的 |
| build-host 是默认 | 它走 cargo,天然使用用户已配好的 registry / 镜像;prebuilt 从 GitHub 下载会绕开这些,所以只当加速项 |
§与「宿主契约 crate」的分工
crate-plugin-kit ← 通用:装卸、列举、dlopen、crates.io 查询、文件锁
↑ 依赖
宿主契约 crate ← 宿主专有:ABI 结构体定义、abi_version 校验、
调用入口函数、跨边界内存所有权、catch_unwind 落点
↑ 依赖
宿主程序 / 插件本 crate 不知道也不该知道 T 里有什么。知道得越多,就越不通用。
Re-exports§
pub use config::KitConfig;pub use config::KitPaths;pub use config::DEFAULT_LOCK_TIMEOUT;pub use error::KitError;pub use error::KitResult;pub use loader::find_library;pub use loader::library_candidates;pub use loader::LoadedPlugin;pub use manifest::LibSection;pub use manifest::PluginManifest;pub use manifest::PluginSection;pub use registry::CrateInfo;pub use registry::CrateSummary;pub use registry::Registry;pub use store::CratePluginKit;pub use store::PluginInfo;
Modules§
- cache
- 安装记录缓存
<plugins>/.plugins.json。 - config
KitConfig:把一个 kit 实例里所有跟宿主应用相关的名字参数化。- error
- 错误类型。
- install
- 安装:把 crates.io 上的一个插件 crate 变成磁盘上可
dlopen的 cdylib + manifest。 - loader
- 泛型
dlopen加载。 - lock
- 安装 / 卸载期间的排他文件锁。
- manifest
- 插件 manifest 的读写。
- panic
catch_unwind工具。- registry
- crates.io 查询。
- store
CratePluginKit:本 crate 的门面。
Constants§
- TARGET_
TRIPLE - 编译期注入的 target triple,例如
x86_64-pc-windows-msvc。 - VERSION
- 本 crate 的版本。