Crate wasmer

Wasmer is the most popular WebAssembly runtime for Rust. It supports JIT (Just In Time) and AOT (Ahead Of Time) compilation as well as pluggable compilers suited to your needs.

It’s designed to be safe and secure, and runnable in any kind of environment.

Usage

Here is a small example of using Wasmer to run a WebAssembly module written with its WAT format (textual format):

use wasmer::{Store, Module, Instance, Value, imports};

fn main() -> anyhow::Result<()> {
    let module_wat = r#"
    (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))
    "#;

    let store = Store::default();
    let module = Module::new(&store, &module_wat)?;
    // The module doesn't import anything, so we create an empty import object.
    let import_object = imports! {};
    let instance = Instance::new(&module, &import_object)?;

    let add_one = instance.exports.get_function("add_one")?;
    let result = add_one.call(&[Value::I32(42)])?;
    assert_eq!(result[0], Value::I32(43));

    Ok(())
}

Discover the full collection of examples.

Overview of the Features

Wasmer is not only fast, but also designed to be highly customizable:

• Pluggable engines — An engine is responsible to drive the compilation process and to store the generated executable code somewhere, either:

  • in-memory (with wasmer-engine-universal),
  • in a native shared object file (with wasmer-engine-dylib, .dylib, .so, .dll), then load it with dlopen,
  • in a native static object file (with wasmer-engine-staticlib), in addition to emitting a C header file, which both can be linked against a sandboxed WebAssembly runtime environment for the compiled module with no need for runtime compilation.

• Pluggable compilers — A compiler is used by an engine to transform WebAssembly into executable code:

  • wasmer-compiler-singlepass provides a fast compilation-time but an unoptimized runtime speed,
  • wasmer-compiler-cranelift provides the right balance between compilation-time and runtime performance, useful for development,
  • wasmer-compiler-llvm provides a deeply optimized executable code with the fastest runtime speed, ideal for production.

• Headless mode — Once a WebAssembly module has been compiled, it is possible to serialize it in a file for example, and later execute it with Wasmer with headless mode turned on. Headless Wasmer has no compiler, which makes it more portable and faster to load. It’s ideal for constrainted environments.

• Cross-compilation — Most compilers support cross-compilation. It means it possible to pre-compile a WebAssembly module targetting a different architecture or platform and serialize it, to then run it on the targetted architecture and platform later.

• Run Wasmer in a JavaScript environment — With the js Cargo feature, it is possible to compile a Rust program using Wasmer to WebAssembly. In this context, the resulting WebAssembly module will expect to run in a JavaScript environment, like a browser, Node.js, Deno and so on. In this specific scenario, there is no engines or compilers available, it’s the one available in the JavaScript environment that will be used.

Wasmer ships by default with the Cranelift compiler as its great for development purposes. However, we strongly encourage to use the LLVM compiler in production as it performs about 50% faster, achieving near-native speeds.

Note: if one wants to use multiple compilers at the same time, it’s also possible! One will need to import them directly via each of the compiler crates.

Table of Contents

• WebAssembly Primitives
  • Externs
    • Functions
    • Memories
    • Globals
    • Tables
• Project Layout
  • Engines
  • Compilers
• Cargo Features
• Using Wasmer in a JavaScript environment

WebAssembly Primitives

In order to make use of the power of the wasmer API, it’s important to understand the primitives around which the API is built.

Wasm only deals with a small number of core data types, these data types can be found in the Value type.

In addition to the core Wasm types, the core types of the API are referred to as “externs”.

Externs

An Extern is a type that can be imported or exported from a Wasm module.

To import an extern, simply give it a namespace and a name with the imports macro:

let memory = Memory::new(&store, MemoryType::new(1, None, false)).unwrap();
imports! {
    "env" => {
         "my_function" => Function::new_native(store, || println!("Hello")),
         "memory" => memory,
    }
}

And to access an exported extern, see the Exports API, accessible from any instance via instance.exports:

let memory = instance.exports.get_memory("memory")?;
let memory: &Memory = instance.exports.get("some_other_memory")?;
let add: NativeFunc<(i32, i32), i32> = instance.exports.get_native_function("add")?;
let result = add.call(5, 37)?;
assert_eq!(result, 42);

