Merge pull request #724 from wasmx/rust-readme

rust: add example code and mention in the readme

README.md

@@ -14,7 +14,7 @@ Fizzy aims to be a fast, deterministic, and pedantic WebAssembly interpreter wri
 
 I) Code quality
 - [x] Clean and modern C++17 codebase without external dependencies
-- [ ] Easily embeddable (*and take part of the standardisation of the "C/C++ embedding API"*)
+- [x] Easily embeddable (*and take part of the standardisation of the "C/C++ embedding API"*)
 
 II) Simplicity
 - [x] Only implement WebAssembly 1.0 (and none of the proposals)
@@ -79,6 +79,9 @@ find_package(fizzy CONFIG REQUIRED)
 target_link_libraries(app_name PRIVATE fizzy::fizzy)
 ```
 
+Fizzy also has a Rust binding. It is published on [crates.io](https://crates.io/crates/fizzy) and the
+official documentation with examples can be read on [docs.rs](https://docs.rs/fizzy/).
+
 ## WASI
 
 Building with the `FIZZY_WASI` option will output a `fizzy-wasi` binary implementing

bindings/rust/src/lib.rs

@@ -2,7 +2,39 @@
 // Copyright 2019-2020 The Fizzy Authors.
 // SPDX-License-Identifier: Apache-2.0
 
-//! This is a Rust interface to [Fizzy](https://github.com/wasmx/fizzy), a WebAssembly virtual machine.
+//! This is a Rust interface to [Fizzy](https://github.com/wasmx/fizzy), a fast, deterministic, and pedantic WebAssembly interpreter.
+//!
+//! # Examples
+//!
+//! This is a generic example for parsing and instantiating a module, and executing a simple function with inputs and an output.
+//!
+//! ```
+//! extern crate fizzy;
+//!
+//! fn main() {
+//!     // This wasm binary exports a single sum(u32, u32) -> u32 function.
+//!     let wasm = [
+//!         0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x01, 0x07, 0x01, 0x60, 0x02, 0x7f,
+//!         0x7f, 0x01, 0x7f, 0x03, 0x02, 0x01, 0x00, 0x07, 0x07, 0x01, 0x03, 0x73, 0x75, 0x6d,
+//!         0x00, 0x00, 0x0a, 0x09, 0x01, 0x07, 0x00, 0x20, 0x00, 0x20, 0x01, 0x6a, 0x0b,
+//!     ];
+//!     let module = fizzy::parse(&wasm).expect("parsing failed");
+//!     let mut instance = module.instantiate().expect("instantiation failed");
+//!     let result = instance
+//!         .execute(
+//!             "sum",
+//!             &[fizzy::TypedValue::U32(42), fizzy::TypedValue::U32(24)],
+//!             0,
+//!         )
+//!         .expect("execution failed");
+//!     let result = result
+//!         .value()
+//!         .expect("return value expected")
+//!         .as_u32()
+//!         .expect("u32 expected as a return type");
+//!     assert_eq!(result, 66);
+//! }
+//! ```
 
 mod sys;
 

circle.yml

@@ -666,7 +666,10 @@ jobs:
           command: RUSTFLAGS="-Z sanitizer=address" cargo +nightly build --target x86_64-unknown-linux-gnu
       - run:
           name: Test (debug mode)
-          command: RUSTFLAGS="-Z sanitizer=address -C opt-level=0" cargo +nightly test --target x86_64-unknown-linux-gnu
+          command: |
+            export RUSTFLAGS="-Z sanitizer=address -C opt-level=0"
+            export RUSTDOCFLAGS=$RUSTFLAGS
+            cargo +nightly test --target x86_64-unknown-linux-gnu
 
   bindings-rust-coverage:
     executor: rust