1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
//! # crate-plugin-kit
//!
//! A cargo-based plugin system: install cdylib plugins from crates.io and load them
//! at runtime.
//!
//! It is the counterpart of npm's [`npm-plugin-kit`](https://github.com/imba97/npm-plugin-kit),
//! moving "install a plugin, then load it" onto cargo / `dlopen`.
//!
//! ## The core problem it solves
//!
//! `cargo install` only recognizes bin targets. A crate with
//! `crate-type = ["cdylib"]` has no bin, so `cargo install` fails outright. cdylib
//! plugins therefore cannot be distributed with `cargo install`.
//!
//! What this crate does instead is generate a tiny wrapper project, leaving the plugin
//! crate itself a plain rlib:
//!
//! ```text
//! plugin crate (a plain rlib on crates.io)
//! ↓ as a dependency
//! wrapper project (generated by this crate, a few dozen lines, [lib] crate-type = ["cdylib"])
//! ↓ cargo build --release
//! libxxx.so / xxx.dll / libxxx.dylib
//! ↓ copied to <data-dir>/plugins/<crate>/
//! runtime dlopen
//! ```
//!
//! ## Quick start
//!
//! ```no_run
//! use crate_plugin_kit::{CratePluginKit, KitConfig};
//!
//! # #[repr(C)]
//! # struct MyHostEntry { pub 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
//! let infos = kit.list()?;
//! let plugin = kit.load("myapp-plugin-foo")?; // *const MyHostEntry
//! # Ok::<(), crate_plugin_kit::KitError>(())
//! ```
//!
//! ## Design points
//!
//! | Point | Detail |
//! | ---- | ---- |
//! | No host-specific names in this crate | `myapp` / `myapp-plugin.toml` / the entry symbol all come from [`KitConfig`] |
//! | 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 |
//! | No ABI validation | That is the host contract crate's job (only it knows what is inside `T`). This crate only resolves the symbol |
//! | Fully synchronous | No async runtime. Installing a plugin = running `cargo build`; loading it = `dlopen` |
//! | 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 |
//! | 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 |
//!
//! ## Division of labor with the host contract crate
//!
//! ```text
//! crate-plugin-kit <- generic: install/uninstall, list, dlopen, crates.io queries, file lock
//! ↑ depends on
//! host contract crate <- host-specific: ABI struct definitions, abi_version checks,
//! calling the entry function, cross-boundary memory ownership,
//! catch_unwind placement
//! ↑ depends on
//! host program / plugins
//! ```
//!
//! This crate does not know and should not know what is inside `T`. The more it knows,
//! the less generic it is.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
/// Target triple injected at compile time, such as `x86_64-pc-windows-msvc`.
///
/// prebuilt asset names are built from it. See `build.rs`.
pub const TARGET_TRIPLE: &str = env!;
/// Version of this crate.
pub const VERSION: &str = env!;