https://github.com/second-state/wasmedge_plugin_rust_sdk
https://github.com/second-state/wasmedge_plugin_rust_sdk
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/second-state/wasmedge_plugin_rust_sdk
- Owner: second-state
- Created: 2023-02-20T12:33:13.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-29T09:32:43.000Z (almost 2 years ago)
- Last Synced: 2025-09-04T18:55:58.125Z (9 months ago)
- Language: Rust
- Size: 111 KB
- Stars: 4
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# A Rust SDK for creating WasmEdge Plugins
WasmEdge plugins are packaged host functions that allow Wasm programs running inside WasmEdge to access native functions and vice versa. The plugin system makes WasmEdge extensible.
## Install WasmEdge
```bash
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- -v 0.14.0
```
## Example 1: Hello world -- Wasm calls plugin
This demo shows how to call a host function registered in the plugin from a Wasm program running inside WasmEdge.
### Plugin
The plugin source code is [here](examples/plugin/hello_plugin/). You can build it with
```bash
cd examples/plugin/hello_plugin
cargo build --release
```
The build result is a `libhello_plugin.so` file that you can copy into WasmEdge's plugin directory.
```bash
cp ../../../target/release/libhello_plugin.so /usr/local/lib/wasmedge/
... or ...
cp ../../../target/release/libhello_plugin.so ~/.wasmedge/plugin
```
The plugin provides a native host function `hello()` that prints a line of text to the system console.
### Wasm program
The Wasm program source code is [here](examples/wasm/hello_world/). It compiles into a Wasm program that calls the native host function `hello()` in the plugin. Build it with
```bash
cd examples/wasm/hello_world
cargo build --release
```
Run it with the following command. It calls the `hello()` host function in the plugin to print the text.
```bash
wasmedge ../../../target/wasm32-wasi/release/hello_world.wasm
```
## Example 2: Stateful plugin -- Wasm calls plugin
This demo shows how to manage application state in the plugin, and have the state available to the Wasm programs through host functions.
### Plugin
The plugin source code is [here](examples/plugin/stateful_plugin/). You can build it with
```bash
cd examples/plugin/stateful_plugin
cargo build --release
```
The build result is a `libstateful_plugin.so` file that you can copy into WasmEdge's plugin directory.
```bash
cp ../../../target/release/libstateful_plugin.so /usr/local/lib/wasmedge/
... or ...
cp ../../../target/release/libstateful_plugin.so ~/.wasmedge/plugin
```
The plugin maintains an internal state in a `(x,y)` tuple, and exposes two host functions, `add_x()` and `add_y()` to manipulate the tuple value. The tuple is initialized to `(0,0)` in the plugin source code.
### Wasm program
The Wasm program source code is [here](examples/wasm/call_stateful_plugin/). It compiles into a Wasm program that calls the host functions in the plugin. Build it with
```bash
cd examples/wasm/call_stateful_plugin
cargo build --release
```
Run it with the following command. It calls the `add_x()` and `add_y()` host functions in the plugin to manipulate the tuple data in the plugin.
```bash
wasmedge ../../../target/wasm32-wasi/release/call_stateful_plugin.wasm
```
## Example 3: Memory access -- Plugin calls Wasm
This demo shows how a host function in the plugin accesses memory in the Wasm program. It allows host functions to exchange dynamic data (e.g., strings and arrays) with the Wasm program.
### Plugin
The plugin source code is [here](examples/plugin/memory_access_plugin/). You can build it with
```bash
cd examples/plugin/memory_access_plugin
cargo build --release
```
The build result is a `libmemory_access_plugin.so` file that you can copy into WasmEdge's plugin directory.
```bash
cp ../../../target/release/libmemory_access_plugin.so /usr/local/lib/wasmedge/
... or ...
cp ../../../target/release/libmemory_access_plugin.so ~/.wasmedge/plugin
```
The plugin provides two native host functions
* `get_data()` allows the host function to access and modify memory managed by the Wasm runtime.
* `to_uppercase()` takes the memory space for a string in the Wasm runtime, and turns the in-memory string into upper case.
### Wasm program
The Wasm program source code is [here](examples/wasm/call_memory_access/). It compiles into a Wasm program that calls the native host functions `get_data()` and `to_uppercase()` in the plugin. Build it with
```bash
cd examples/wasm/call_memory_access
cargo build --release
```
Run it with the following command.
```bash
wasmedge ../../../target/wasm32-wasi/release/call_memory_access.wasm
```