Add examples of linking and WASI

Cargo.toml

@@ -67,6 +67,7 @@ members = [
   "crates/misc/rust",
   "crates/wiggle",
   "examples/fib-debug/wasm",
+  "examples/wasi/wasm",
   "fuzz",
 ]
 

crates/misc/run-examples/src/main.rs

@@ -2,13 +2,18 @@ use std::collections::BTreeSet;
 use std::process::Command;
 
 fn main() {
+    let example_to_run = std::env::args().nth(1);
     let examples = std::fs::read_dir("examples").unwrap();
     let examples = examples
-        .map(|e| {
+        .filter_map(|e| {
             let e = e.unwrap();
             let path = e.path();
             let dir = e.metadata().unwrap().is_dir();
-            (path.file_stem().unwrap().to_str().unwrap().to_owned(), dir)
+            if let Some("wat") = path.extension().and_then(|s| s.to_str()) {
+                return None;
+            }
+
+            Some((path.file_stem().unwrap().to_str().unwrap().to_owned(), dir))
         })
         .collect::<BTreeSet<_>>();
 
@@ -21,14 +26,24 @@ fn main() {
         if example == "README" {
             continue;
         }
+        if let Some(example_to_run) = &example_to_run {
+            if !example.contains(&example_to_run[..]) {
+                continue;
+            }
+        }
         if is_dir {
             println!("======== Rust wasm file `{}` ============", example);
+            let target = if example == "fib-debug" {
+                "wasm32-unknown-unknown"
+            } else {
+                "wasm32-wasi"
+            };
             run(Command::new("cargo")
                 .arg("build")
                 .arg("-p")
                 .arg(format!("example-{}-wasm", example))
                 .arg("--target")
-                .arg("wasm32-unknown-unknown"));
+                .arg(target));
         }
         println!("======== Rust example `{}` ============", example);
         run(Command::new("cargo")

docs/SUMMARY.md

@@ -7,6 +7,22 @@
 - [Examples](./examples.md)
   - [Markdown parser](./examples-markdown.md)
   - [Profiling WebAssembly](./examples-profiling.md)
+  - [Embedding in Rust](./examples-rust-embed.md)
+    - [Hello, world!](./examples-rust-hello-world.md)
+    - [Calculating the GCD](./examples-rust-gcd.md)
+    - [Using linear memory](./examples-rust-memory.md)
+    - [WASI](./examples-rust-wasi.md)
+    - [Linking modules](./examples-rust-linking.md)
+    - [Debugging](./examples-rust-debugging.md)
+    - [Using multi-value](./examples-rust-multi-value.md)
+  - [Embedding in C](./examples-c-embed.md)
+    - [Hello, world!](./examples-c-hello-world.md)
+    - [Calculating the GCD](./examples-c-gcd.md)
+    - [Using linear memory](./examples-c-memory.md)
+    - [WASI](./examples-c-wasi.md)
+    - [Linking modules](./examples-c-linking.md)
+    - [Debugging](./examples-c-debugging.md)
+    - [Using multi-value](./examples-c-multi-value.md)
 - [Using WebAssembly from your lanugage](./lang.md)
   - [Python](./lang-python.md)
   - [.NET](./lang-dotnet.md)

docs/embed-rust.md

@@ -3,7 +3,8 @@
 This document shows an example of how to embed Wasmtime using the [Rust
 API][apidoc] to execute a simple wasm program. Be sure to also check out the
 [full API documentation][apidoc] for a full listing of what the [`wasmtime`
-crate][crate] has to offer.
+crate][wasmtime] has to offer and the [book examples for
+Rust](./examples-rust-embed.md) for more information.
 
 [apidoc]: https://bytecodealliance.github.io/wasmtime/api/wasmtime/
 [wasmtime]: https://crates.io/crates/wasmtime

docs/examples-c-debugging.md

@@ -0,0 +1,15 @@
+# Debugging
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/fib-debug/main.c
+
+This example shows off how to set up a module for dynamic runtime debugging via
+a native debugger like GDB or LLDB.
+
+## `main.c`
+
+```c
+{{#include ../examples/fib-debug/main.c}}
+```

docs/examples-c-embed.md

@@ -0,0 +1,12 @@
+# Embedding in C
+
+This section is intended to showcase the C embedding API for Wasmtime. The C
+embedding API is based on the [proposed wasm C embedding API][proposal] (namely
+[`wasm.h`]) and has a few extension headers (like [`wasi.h`] and
+[`wasmtime.h`]) which are intended to eventually become part of the standard
+themselves one day.
+
+[proposal]: https://github.com/webassembly/wasm-c-api
+[`wasm.h`]: https://github.com/WebAssembly/wasm-c-api/blob/master/include/wasm.h
+[`wasi.h`]: https://github.com/bytecodealliance/wasmtime/blob/master/crates/c-api/include/wasi.h
+[`wasmtime.h`]: https://github.com/bytecodealliance/wasmtime/blob/master/crates/c-api/include/wasmtime.h

docs/examples-c-gcd.md

@@ -0,0 +1,22 @@
+# Calculating the GCD
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/gcd.c
+
+This example shows off how run a wasm program which calculates the GCD of two
+numbers.
+
+## `gcd.wat`
+
+```wat
+{{#include ../examples/gcd.wat}}
+```
+
+
+## `gcd.c`
+
+```c
+{{#include ../examples/gcd.c}}
+```

docs/examples-c-hello-world.md

@@ -0,0 +1,22 @@
+# Hello, world!
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/hello.c
+
+This example shows off how to instantiate a simple wasm module and interact with
+it.
+
+## `hello.wat`
+
+```wat
+{{#include ../examples/hello.wat}}
+```
+
+
+## `hello.c`
+
+```c
+{{#include ../examples/hello.c}}
+```

docs/examples-c-linking.md

@@ -0,0 +1,27 @@
+# Linking modules
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/linking.c
+
+This example shows off how to compile and instantiate modules which link
+together.
+
+## `linking1.wat`
+
+```wat
+{{#include ../examples/linking1.wat}}
+```
+
+## `linking2.wat`
+
+```wat
+{{#include ../examples/linking2.wat}}
+```
+
+## `linking.c`
+
+```c
+{{#include ../examples/linking.c}}
+```

docs/examples-c-memory.md

@@ -0,0 +1,24 @@
+# Using linear memory
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/memory.c
+
+This example shows off how to interact with wasm memory in a module. Be sure to
+read the documentation for [`Memory`] as well.
+
+[`Memory`]: https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Memory.html
+
+## `memory.wat`
+
+```wat
+{{#include ../examples/memory.wat}}
+```
+
+
+## `memory.c`
+
+```c
+{{#include ../examples/memory.c}}
+```

docs/examples-c-multi-value.md

@@ -0,0 +1,22 @@
+# Using multi-value
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/multi.c
+
+This example shows off how to interact with a wasm module that uses multi-value
+exports and imports.
+
+## `multi.wat`
+
+```wat
+{{#include ../examples/multi.wat}}
+```
+
+
+## `multi.c`
+
+```c
+{{#include ../examples/multi.c}}
+```

docs/examples-c-wasi.md

@@ -0,0 +1,21 @@
+# WASI
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/wasi/main.c
+
+This example shows off how to instantiate a wasm module using WASI imports.
+
+## Wasm Source code
+
+```rust,ignore
+{{#include ../examples/wasi/wasm/wasi.c}}
+```
+
+
+## `wasi.c`
+
+```c
+{{#include ../examples/wasi/main.c}}
+```

docs/examples-rust-debugging.md

@@ -0,0 +1,15 @@
+# Debugging
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/fib-debug/main.rs
+
+This example shows off how to set up a module for dynamic runtime debugging via
+a native debugger like GDB or LLDB.
+
+## `main.rs`
+
+```rust,ignore
+{{#include ../examples/fib-debug/main.rs}}
+```

docs/examples-rust-embed.md

@@ -0,0 +1,7 @@
+# Embedding in Rust
+
+This section is intended to showcase the Rust embedding API for Wasmtime. This
+is done through the [`wasmtime` crate](https://crates.io/crates/wasmtime). In
+addition to browsing the following examples you can also browse the [specific
+section on Rust embedding](./embed-rust.md) or the [full API
+documentation](https://docs.rs/wasmtime).

docs/examples-rust-gcd.md

@@ -0,0 +1,22 @@
+# Calculating the GCD
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/gcd.rs
+
+This example shows off how run a wasm program which calculates the GCD of two
+numbers.
+
+## `gcd.wat`
+
+```wat
+{{#include ../examples/gcd.wat}}
+```
+
+
+## `gcd.rs`
+
+```rust,ignore
+{{#include ../examples/gcd.rs}}
+```

docs/examples-rust-hello-world.md

@@ -0,0 +1,22 @@
+# Hello, world!
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/hello.rs
+
+This example shows off how to instantiate a simple wasm module and interact with
+it.
+
+## `hello.wat`
+
+```wat
+{{#include ../examples/hello.wat}}
+```
+
+
+## `hello.rs`
+
+```rust,ignore
+{{#include ../examples/hello.rs}}
+```

docs/examples-rust-linking.md

@@ -0,0 +1,27 @@
+# Linking modules
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/linking.rs
+
+This example shows off how to compile and instantiate modules which link
+together.
+
+## `linking1.wat`
+
+```wat
+{{#include ../examples/linking1.wat}}
+```
+
+## `linking2.wat`
+
+```wat
+{{#include ../examples/linking2.wat}}
+```
+
+## `linking.rs`
+
+```rust,ignore
+{{#include ../examples/linking.rs}}
+```

docs/examples-rust-memory.md

@@ -0,0 +1,24 @@
+# Using linear memory
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/examples/memory.rs
+
+This example shows off how to interact with wasm memory in a module. Be sure to
+read the documentation for [`Memory`] as well.
+
+[`Memory`]: https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Memory.html
+
+## `memory.wat`
+
+```wat
+{{#include ../examples/memory.wat}}
+```
+
+
+## `memory.rs`
+
+```rust,ignore
+{{#include ../examples/memory.rs}}
+```