These are the primary types that the wasmer API uses.

Functions

There are 2 types of functions in wasmer:

1. Wasm functions,
2. Host functions.

A Wasm function is a function defined in a WebAssembly module that can only perform computation without side effects and call other functions.

Wasm functions take 0 or more arguments and return 0 or more results. Wasm functions can only deal with the primitive types defined in Value.

A Host function is any function implemented on the host, in this case in Rust.

Host functions can optionally be created with an environment that implements WasmerEnv. This environment is useful for maintaining host state (for example the filesystem in WASI).

Thus WebAssembly modules by themselves cannot do anything but computation on the core types in Value. In order to make them more useful we give them access to the outside world with imports.

If you’re looking for a sandboxed, POSIX-like environment to execute Wasm in, check out the wasmer-wasi crate for our implementation of WASI, the WebAssembly System Interface.

In the wasmer API we support functions which take their arguments and return their results dynamically, Function, and functions which take their arguments and return their results statically, NativeFunc.

Memories

Memories store data.

In most Wasm programs, nearly all data will live in a Memory.

This data can be shared between the host and guest to allow for more interesting programs.

Globals

A Global is a type that may be either mutable or immutable, and contains one of the core Wasm types defined in Value.

Tables

A Table is an indexed list of items.

Project Layout

The Wasmer project is divided into a number of crates, below is a dependency graph with transitive dependencies removed.

While this crate is the top level API, we also publish crates built on top of this API that you may be interested in using, including:

• wasmer-cache for caching compiled Wasm modules,
• wasmer-emscripten for running Wasm modules compiled to the Emscripten ABI,
• wasmer-wasi for running Wasm modules compiled to the WASI ABI.

The Wasmer project has two major abstractions:

1. Engines,
2. Compilers.

These two abstractions have multiple options that can be enabled with features.

Engines

An engine is a system that uses a compiler to make a WebAssembly module executable.

Compilers

A compiler is a system that handles the details of making a Wasm module executable. For example, by generating native machine code for each Wasm function.

Cargo Features

This crate comes in 2 flavors:

1. sys (enabled), where wasmer will be compiled to a native executable which provides compilers, engines, a full VM etc.
2. js (disabled), where wasmer will be compiled to WebAssembly to run in a JavaScript host (see Using Wasmer in a JavaScript environment).

Consequently, we can group the features by the sys or js features.

Features for the sys feature group (enabled)

The default features can be enabled with the sys-default feature.

The features for the sys feature group can be broken down into 2 kinds: features that enable new functionality and features that set defaults.

The features that enable new functionality are:

• cranelift (disabled), enables Wasmer’s [Cranelift compiler][wasmer-compiler-cranelift],
• llvm (disabled), enables Wasmer’s [LLVM compiler][wasmer-compiler-lvm],
• singlepass (enabled), enables Wasmer’s [Singlepass compiler][wasmer-compiler-singlepass],
• wat (enabled), enables wasmer to parse the WebAssembly text format,
• universal (enabled), enables the Universal engine,
• dylib (disabled), enables the Dylib engine.

The features that set defaults come in sets that are mutually exclusive.

The first set is the default compiler set:

• default-cranelift (disabled), set Wasmer’s Cranelift compiler as the default,
• default-llvm (disabled), set Wasmer’s LLVM compiler as the default,
• default-singlepass (enabled), set Wasmer’s Singlepass compiler as the default.

The next set is the default engine set:

• default-universal (enabled), set the Universal engine as the default,
• default-dylib (disabled), set the Dylib engine as the default.

Features for the js feature group (disabled)

The default features can be enabled with the js-default feature.

Here are the detailed list of features:

• wasm-types-polyfill (disabled), parses the Wasm file, allowing to do type reflection of the inner Wasm types. It adds 100kb to the Wasm bundle (28kb gzipped). It is possible to disable it and to use Module::set_type_hints manually instead for a lightweight alternative. This is needed until the Wasm JS introspection API proposal is adopted by browsers,
• wat (enabled), allows to read a Wasm file in its text format. This feature is normally used only in development environments. It will add around 650kb to the Wasm bundle (120Kb gzipped).

