1 unstable release
Uses old Rust 2015
0.1.0 | Sep 27, 2017 |
---|
#668 in Cargo plugins
11KB
116 lines
cargo-plugin, a tool to handle plugins at compile tome for your crate
Warning: experimental project, things might change soon
This tool helps you build a plugin infrastructure for your Rust project. Highlights of that system:
- the plugin API is versioned, so plugins compatibility is checked
- it only uses stable Rust code
- you can publish your project on crates.io with a default set of dependencies, but allow an override if building locally from source
The rust-plugin-test project is an example of this usage.
Installation
Launch the following command:
cargo install cargo-plugin
How to use
Setting it up
This will work better if your project uses a workspace:
- the
plugin-api
crate defines traits that plugins should implementcargo-plugin
expects that this crates exposes aPluginInformation
trait
- the
plugins
crate holds the plugins- its
Cargo.toml
file declares a dependency onplugin-api
by version. This file will be rewritten bycargo-plugin
- the
metadata.toml
file indicates the plugin API crate's name - all plugins are subdirectories of
plugins/src
:- every plugin has a
metadata.toml
file declaring its name and its dependencies - every plugin, in its
mod.rs
file:- imports the traits from the plugin API crate
- declares a
PLUGIN_METADATA
const element that implements thePluginInformation
trait
- every plugin has a
- its
- the
main
crate:- declares a dependency to the plugin API
- declares a dependency to the plugins crate, by version AND by path
You can now publish your crates, first the plugin API, then the plugins crate, then the main one.
Usage
Your crates are published with a default set of plugins. If you want to build a version with a different set of plugins, add and remove plugin folders in plugins/src
, then run cargo plugin
while in plugins/
.
The cargo-plugin
tool will read the metadata from every plugin folder, then edit the Cargo.toml
and src/lib.rs
to do the following tasks:
- import crates used by every plugin
- declare all plugins as submodules
- generate a function declaring the plugins at runtime
Dependencies
~6.5MB
~140K SLoC