Add extending WASI plugin example

Cargo.lock

@@ -1317,6 +1317,10 @@ name = "plain"
 version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 
+[[package]]
+name = "plugin-for-example"
+version = "0.1.0"
+
 [[package]]
 name = "podio"
 version = "0.1.6"

Cargo.toml

@@ -33,7 +33,7 @@ wasmer-llvm-backend = { path = "lib/llvm-backend", optional = true }
 wasmer-wasi = { path = "lib/wasi", optional = true }
 
 [workspace]
-members = ["lib/clif-backend", "lib/singlepass-backend", "lib/runtime", "lib/runtime-abi", "lib/runtime-core", "lib/emscripten", "lib/spectests", "lib/win-exception-handler", "lib/runtime-c-api", "lib/llvm-backend", "lib/wasi"]
+members = ["lib/clif-backend", "lib/singlepass-backend", "lib/runtime", "lib/runtime-abi", "lib/runtime-core", "lib/emscripten", "lib/spectests", "lib/win-exception-handler", "lib/runtime-c-api", "lib/llvm-backend", "lib/wasi", "examples/plugin-for-example"]
 
 [build-dependencies]
 wabt = "0.7.2"
@@ -49,3 +49,7 @@ fast-tests = []
 "backend:singlepass" = ["wasmer-singlepass-backend"]
 wasi = ["wasmer-wasi"]
 vfs = ["wasmer-runtime-abi"]
+
+[[example]]
+name = "plugin"
+crate-type = ["bin"]

examples/plugin-for-example/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "plugin-for-example"
+version = "0.1.0"
+authors = ["The Wasmer Engineering Team <enigneering@wasmer.io>"]
+edition = "2018"
+
+[dependencies]

examples/plugin-for-example/README.md

@@ -0,0 +1,33 @@
+# WASI plugin example
+
+In this example we extend the imports of Wasmer's WASI ABI to demonstrate how custom plugins work.
+
+See the `wasmer/examples/plugin.rs` file for the source code of the host system.
+
+## Compiling
+
+```
+# Install an up to date version of Rust nightly
+# Add the target
+rustup target add wasm32-unknown-wasi
+# build it
+cargo build --release --target=wasm32-unknown-wasi
+# copy it to examples folder
+cp ../../target/wasm32-unknown-wasi/release/plugin-for-example.wasm ../
+```
+
+## Running
+```
+# Go back to top level Wasmer dir
+cd ..
+# Run the example
+cargo run --example plugin
+```
+
+## Explanation
+
+In this example, we instantiate a system with an extended (WASI)[wasi] ABI, allowing our program to rely on Wasmer's implementation of the syscalls defined by WASI as well as our own that we made.  This allows us to use the full power of an existing ABI, like WASI, and give it super-powers for our specific use case.
+
+Because the Rust WASI doesn't support the crate type of `cdylib`, we have to include a main function which we don't use.
+
+[wasi]: https://hacks.mozilla.org/2019/03/standardizing-wasi-a-webassembly-system-interface/

examples/plugin-for-example/src/bin.rs

@@ -0,0 +1,14 @@
+extern "C" {
+    fn it_works() -> i32;
+}
+
+#[no_mangle]
+pub fn plugin_entrypoint(n: i32) -> i32 {
+    println!("It works from inside WASI");
+    let result = unsafe { it_works() };
+    result + n
+}
+
+pub fn main() {
+    println!("hello");
+}

examples/plugin-for-example/src/main.rs

@@ -0,0 +1,12 @@
+extern "C" {
+    fn it_works() -> i32;
+}
+
+#[no_mangle]
+pub fn plugin_entrypoint(n: i32) -> i32 {
+    println!("Hello from inside WASI");
+    let result = unsafe { it_works() };
+    result + n
+}
+
+pub fn main() {}

examples/plugin.rs

@@ -0,0 +1,28 @@
+use wasmer_runtime::{func, imports, instantiate};
+use wasmer_runtime_core::vm::Ctx;
+use wasmer_wasi::generate_import_object;
+
+static PLUGIN_WASM: &'static [u8] = include_bytes!("plugin-for-example.wasm");
+
+fn it_works(_ctx: &mut Ctx) -> i32 {
+    println!("Hello from outside WASI");
+    5
+}
+
+fn main() {
+    // WASI imports
+    let mut base_imports = generate_import_object(vec![], vec![], vec![]);
+    // env is the default namespace for extern functions
+    let custom_imports = imports! {
+        "env" => {
+            "it_works" => func!(it_works),
+        },
+    };
+    base_imports.extend(custom_imports);
+    let instance =
+        instantiate(PLUGIN_WASM, &base_imports).expect("failed to instantiate wasm module");
+
+    let entry_point = instance.func::<(i32), i32>("plugin_entrypoint").unwrap();
+    let result = entry_point.call(2).expect("failed to execute plugin");
+    println!("result: {}", result);
+}