2019-05-12 05:33:02 +00:00
|
|
|
#![deny(unused_imports, unused_variables, unused_unsafe, unreachable_patterns)]
|
2019-05-10 00:53:23 +00:00
|
|
|
|
2019-01-24 18:51:20 +00:00
|
|
|
//! 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,
|
2019-02-02 23:28:50 +00:00
|
|
|
//! Func,
|
2019-01-24 18:51:20 +00:00
|
|
|
//! };
|
|
|
|
//!
|
|
|
|
//! fn main() -> error::Result<()> {
|
|
|
|
//! // We're not importing anything, so make an empty import object.
|
|
|
|
//! let import_object = imports! {};
|
|
|
|
//!
|
2019-02-03 00:02:28 +00:00
|
|
|
//! let mut instance = instantiate(WASM, &import_object)?;
|
2019-01-24 18:51:20 +00:00
|
|
|
//!
|
2019-02-02 23:28:50 +00:00
|
|
|
//! let add_one: Func<i32, i32> = instance.func("add_one")?;
|
2019-01-24 18:51:20 +00:00
|
|
|
//!
|
2019-02-02 23:28:50 +00:00
|
|
|
//! let value = add_one.call(42)?;
|
|
|
|
//!
|
|
|
|
//! assert_eq!(value, 43);
|
2019-01-24 18:51:20 +00:00
|
|
|
//!
|
|
|
|
//! 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
|
|
|
|
|
2019-04-03 03:10:49 +00:00
|
|
|
pub use wasmer_runtime_core::export::Export;
|
2019-01-29 18:25:56 +00:00
|
|
|
pub use wasmer_runtime_core::global::Global;
|
2019-01-23 20:34:15 +00:00
|
|
|
pub use wasmer_runtime_core::import::ImportObject;
|
2019-02-02 23:28:50 +00:00
|
|
|
pub use wasmer_runtime_core::instance::{DynFunc, Instance};
|
2019-01-25 23:33:15 +00:00
|
|
|
pub use wasmer_runtime_core::memory::Memory;
|
2019-01-22 19:02:06 +00:00
|
|
|
pub use wasmer_runtime_core::module::Module;
|
2019-01-29 18:25:56 +00:00
|
|
|
pub use wasmer_runtime_core::table::Table;
|
2019-01-23 20:34:15 +00:00
|
|
|
pub use wasmer_runtime_core::types::Value;
|
|
|
|
pub use wasmer_runtime_core::vm::Ctx;
|
|
|
|
|
2019-02-02 23:28:50 +00:00
|
|
|
pub use wasmer_runtime_core::Func;
|
2019-02-07 00:26:45 +00:00
|
|
|
pub use wasmer_runtime_core::{compile_with, validate};
|
2019-01-29 18:25:56 +00:00
|
|
|
pub use wasmer_runtime_core::{func, imports};
|
2019-01-23 20:34:15 +00:00
|
|
|
|
2019-02-05 07:07:58 +00:00
|
|
|
pub mod memory {
|
|
|
|
pub use wasmer_runtime_core::memory::{Atomic, Atomically, Memory, MemoryView};
|
|
|
|
}
|
|
|
|
|
2019-01-23 23:30:35 +00:00
|
|
|
pub mod wasm {
|
2019-01-29 23:44:15 +00:00
|
|
|
//! Various types exposed by the Wasmer Runtime.
|
2019-01-29 18:25:56 +00:00
|
|
|
pub use wasmer_runtime_core::global::Global;
|
|
|
|
pub use wasmer_runtime_core::table::Table;
|
2019-04-03 03:10:49 +00:00
|
|
|
pub use wasmer_runtime_core::types::{
|
|
|
|
FuncSig, GlobalDescriptor, MemoryDescriptor, TableDescriptor, Type, Value,
|
|
|
|
};
|
2019-01-23 20:34:15 +00:00
|
|
|
}
|
|
|
|
|
2019-02-07 00:26:45 +00:00
|
|
|
pub mod error {
|
2019-02-21 19:47:28 +00:00
|
|
|
pub use wasmer_runtime_core::cache::Error as CacheError;
|
2019-02-07 00:26:45 +00:00
|
|
|
pub use wasmer_runtime_core::error::*;
|
|
|
|
}
|
|
|
|
|
2019-01-29 23:44:15 +00:00
|
|
|
pub mod units {
|
|
|
|
//! Various unit types.
|
|
|
|
pub use wasmer_runtime_core::units::{Bytes, Pages};
|
|
|
|
}
|
|
|
|
|
2019-02-21 19:47:28 +00:00
|
|
|
pub mod cache;
|
2019-02-07 00:26:45 +00:00
|
|
|
|
2019-03-27 21:01:27 +00:00
|
|
|
use wasmer_runtime_core::backend::{Compiler, CompilerConfig};
|
2019-02-07 00:26:45 +00:00
|
|
|
|
2019-01-23 20:34:15 +00:00
|
|
|
/// Compile WebAssembly binary code into a [`Module`].
|
|
|
|
/// This function is useful if it is necessary to
|
|
|
|
/// compile a module before it can be instantiated
|
|
|
|
/// (otherwise, the [`instantiate`] function should be used).
|
|
|
|
///
|
|
|
|
/// [`Module`]: struct.Module.html
|
|
|
|
/// [`instantiate`]: fn.instantiate.html
|
2019-01-22 19:02:06 +00:00
|
|
|
///
|
2019-01-23 20:34:15 +00:00
|
|
|
/// # Params:
|
2019-01-22 19:02:06 +00:00
|
|
|
/// * `wasm`: A `&[u8]` containing the
|
|
|
|
/// binary code of the wasm module you want to compile.
|
2019-01-23 20:34:15 +00:00
|
|
|
/// # Errors:
|
|
|
|
/// If the operation fails, the function returns `Err(error::CompileError::...)`.
|
|
|
|
pub fn compile(wasm: &[u8]) -> error::CompileResult<Module> {
|
2019-05-14 23:19:58 +00:00
|
|
|
wasmer_runtime_core::compile_with(&wasm[..], &default_compiler())
|
2019-01-21 22:43:04 +00:00
|
|
|
}
|
|
|
|
|
2019-03-27 21:08:17 +00:00
|
|
|
/// The same as `compile` but takes a `CompilerConfig` for the purpose of
|
|
|
|
/// changing the compiler's behavior
|
2019-03-27 21:01:27 +00:00
|
|
|
pub fn compile_with_config(
|
|
|
|
wasm: &[u8],
|
|
|
|
compiler_config: CompilerConfig,
|
|
|
|
) -> error::CompileResult<Module> {
|
2019-05-14 23:19:58 +00:00
|
|
|
wasmer_runtime_core::compile_with_config(&wasm[..], &default_compiler(), compiler_config)
|
2019-03-27 21:01:27 +00:00
|
|
|
}
|
|
|
|
|
2019-04-11 21:34:54 +00:00
|
|
|
/// The same as `compile_with_config` but takes a `Compiler` for the purpose of
|
|
|
|
/// changing the backend.
|
|
|
|
pub fn compile_with_config_with(
|
|
|
|
wasm: &[u8],
|
|
|
|
compiler_config: CompilerConfig,
|
|
|
|
compiler: &dyn Compiler,
|
|
|
|
) -> error::CompileResult<Module> {
|
|
|
|
wasmer_runtime_core::compile_with_config(&wasm[..], compiler, compiler_config)
|
|
|
|
}
|
|
|
|
|
2019-01-23 20:34:15 +00:00
|
|
|
/// Compile and instantiate WebAssembly code without
|
|
|
|
/// creating a [`Module`].
|
|
|
|
///
|
|
|
|
/// [`Module`]: struct.Module.html
|
2019-01-22 19:02:06 +00:00
|
|
|
///
|
2019-01-23 20:34:15 +00:00
|
|
|
/// # Params:
|
2019-01-22 19:02:06 +00:00
|
|
|
/// * `wasm`: A `&[u8]` containing the
|
|
|
|
/// binary code of the wasm module you want to compile.
|
|
|
|
/// * `import_object`: An object containing the values to be imported
|
|
|
|
/// into the newly-created Instance, such as functions or
|
2019-01-23 20:34:15 +00:00
|
|
|
/// Memory objects. There must be one matching property
|
2019-01-22 19:02:06 +00:00
|
|
|
/// for each declared import of the compiled module or else a
|
2019-01-23 20:34:15 +00:00
|
|
|
/// LinkError is thrown.
|
|
|
|
/// # Errors:
|
2019-01-22 19:02:06 +00:00
|
|
|
/// If the operation fails, the function returns a
|
|
|
|
/// `error::CompileError`, `error::LinkError`, or
|
|
|
|
/// `error::RuntimeError` (all combined into an `error::Error`),
|
|
|
|
/// depending on the cause of the failure.
|
2019-02-02 23:58:33 +00:00
|
|
|
pub fn instantiate(wasm: &[u8], import_object: &ImportObject) -> error::Result<Instance> {
|
2019-01-22 19:02:06 +00:00
|
|
|
let module = compile(wasm)?;
|
2019-03-27 21:01:27 +00:00
|
|
|
module.instantiate(import_object)
|
2019-01-09 02:57:28 +00:00
|
|
|
}
|
2019-01-22 23:26:56 +00:00
|
|
|
|
2019-03-15 10:39:21 +00:00
|
|
|
/// Get a single instance of the default compiler to use.
|
2019-05-14 23:19:58 +00:00
|
|
|
pub fn default_compiler() -> impl Compiler {
|
2019-03-08 03:11:15 +00:00
|
|
|
#[cfg(feature = "llvm")]
|
|
|
|
use wasmer_llvm_backend::LLVMCompiler as DefaultCompiler;
|
|
|
|
|
2019-04-11 19:44:03 +00:00
|
|
|
#[cfg(feature = "singlepass")]
|
|
|
|
use wasmer_singlepass_backend::SinglePassCompiler as DefaultCompiler;
|
2019-03-18 08:15:48 +00:00
|
|
|
|
2019-04-11 19:44:03 +00:00
|
|
|
#[cfg(not(any(feature = "llvm", feature = "singlepass")))]
|
2019-03-18 08:15:48 +00:00
|
|
|
use wasmer_clif_backend::CraneliftCompiler as DefaultCompiler;
|
2019-02-07 00:26:45 +00:00
|
|
|
|
2019-05-14 23:19:58 +00:00
|
|
|
DefaultCompiler::new()
|
2019-02-07 00:26:45 +00:00
|
|
|
}
|
|
|
|
|
2019-01-22 23:26:56 +00:00
|
|
|
/// The current version of this crate
|
|
|
|
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
|