Skip to main content

Crate crate_plugin_kit

Crate crate_plugin_kit 

Source
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 的版本。