fluencelabs/wasmer
1
0
Fork 0
mirror of https://github.com/fluencelabs/wasmer synced 2025-06-21 12:41:32 +00:00
Code Issues Projects Releases Wiki Activity

Improve runtime docs and add readme (#118)

Browse Source 
* Add crate-level documentation

* add runtime readme

* Fix lint
This commit is contained in:
Lachlan Sneff
2019-01-24 10:51:20 -08:00
committed by GitHub
parent e5c86e00ff
commit a20627964c
4 changed files with 171 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
Cargo.lock generated
View File

@ -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-emscripten 0.2.0",
"wasmer-runtime 0.2.0",
"wasmer-runtime-core 0.2.0",
"wasmer-clif-backend 0.1.1",
"wasmer-emscripten 0.1.0",
"wasmer-runtime 0.1.1",
"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-runtime-core 0.2.0",
"wasmer-clif-backend 0.1.1",
"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-runtime-core 0.2.0",
"wasmer-clif-backend 0.1.1",
"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)",
]

7
lib/runtime-core/src/error.rs
View File

@ -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))

75
lib/runtime/README.md Normal file
View File

@ -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

75
lib/runtime/src/lib.rs
View File

@ -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;