https://github.com/itsethra/scotch
Create WASM plugins easily in Rust
https://github.com/itsethra/scotch
plugin plugin-system rust wasm webassembly
Last synced: 7 months ago
JSON representation
Create WASM plugins easily in Rust
- Host: GitHub
- URL: https://github.com/itsethra/scotch
- Owner: ItsEthra
- License: mit
- Created: 2023-01-16T17:19:13.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-01-26T13:58:48.000Z (about 3 years ago)
- Last Synced: 2025-06-16T22:23:44.175Z (8 months ago)
- Topics: plugin, plugin-system, rust, wasm, webassembly
- Language: Rust
- Homepage:
- Size: 197 KB
- Stars: 66
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Scotch
Library for creating WASM plugins with Rust.
Scotch allows you to pass complex types to/from functions in WASM plugins.
It achieves that by encoding and decoding complex types when passed between host and guest environment.
Encoding and decoding is handled by `bincode@2.0.0-rc.2` so you need your types
to implement `bincode::Encode` and `bincode::Decode` traits.
## Headless mode
You can disable default features to enable headless mode. This should reduce host binary size.
In headless mode you are unable to compile wasm bytecode and need to rely on serialized plugins.
See `WasmPluginBuilder::from_serialized`, `WasmPluginBuilder::from_serialized_compressed`,
`WasmPlugin::serialize`, `WasmPlugin::serialize_compress`. `*_compress`, `*_compressed` functions
uses `flate2` crate to compress/decompress plugins, to use them you need to have `flate2` feature enabled.
## Instalation
```toml
# In your main application
[dependenices]
scotch-host = "0.1"
# In your plugins
[dependencies]
scotch-guest = "0.1"
```
## Example application
```rust
// Define functions that your plugin exports.
#[scotch_host::guest_functions]
extern "C" {
// To pass complex types you use references to them, not owned types.
// The name must match with the name of the plugin function.
pub fn add_up_list(nums: &Vec) -> i32;
}
// Create your plugin
let plugin = WasmPlugin::builder()
.with_state(0)
// PLUGIN_BYTES is a slice of your wasm plugin.
.from_binary(PLUGIN_BYTES)?
// This call caches exports of your plugin.
.with_exports(make_exports![add_up_list])
.finish()?;
// Call the function
let sum = plugin.function_unwrap::()(&vec![1, 2, 3, 4, 5])?;
assert_eq!(sum, 15);
```
## Example plugin
```rust
// This is required.
scotch_guest::export_alloc!();
// Functions marked with `guest_function` will be exposed to the host.
// All complex types such as Vec, String, user-defined types must be passed by immutable reference.
#[scotch_guest::guest_function]
fn add_up_list(items: &Vec) -> i32 {
items.iter().sum::()
}
```
More complete example can be found [here](/examples)
## Planned features
* [ ] Improve codegeneration with proc macros.
* [ ] Mutable references.
* [ ] WASI support.