diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index d4314339c7..0a32aa96a9 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -30,6 +30,8 @@ jobs: curl -L https://github.com/rust-lang-nursery/mdBook/releases/download/v0.3.1/mdbook-v0.3.1-x86_64-unknown-linux-gnu.tar.gz | tar xzf - echo ::add-path::`pwd` - run: (cd docs && mdbook build) + - run: cargo build -p wasmtime + - run: (cd docs && mdbook test -L ../target/debug/deps) - uses: actions/upload-artifact@v1 with: name: doc-book diff --git a/docs/cli-cache.md b/docs/cli-cache.md index c8c9f1680e..f8c6622971 100644 --- a/docs/cli-cache.md +++ b/docs/cli-cache.md @@ -2,7 +2,7 @@ The configuration file uses the [toml] format. You can create a configuration file at the default location with: -``` +```sh $ wasmtime config new ``` It will print the location regardless of the success. diff --git a/docs/embed-rust.md b/docs/embed-rust.md index b2c4184fb6..3ec437a518 100644 --- a/docs/embed-rust.md +++ b/docs/embed-rust.md @@ -18,7 +18,7 @@ Let's create a simple WebAssembly file with a single exported function that retu # Create rust project -``` +```sh $ cargo new --bin wasmtime_hello $ cd wasmtime_hello $ cp $WASM_FILES/hello.wasm . @@ -26,7 +26,7 @@ $ cp $WASM_FILES/hello.wasm . We will be using the wasmtime engine/API to run the wasm file, so we will add the dependency to `Cargo.toml`: -``` +```toml [dependencies] wasmtime = "" ``` @@ -36,6 +36,7 @@ where "" is the current version number of the `wasmtime` crate. It is time to add code to the `src/main.rs`. First, storage needs to be activated: ```rust +# extern crate wasmtime; use wasmtime::*; let store = Store::default(); @@ -43,18 +44,32 @@ let store = Store::default(); The `hello.wasm` can be read from the file system and provided to the `Module` object constructor as `&[u8]`: -```rust +```rust,no_run +# extern crate wasmtime; +# use wasmtime::*; +# fn main() -> Result<(), Box> { +# let store = Store::default(); use std::fs::read; -let hello_wasm = read("hello.wasm").expect("wasm file"); +let hello_wasm = read("hello.wasm")?; -let module = Module::new(&store, &hello_wasm).expect("wasm module"); +let module = Module::new(&store, &hello_wasm)?; +# Ok(()) +# } ``` -The module instance can now be created. Normally, you would provide exports, but in this case, there are none required: +The module instance can now be created. Normally, you would provide imports, but +in this case, there are none required: ```rust -let instance = Instance::new(&module, &[]).expect("wasm instance"); +# extern crate wasmtime; +# use wasmtime::*; +# fn main() -> Result<(), Box> { +# let store = Store::default(); +# let module = Module::new(&store, "(module)")?; +let instance = Instance::new(&module, &[])?; +# Ok(()) +# } ``` Everything is set. If a WebAssembly module has a start function -- it was run. @@ -62,34 +77,74 @@ The instance's exports can be used at this point. wasmtime provides functions to get an export by name, and ensure that it's a function: ```rust +# extern crate wasmtime; +# use wasmtime::*; +# fn main() -> Result<(), Box> { +# let store = Store::default(); +# let module = Module::new(&store, r#"(module (func (export "answer")))"#)?; +# let instance = Instance::new(&module, &[])?; let answer = instance.get_export("answer").expect("answer").func().expect("function"); +# Ok(()) +# } ``` -The exported function can be called using the `call` method. The exported "answer" function accepts no parameters and returns a single `i32` value. +The exported function can be called using the `call` method. The exported +"answer" function accepts no parameters and returns a single `i32` value. ```rust -let result = answer.call(&[]).expect("success"); +# extern crate wasmtime; +# use wasmtime::*; +# fn main() -> Result<(), Box> { +# let store = Store::default(); +# let module = Module::new(&store, r#"(module (func (export "answer") (result i32) i32.const 2))"#)?; +# let instance = Instance::new(&module, &[])?; +# let answer = instance.get_export("answer").expect("answer").func().expect("function"); +let result = answer.call(&[])?; println!("Answer: {:?}", result[0].i32()); +# Ok(()) +# } ``` -The names of the WebAssembly module's imports and exports can be discovered by means of module's corresponding methods. +Since we know the signature of the function ahead of time, we can also assert +its signature and call the function directly without doing conversions: + +```rust +# extern crate wasmtime; +# use wasmtime::*; +# fn main() -> Result<(), Box> { +# let store = Store::default(); +# let module = Module::new(&store, r#"(module (func (export "answer") (result i32) i32.const 2))"#)?; +# let instance = Instance::new(&module, &[])?; +# let answer = instance.get_export("answer").expect("answer").func().expect("function"); +let answer = answer.get0::()?; +let result: i32 = answer()?; +println!("Answer: {}", result); +# Ok(()) +# } +``` + +The names of the WebAssembly module's imports and exports can be discovered by +means of module's corresponding methods. # src/main.rs -```rust +```rust,no_run +# extern crate wasmtime; +use std::error::Error; use std::fs::read; use wasmtime::*; -fn main() { +fn main() -> Result<(), Box> { let store = Store::default(); - let wasm = read("hello.wasm").expect("wasm file"); + let wasm = read("hello.wasm")?; - let module = Module::new(&store, &wasm).expect("wasm module"); - let instance = Instance::new(&module, &[]).expect("wasm instance"); + let module = Module::new(&store, &wasm)?; + let instance = Instance::new(&module, &[])?; let answer = instance.get_export("answer").expect("answer").func().expect("function"); - let result = answer.call(&[]).expect("success"); + let result = answer.call(&[])?; println!("Answer: {:?}", result[0].i32()); + Ok(()) } ``` diff --git a/docs/wasm-rust.md b/docs/wasm-rust.md index d9e0c1fa3f..9f3f0c8f14 100644 --- a/docs/wasm-rust.md +++ b/docs/wasm-rust.md @@ -164,7 +164,7 @@ wasm-bindgen = "0.2.54" Using this crate, we can then update our `src/lib.rs` with the following: -```rust +```rust,ignore use wasm_bindgen::prelude::*; #[wasm_bindgen] @@ -248,6 +248,7 @@ Only functions can be imported in Rust at this time, and they can be imported via raw interfaces like: ```rust +# struct MyStruct; #[link(wasm_import_module = "the-wasm-import-module")] extern "C" { // imports the name `foo` from `the-wasm-import-module` @@ -270,7 +271,7 @@ extern "C" { When you're using `wasm-bindgen` you would instead use: -```rust +```rust,ignore use wasm_bindgen::prelude::*; #[wasm_bindgen(module = "the-wasm-import-module")]