Using Wasmer in a JavaScript environment

Imagine a Rust program that uses this wasmer crate to execute a WebAssembly module. It is possible to compile this Rust progam to WebAssembly by turning on the js Cargo feature of this wasmer crate.

Here is a small example illustrating such a Rust program, and how to compile it with wasm-pack and wasm-bindgen:

#[wasm_bindgen]
pub extern fn do_add_one_in_wasmer() -> i32 {
    let module_wat = r#"
    (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))
    "#;
    let store = Store::default();
    let module = Module::new(&store, &module_wat).unwrap();
    // The module doesn't import anything, so we create an empty import object.
    let import_object = imports! {};
    let instance = Instance::new(&module, &import_object).unwrap();

    let add_one = instance.exports.get_function("add_one").unwrap();
    let result = add_one.call(&[Value::I32(42)]).unwrap();
    assert_eq!(result[0], Value::I32(43));

    result[0].unwrap_i32()
}

Note that it’s the same code as above with the former example. The API is the same!

Then, compile with wasm-pack build. Take care of using the js or js-default Cargo features.

Re-exports

pub use wasmer_compiler::wasmparser;

Modules

vm

The vm module re-exports wasmer-vm types.

Macros

imports

Generate an ImportObject easily with the imports! macro.

Structs

Array

The Array marker type. This type can be used like WasmPtr<T, Array> to get access to methods

Atomically

Atomically.

BaseTunables

Tunable parameters for WebAssembly compilation. This is the reference implementation of the Tunables trait, used by default.

Bytes

Units of WebAssembly memory in terms of 8-bit bytes.

ExportType

A descriptor for an exported WebAssembly value.

Exports

Exports is a special kind of map that allows easily unwrapping the types of instances.

ExportsIterator

An iterator over exports.

Features

Controls which experimental features will be enabled. Features usually have a corresponding WebAssembly proposal.

FrameInfo

Description of a frame in a backtrace for a RuntimeError::trace.

Function

A WebAssembly function instance.

FunctionType

The signature of a function that is either implemented in a Wasm module or exposed to Wasm by the host.

Global

A WebAssembly global instance.

GlobalType

WebAssembly global.

ImportObject

All of the import data used when instantiating.

ImportObjectIterator

Iterator for an ImportObject’s exports.

ImportType

A descriptor for an imported value into a wasm module.

Instance

A WebAssembly Instance is a stateful, executable instance of a WebAssembly Module.

Item

The Item marker type. This is the default and does not usually need to be specified.

LazyInit

Lazily init an item

LocalFunctionIndex

Index type of a function defined locally inside the WebAssembly module.

Memory

A WebAssembly memory instance.

MemoryType

A descriptor for a WebAssembly memory type.

MemoryView

A view into a memory.

MiddlewareError

A error in the middleware.

MiddlewareReaderState

The state of the binary reader. Exposed to middlewares to push their outputs.

Module

A WebAssembly Module contains stateless WebAssembly code that has already been compiled and can be instantiated multiple times.

NamedResolverChain

A Resolver that links two resolvers together in a chain.

NativeFunc

A WebAssembly function that can be called natively (using the Native ABI).

Pages

Units of WebAssembly pages (as specified to be 65,536 bytes).

RuntimeError

A struct representing an aborted instruction execution, with a message indicating the cause.

Singlepass

Store

The store represents all global state that can be manipulated by WebAssembly programs. It consists of the runtime representation of all instances of functions, tables, memories, and globals that have been allocated during the lifetime of the abstract machine.

Table

A WebAssembly table instance.

TableType

A descriptor for a table in a WebAssembly module.

Target

This is the target that we will use for compiling the WebAssembly ModuleInfo, and then run it.

Triple

A target “triple”. Historically such things had three fields, though they’ve added additional fields over time.

Universal

The Universal builder

UniversalArtifact

A compiled wasm module, ready to be instantiated.

UniversalEngine

