Improve runtime docs and add readme (#118)

* Add crate-level documentation

* add runtime readme

* Fix lint

Cargo.lock

@@ -489,15 +489,15 @@ dependencies = [
  "glob 0.2.11 (registry+https://github.com/rust-lang/crates.io-index)",
  "structopt 0.2.14 (registry+https://github.com/rust-lang/crates.io-index)",
  "wabt 0.7.2 (registry+https://github.com/rust-lang/crates.io-index)",
- "wasmer-clif-backend 0.2.0",
+ "wasmer-clif-backend 0.1.1",
- "wasmer-emscripten 0.2.0",
+ "wasmer-emscripten 0.1.0",
- "wasmer-runtime 0.2.0",
+ "wasmer-runtime 0.1.1",
- "wasmer-runtime-core 0.2.0",
+ "wasmer-runtime-core 0.1.1",
 ]
 
 [[package]]
 name = "wasmer-clif-backend"
-version = "0.2.0"
+version = "0.1.1"
 dependencies = [
  "byteorder 1.2.7 (registry+https://github.com/rust-lang/crates.io-index)",
  "cranelift-codegen 0.26.0 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -507,13 +507,13 @@ dependencies = [
  "hashbrown 0.1.7 (registry+https://github.com/rust-lang/crates.io-index)",
  "nix 0.12.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "target-lexicon 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
- "wasmer-runtime-core 0.2.0",
+ "wasmer-runtime-core 0.1.1",
  "wasmparser 0.23.0 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
 [[package]]
 name = "wasmer-emscripten"
-version = "0.2.0"
+version = "0.1.0"
 dependencies = [
  "byteorder 1.2.7 (registry+https://github.com/rust-lang/crates.io-index)",
  "glob 0.2.11 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -521,21 +521,21 @@ dependencies = [
  "libc 0.2.44 (git+https://github.com/rust-lang/libc)",
  "time 0.1.41 (registry+https://github.com/rust-lang/crates.io-index)",
  "wabt 0.7.2 (registry+https://github.com/rust-lang/crates.io-index)",
- "wasmer-clif-backend 0.2.0",
+ "wasmer-clif-backend 0.1.1",
- "wasmer-runtime-core 0.2.0",
+ "wasmer-runtime-core 0.1.1",
 ]
 
 [[package]]
 name = "wasmer-runtime"
-version = "0.2.0"
+version = "0.1.1"
 dependencies = [
- "wasmer-clif-backend 0.2.0",
+ "wasmer-clif-backend 0.1.1",
- "wasmer-runtime-core 0.2.0",
+ "wasmer-runtime-core 0.1.1",
 ]
 
 [[package]]
 name = "wasmer-runtime-core"
-version = "0.2.0"
+version = "0.1.1"
 dependencies = [
  "errno 0.2.4 (registry+https://github.com/rust-lang/crates.io-index)",
  "field-offset 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -543,7 +543,7 @@ dependencies = [
  "nix 0.12.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "page_size 0.4.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "wabt 0.7.2 (registry+https://github.com/rust-lang/crates.io-index)",
- "wasmer-clif-backend 0.2.0",
+ "wasmer-clif-backend 0.1.1",
  "wasmparser 0.23.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "winapi 0.3.6 (registry+https://github.com/rust-lang/crates.io-index)",
 ]

lib/runtime-core/src/error.rs

@@ -140,6 +140,7 @@ pub enum Error {
     CompileError(CompileError),
     LinkError(Vec<LinkError>),
     RuntimeError(RuntimeError),
+    ResolveError(ResolveError),
     CallError(CallError),
 }
 
@@ -167,6 +168,12 @@ impl From<Box<RuntimeError>> for Box<Error> {
     }
 }
 
+impl From<Box<ResolveError>> for Box<Error> {
+    fn from(resolve_err: Box<ResolveError>) -> Self {
+        Box::new(Error::ResolveError(*resolve_err))
+    }
+}
+
 impl From<Box<CallError>> for Box<Error> {
     fn from(call_err: Box<CallError>) -> Self {
         Box::new(Error::CallError(*call_err))

lib/runtime/README.md

@@ -0,0 +1,75 @@
+# Wasmer-Runtime
+
+Wasmer-runtime is a library that makes embedding WebAssembly
+in your application easy, efficient, and safe.
+
+# How to use Wasmer-Runtime
+
+The easiest way is to use the [`instantiate`] function to create an [`Instance`].
+Then you can use [`call`] or [`func`] and then [`call`][func.call] to call an exported function safely.
+
+[`instantiate`]: https://docs.rs/wasmer-runtime/*/wasmer_runtime/fn.instantiate.html
+[`Instance`]: https://docs.rs/wasmer-runtime/*/wasmer_runtime/struct.Instance.html
+[`call`]: https://docs.rs/wasmer-runtime/*/wasmer_runtime/struct.Instance.html#method.call
+[`func`]: https://docs.rs/wasmer-runtime/*/wasmer_runtime/struct.Instance.html#method.func
+[func.call]: https://docs.rs/wasmer-runtime/*/wasmer_runtime/struct.Function.html#method.call
+
+## Here's an example:
+
+Given this WebAssembly:
+
+```wat
+(module
+  (type $t0 (func (param i32) (result i32)))
+  (func $add_one (export "add_one") (type $t0) (param $p0 i32) (result i32)
+    get_local $p0
+    i32.const 1
+    i32.add))
+```
+
+compiled into wasm bytecode, we can call the exported "add_one" function:
+
+```rust
+static WASM: &'static [u8] = &[
+    // The module above compiled to bytecode goes here.
+    0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x01, 0x06, 0x01, 0x60,
+    0x01, 0x7f, 0x01, 0x7f, 0x03, 0x02, 0x01, 0x00, 0x07, 0x0b, 0x01, 0x07,
+    0x61, 0x64, 0x64, 0x5f, 0x6f, 0x6e, 0x65, 0x00, 0x00, 0x0a, 0x09, 0x01,
+    0x07, 0x00, 0x20, 0x00, 0x41, 0x01, 0x6a, 0x0b, 0x00, 0x1a, 0x04, 0x6e,
+    0x61, 0x6d, 0x65, 0x01, 0x0a, 0x01, 0x00, 0x07, 0x61, 0x64, 0x64, 0x5f,
+    0x6f, 0x6e, 0x65, 0x02, 0x07, 0x01, 0x00, 0x01, 0x00, 0x02, 0x70, 0x30,
+];
+
+use wasmer_runtime::{
+    instantiate,
+    Value,
+    imports,
+    error,
+};
+
+fn main() -> error::Result<()> {
+    // We're not importing anything, so make an empty import object.
+    let import_object = imports! {};
+
+    let mut instance = instantiate(WASM, import_object)?;
+
+    let values = instance
+        .func("add_one")?
+        .call(&[Value::I32(42)])?;
+
+    assert_eq!(values[0], Value::I32(43));
+    
+    Ok(())
+}
+```
+
+# Additional Notes:
+
+The `wasmer-runtime` is build to support compiler multiple backends.
+Currently, we support the [Cranelift] compiler with the [`wasmer-clif-backend`] crate.
+
+You can specify the compiler you wish to use with the [`compile_with`] function.
+
+[Cranelift]: https://github.com/CraneStation/cranelift
+[`wasmer-clif-backend`]: https://crates.io/crates/wasmer-clif-backend
+[`compile_with`]: https://docs.rs/wasmer-runtime/*/wasmer_runtime/fn.compile_with.html

lib/runtime/src/lib.rs

@@ -1,3 +1,78 @@
+//! Wasmer-runtime is a library that makes embedding WebAssembly
+//! in your application easy, efficient, and safe.
+//!
+//! # How to use Wasmer-Runtime
+//!
+//! The easiest way is to use the [`instantiate`] function to create an [`Instance`].
+//! Then you can use [`call`] or [`func`] and then [`call`][func.call] to call an exported function safely.
+//!
+//! [`instantiate`]: fn.instantiate.html
+//! [`Instance`]: struct.Instance.html
+//! [`call`]: struct.Instance.html#method.call
+//! [`func`]: struct.Instance.html#method.func
+//! [func.call]: struct.Function.html#method.call
+//!
+//! ## Here's an example:
+//!
+//! Given this WebAssembly:
+//!
+//! ```wat
+//! (module
+//!   (type $t0 (func (param i32) (result i32)))
+//!   (func $add_one (export "add_one") (type $t0) (param $p0 i32) (result i32)
+//!     get_local $p0
+//!     i32.const 1
+//!     i32.add))
+//! ```
+//!
+//! compiled into wasm bytecode, we can call the exported "add_one" function:
+//!
+//! ```
+//! static WASM: &'static [u8] = &[
+//!     // The module above compiled to bytecode goes here.
+//!     // ...
+//! #   0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x01, 0x06, 0x01, 0x60,
+//! #   0x01, 0x7f, 0x01, 0x7f, 0x03, 0x02, 0x01, 0x00, 0x07, 0x0b, 0x01, 0x07,
+//! #   0x61, 0x64, 0x64, 0x5f, 0x6f, 0x6e, 0x65, 0x00, 0x00, 0x0a, 0x09, 0x01,
+//! #   0x07, 0x00, 0x20, 0x00, 0x41, 0x01, 0x6a, 0x0b, 0x00, 0x1a, 0x04, 0x6e,
+//! #   0x61, 0x6d, 0x65, 0x01, 0x0a, 0x01, 0x00, 0x07, 0x61, 0x64, 0x64, 0x5f,
+//! #   0x6f, 0x6e, 0x65, 0x02, 0x07, 0x01, 0x00, 0x01, 0x00, 0x02, 0x70, 0x30,
+//! ];
+//!
+//! use wasmer_runtime::{
+//!     instantiate,
+//!     Value,
+//!     imports,
+//!     error,
+//! };
+//!
+//! fn main() -> error::Result<()> {
+//!     // We're not importing anything, so make an empty import object.
+//!     let import_object = imports! {};
+//!
+//!     let mut instance = instantiate(WASM, import_object)?;
+//!
+//!     let values = instance
+//!         .func("add_one")?
+//!         .call(&[Value::I32(42)])?;
+//!
+//!     assert_eq!(values[0], Value::I32(43));
+//!     
+//!     Ok(())
+//! }
+//! ```
+//!
+//! # Additional Notes:
+//!
+//! The `wasmer-runtime` is build to support compiler multiple backends.
+//! Currently, we support the [Cranelift] compiler with the [`wasmer-clif-backend`] crate.
+//!
+//! You can specify the compiler you wish to use with the [`compile_with`] function.
+//!
+//! [Cranelift]: https://github.com/CraneStation/cranelift
+//! [`wasmer-clif-backend`]: https://crates.io/crates/wasmer-clif-backend
+//! [`compile_with`]: fn.compile_with.html
+
 pub use wasmer_runtime_core::import::ImportObject;
 pub use wasmer_runtime_core::instance::{Function, Instance};
 pub use wasmer_runtime_core::module::Module;