wasmer/docs/migration_to_3.0.0.md

Migrating from Wasmer 2.x to Wasmer 3.0.0

This document will describe the differences between Wasmer 2.x and Wasmer 3.0.0 and provide examples to make migrating to the new API as simple as possible.

Table of Contents

• Rationale for changes in 3.0.0
• How to use Wasmer 3.0.0
  • Installing Wasmer CLI
  • Using Wasmer 3.0.0
• Project structure
• Differences
  • Managing imports

Rationale for changes in 3.0.0

This version introduces the following changes to make the Wasmer API more ergonomic and safe:

1. ImportsObject and the traits Resolver, NamedResolver, etc have been removed and replaced with a single simple type Imports. This reduces the complexity of setting up an Instance. The helper macro imports! can still be used.

How to use Wasmer 3.0.0

Installing Wasmer CLI

See wasmer.io for installation instructions.

If you already have wasmer installed, run wasmer self-update.

Install the latest versions of Wasmer with wasmer-nightly or by following the steps described in the documentation: Getting Started.

Using Wasmer 3.0.0

See the examples to find out how to do specific things in Wasmer 3.0.0.

Project Structure

TODO

Differences

Managing imports

Instantiating a Wasm module is similar to 2.x.x.:

let import_object: Imports = imports! {
    "env" => {
        "host_function" => host_function,
    },
};
let instance = Instance::new(&module, &import_object).expect("Could not instantiate module.");

You can also build the Imports object manually:

let mut import_object: Imports = Imports::new();
import_object.define("env", "host_function", host_function);
let instance = Instance::new(&module, &import_object).expect("Could not instantiate module.");

ChainableNamedResolver is removed

Chaining imports with a trait has been deemed too complex for what it does; it's possible to chain (i.e. override) an Imports' contents by using its implementation of std::iter::Extend from the Rust standard library:

let imports1: Imports = todo!();
let mut imports2: Imports = todo!();

imports2.extend(&imports);
// This is equivalent to the following:
// for ((ns, name), ext) in imports1.into_iter() {
//     imports2.define(&ns &name, ext);
// }