plugy 0.2.0

plugy empowers you to construct agnostic dynamic plugin systems using Rust and WASM
Documentation 
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

<img src="./assets/logo.svg" width="100%">

[![GitHub Actions][github-actions-badge]](https://github.com/geofmureithi/plugy/actions)
[![GitHub Releases][github-release-svg]][github-release]

# plugy

plugy is a plugin system designed to enable the seamless integration of Rust-based plugins into your application. It provides a runtime environment for loading and executing plugins written in WebAssembly (Wasm), enabling dynamic extensibility and modularity in your Rust projects.

## Features

- Load and execute plugins compiled to WASM.
- Flexible runtime management of plugins.
- Calls to plugin functions are async.
- Easy-to-use macros for generating plugin interfaces.

## Getting Started

To use plugy in your Rust project, follow these steps:

1. Write your plugin trait:

```rust
#[plugy::plugin]
trait Greeter {
    fn greet(&self) -> String;
}
```

2. Write your first plugin implementation

```rust
#[derive(Debug, Deserialize)]
struct FooPlugin;

#[plugin_impl]
impl Greeter for FooPlugin {
    fn greet(&self) -> String {
        "Hello From Foo Plugin".to_owned()
    }
}
```

Compile it!

```
cargo build --target wasm32-unknown-unknown
```

3. Import and run

```rust
#[plugin_import(file = "target/wasm32-unknown-unknown/debug/foo_plugin.wasm")]
struct FooPlugin;

#[tokio::main]
async fn main() {
    let runtime = Runtime::<Box<dyn Greeter>>::new().unwrap();
    let handle = runtime.load(FooPlugin).await.unwrap();
    let res = handle.greet().await;
    assert_eq!(res, "Hello From Foo Plugin")
}
```

And you are set!

## Examples

Check out the [examples](./examples/) directory for sample usage of plugy.

## Milestones

| Status | Goal                                                                                                | Labels     |
| :----: | :-------------------------------------------------------------------------------------------------- | ---------- |
|   ✅   | [accept multiple arity (n-ary) in plugin functions](https://github.com/geofmureithi/plugy/issues/2) | `complete` |
|   ✅   | [pass down context between host and guest](https://github.com/geofmureithi/plugy/issues/3)          | `complete`  |

## Functionality

Plugy comprises three fundamental crates, each serving a distinct role in crafting dynamic plugin systems with Rust and WebAssembly:
- core: This crate houses essential components such as bitwise utilities and the guest module, forming the foundation of Plugy's functionality.

- runtime: The runtime crate orchestrates the execution of your plugin system, allowing seamless integration of plugins into your applications.

- macros: The macros crate offers a collection of macros that simplify the generation of bindings and interfaces, streamlining the process of working with dynamic plugins.

## Contributing

Contributions to plugy are welcome! If you find a bug or want to propose a new feature, feel free to create an issue or submit a pull request.

### Thanks to

- [Wasmtime](https://wasmtime.dev/)
- Bincode
- Serde

License

This project is licensed under the GNU General Public License.

<!-- Badges -->

[github-actions-badge]: https://github.com/geofmureithi/plugy/actions/workflows/build.yml/badge.svg
[github-release]: https://github.com/geofmureithi/plugy/releases
[github-release-svg]: https://img.shields.io/github/release/geofmureithi/plugy.svg