A WebAssembly Universal Engine.

WasmCell

A mutable Wasm-memory location.

WasmPtr

A zero-cost type that represents a pointer to something in Wasm linear memory.

Enums

Architecture

The “architecture” field, which in some cases also specifies a specific subarchitecture.

CallingConvention

The calling convention, which specifies things like which registers are used for passing arguments, which registers are callee-saved, and so on.

CompileError

The WebAssembly.CompileError object indicates an error during WebAssembly decoding or validation.

CpuFeature

The nomenclature is inspired by the cpuid crate. The list of supported features was initially retrieved from cranelift-native.

DeserializeError

The Deserialize error can occur when loading a compiled Module from a binary.

Export

The value of an export passed from one instance to another.

ExportError

The ExportError can happen when trying to get a specific export Extern from the Instance exports.

ExportIndex

An entity to export.

Extern

An Extern is the runtime representation of an entity that can be imported or exported.

ExternType

A list of all possible types which can be externally referenced from a WebAssembly module.

GlobalInit

Globals are initialized via the const operators or by referring to another import.

HostEnvInitError

An error while initializing the user supplied host env with the WasmerEnv trait.

InstantiationError

An error while instantiating a module.

LinkError

The WebAssembly.LinkError object indicates an error during module instantiation (besides traps from the start function).

MemoryError

Error type describing things that can go wrong when operating on Wasm Memories.

Mutability

Indicator of whether a global is mutable or not

OperatingSystem

The “operating system” field, which sometimes implies an environment, and sometimes isn’t an actual operating system.

ParseCpuFeatureError

The error that can happen while parsing a str to retrieve a CpuFeature.

SerializeError

The Serialize error can occur when serializing a compiled Module into a binary.

Type

A list of all possible value types in WebAssembly.

ValType

A list of all possible value types in WebAssembly.

WasmError

A WebAssembly translation error.

Constants

HOST

The Triple of the current host.

VERSION

Version number of this crate.

WASM_MAX_PAGES

The number of pages we can have before we run out of byte index space.

WASM_MIN_PAGES

The minimum number of pages allowed.

WASM_PAGE_SIZE

WebAssembly page sizes are fixed to be 64KiB. Note: large page support may be added in an opt-in manner in the future.

Traits

ChainableNamedResolver

A trait for chaining resolvers together.

CompilerConfig

The compiler configuration options.

Engine

A unimplemented Wasmer Engine.

Exportable

This trait is used to mark types as gettable from an Instance.

FromToNativeWasmType

A trait to convert a Rust value to a WasmNativeType value, or to convert WasmNativeType value to a Rust value.

FunctionMiddleware

A function middleware specialized for a single function.

HostFunction

The HostFunction trait represents the set of functions that can be used as host function. To uphold this statement, it is necessary for a function to be transformed into a pointer to VMFunctionBody.

LikeNamespace

The LikeNamespace trait represents objects that act as a namespace for imports. For example, an Instance or Namespace could be considered namespaces that could provide imports to an instance.

ModuleMiddleware

A shared builder for function middlewares.

NamedResolver

Import resolver connects imports with available exported values.

Resolver

Import resolver connects imports with available exported values.

StoreObject

A trait represinting any object that lives in the Store.

Tunables

An engine delegates the creation of memories, tables, and globals to a foreign implementor of this trait.

ValueType

Trait for a Value type. A Value type is a type that is always valid and may be safely copied.

WasmTypeList

The WasmTypeList trait represents a tuple (list) of Wasm typed values. It is used to get low-level representation of such a tuple.

WasmerEnv

Trait for initializing the environments passed to host functions after instantiation but before execution.

Functions

is_wasm

Check if the provided bytes are wasm-like

raise_user_trap^⚠

Raises a user-defined trap immediately.

wat2wasm

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module.

Type Definitions

Val

WebAssembly computations manipulate values of basic value types:

Value

WebAssembly computations manipulate values of basic value types:

WasmResult

A convenient alias for a Result that uses WasmError as the error type.

Derive Macros

WasmerEnv

Implement WasmerEnv for your type with #[derive(WasmerEnv)].