crate-plugin-kit 0.3.2

Installs and loads cdylib plugins and builds their prebuilt assets.
Documentation
//! # 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.

#![deny(missing_docs)]
#![warn(clippy::all)]

pub mod cache;
pub mod config;
pub mod error;
pub mod install;
pub mod loader;
pub mod lock;
pub mod manifest;
pub mod pack;
pub mod panic;
pub mod registry;
pub mod store;

mod wrapper;

pub use config::{KitConfig, KitPaths, DEFAULT_LOCK_TIMEOUT};
pub use error::{KitError, KitResult};
pub use loader::{find_library, library_candidates, LoadedPlugin};
pub use manifest::{LibSection, PluginManifest, PluginSection};
pub use pack::{build as pack_plugin, PackOptions, PackedAssets};
pub use registry::{CrateInfo, CrateSummary, Registry};
pub use store::{CratePluginKit, PluginInfo};

/// 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!("CPK_TARGET");

/// Version of this crate.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");