crate_plugin_kit/lib.rs
1//! # crate-plugin-kit
2//!
3//! 一个**基于 cargo 的插件系统**:从 crates.io 安装 cdylib 插件,并在运行时加载。
4//!
5//! 定位上对标 npm 生态的 [`npm-plugin-kit`](https://github.com/imba97/npm-plugin-kit),
6//! 把「插件安装 + 运行时加载」这套东西搬到 cargo / `dlopen` 这边。
7//!
8//! ## 它解决的核心问题
9//!
10//! `cargo install` 只认 **bin target**。一个 `crate-type = ["cdylib"]` 的 crate
11//! 没有 bin,`cargo install` 会直接失败。所以 cdylib 插件**不能靠 `cargo install` 分发**。
12//!
13//! 本 crate 的做法是生成一个极小的 **wrapper 工程**,让插件本体的 crate 保持普通 rlib:
14//!
15//! ```text
16//! 插件 crate(crates.io 上的普通 rlib)
17//! ↓ 作为依赖
18//! wrapper 工程(本 crate 生成,几十行,[lib] crate-type = ["cdylib"])
19//! ↓ cargo build --release
20//! libxxx.so / xxx.dll / libxxx.dylib
21//! ↓ 拷到 <data-dir>/plugins/<crate>/
22//! 运行时 dlopen
23//! ```
24//!
25//! ## 快速上手
26//!
27//! ```no_run
28//! use crate_plugin_kit::{CratePluginKit, KitConfig};
29//!
30//! # #[repr(C)]
31//! # struct MyHostEntry { pub abi_version: u32, /* ... */ }
32//! let mut cfg = KitConfig::new("myapp");
33//! cfg.crate_prefix = "myapp-plugin-".into();
34//! cfg.entry_symbol = b"myapp_plugin_entry_v1".to_vec();
35//! cfg.contract_crate = "myapp-plugin".into();
36//! cfg.wrapper_body = "myapp_plugin::export!({crate_ident}::create);\n".into();
37//!
38//! let kit = CratePluginKit::<MyHostEntry>::new(cfg)?;
39//!
40//! kit.install("foo", None)?; // 装 myapp-plugin-foo
41//! let infos = kit.list()?;
42//! let plugin = kit.load("myapp-plugin-foo")?; // *const MyHostEntry
43//! # Ok::<(), crate_plugin_kit::KitError>(())
44//! ```
45//!
46//! ## 设计要点
47//!
48//! | 要点 | 说明 |
49//! | ---- | ---- |
50//! | **本 crate 不含任何宿主专有名字** | `myapp` / `myapp-plugin.toml` / 入口符号全都由 [`KitConfig`] 提供 |
51//! | **泛型而非类型擦除** | [`CratePluginKit<T>`] 的 `load()` 返回 `*const T`(**瘦指针**),不存在 `dyn Trait` 的 fat pointer 互转 |
52//! | **不做 ABI 校验** | 那是宿主契约 crate 的职责(它才知道 `T` 里有什么)。本 crate 只负责把符号取出来 |
53//! | **全栈同步** | 没有 async runtime。装插件 = 起 `cargo build`、加载 = `dlopen`,都是同步的 |
54//! | **build-host 是默认** | 它走 `cargo`,天然使用用户已配好的 registry / 镜像;prebuilt 从 GitHub 下载会绕开这些,所以只当加速项 |
55//!
56//! ## 与「宿主契约 crate」的分工
57//!
58//! ```text
59//! crate-plugin-kit ← 通用:装卸、列举、dlopen、crates.io 查询、文件锁
60//! ↑ 依赖
61//! 宿主契约 crate ← 宿主专有:ABI 结构体定义、abi_version 校验、
62//! 调用入口函数、跨边界内存所有权、catch_unwind 落点
63//! ↑ 依赖
64//! 宿主程序 / 插件
65//! ```
66//!
67//! 本 crate **不知道也不该知道** `T` 里有什么。知道得越多,就越不通用。
68
69#![deny(missing_docs)]
70#![warn(clippy::all)]
71
72pub mod cache;
73pub mod config;
74pub mod error;
75pub mod install;
76pub mod loader;
77pub mod lock;
78pub mod manifest;
79pub mod panic;
80pub mod registry;
81pub mod store;
82
83pub use config::{KitConfig, KitPaths, DEFAULT_LOCK_TIMEOUT};
84pub use error::{KitError, KitResult};
85pub use loader::{find_library, library_candidates, LoadedPlugin};
86pub use manifest::{LibSection, PluginManifest, PluginSection};
87pub use registry::{CrateInfo, CrateSummary, Registry};
88pub use store::{CratePluginKit, PluginInfo};
89
90/// 编译期注入的 target triple,例如 `x86_64-pc-windows-msvc`。
91///
92/// prebuilt 资产名按它来拼。见 `build.rs`。
93pub const TARGET_TRIPLE: &str = env!("CPK_TARGET");
94
95/// 本 crate 的版本。
96pub const VERSION: &str = env!("CARGO_PKG_VERSION");