logo
Expand description

Overview

The wasmedge-sys crate defines a group of low-level Rust APIs for WasmEdge, a light-weight, high-performance, and extensible WebAssembly runtime for cloud-native, edge, and decentralized applications.

For developers, it is strongly recommended that the APIs in wasmedge-sys are used to construct high-level libraries, while wasmedge-sdk is for building up business applications.

Notice that WasmEdge Rust SDK uses nightly version of Rust. It’s strongly recommended to use the latest nightly version of Rust.

Versioning Table

The following table provides the versioning information about each crate of WasmEdge Rust bindings.

wasmedge-sdkWasmEdge libwasmedge-syswasmedge-types
0.4.00.11.00.90.2.1
0.3.00.10.10.80.2.0
0.1.00.10.00.70.1

Build

To use or build the wasmedge-sys crate, the WasmEdge library is required.

  • If you choose to use install.sh to install WasmEdge Runtime on your local system. Please use WASMEDGE_INCLUDE_DIR and WASMEDGE_LIB_DIR to specify the paths to the include and lib directories, respectively. For example, use the following commands to specify the paths after using bash install.sh --path=$HOME/wasmedge-install to install WasmEdge Runtime on Ubuntu 20.04:

    export WASMEDGE_INCLUDE_DIR=$HOME/wasmedge-install/include
    export WASMEDGE_LIB_DIR=$HOME/wasmedge-install/lib
  • If you choose to manually download WasmEdge Runtime binary from WasmEdge Releases Page, it is strongly recommended to place it in $HOME/.wasmedge directory. It looks like below on Ubuntu 20.04. wasmedge-sys will search the directory automatically, you do not have to set any environment variables for it.

    // $HOME/.wasmedge/
    .
    |-- bin
    |   |-- wasmedge
    |   `-- wasmedgec
    |-- include
    |   `-- wasmedge
    |       |-- enum.inc
    |       |-- enum_configure.h
    |       |-- enum_errcode.h
    |       |-- enum_types.h
    |       |-- int128.h
    |       |-- version.h
    |       `-- wasmedge.h
    `-- lib64
        |-- libwasmedge_c.so
        `-- wasmedge
            `-- libwasmedgePluginWasmEdgeProcess.so
    
    5 directories, 11 files

Enable WasmEdge Plugins

If you’d like to enable WasmEdge Plugins (currently, only available on Linux platform), please use WASMEDGE_PLUGIN_PATH environment variable to specify the path to the directory containing the plugins. For example, use the following commands to specify the path on Ubuntu 20.04:

export WASMEDGE_PLUGIN_PATH=$HOME/.wasmedge/lib/wasmedge

Example

The following code presents how to use the APIs in wasmedge-sys to run a WebAssembly module written with its WAT format (textual format):

use wasmedge_sys::{Vm, WasmValue};
use wasmedge_types::wat2wasm;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // read the wasm bytes
    let wasm_bytes = wat2wasm(
        br#"
        (module
            (export "fib" (func $fib))
            (func $fib (param $n i32) (result i32)
             (if
              (i32.lt_s
               (get_local $n)
               (i32.const 2)
              )
              (return
               (i32.const 1)
              )
             )
             (return
              (i32.add
               (call $fib
                (i32.sub
                 (get_local $n)
                 (i32.const 2)
                )
               )
               (call $fib
                (i32.sub
                 (get_local $n)
                 (i32.const 1)
                )
               )
              )
             )
            )
           )
"#,
    )?;

    // create a Vm instance
    let mut vm = Vm::create(None, None)?;

    // register the wasm bytes
    let module_name = "extern-module";
    vm.register_wasm_from_bytes(module_name, &wasm_bytes)?;

    // run the exported function named "fib"
    let func_name = "fib";
    let result = vm.run_registered_function(module_name, func_name, [WasmValue::from_i32(5)])?;

    assert_eq!(result.len(), 1);
    assert_eq!(result[0].to_i32(), 8);

    Ok(())
}

[Click for more examples]

See also

Modules

Defines WasmEdge CallingFrame.

Defines the WebAssembly primitive types.

Defines the versioning and logging functions.

Structs

Defines the WasmEdge Async result.

Defines WasmEdge ahead-of-time(AOT) compiler and the relevant APIs.

Defines Config struct used to check/set the configuration options.

Defines an execution environment for both pure WASM and compiled WASM.

Defines the types of the exported wasm values.

Defines a reference to a host function.

Defines the type of a host function.

Defines a host function.

Defines a WebAssembly global variable, which stores a single value of the given type and a flag indicating whether it is mutable or not.

Defines the type of a wasm global variable.

An ImportModule represents a host module with a name. A host module consists of one or more host function, table, memory, and global instances, which are defined outside wasm modules and fed into wasm modules as imports.

Defines the types of the imported wasm value.

An Instance represents an instantiated module. In the instantiation process, An Instance is created from alModule. From an Instance the exported functions, tables, memories, and globals can be fetched.

Loader is used to load WASM modules from the given WASM files or buffers.

Defines the type of a wasm memory instance

Defines a WebAssembly memory instance, which is a linear memory described by its type. Each memory instance consists of a vector of bytes and an optional maximum size, and its size is a multiple of the WebAssembly page size (64KiB of each page).

Defines compiled in-memory representation of an input WASM binary.

Struct of WasmEdge Statistics.

A 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 life time of the Vm.

A WasmEdge Table defines a WebAssembly table instance described by its type. A table is an array-like structure and stores function references.

A WasmEdge TableType classifies a Table instance over elements of element types within a size range.

Struct of WasmEdge Validator.

A Vm defines a virtual environment for managing WebAssembly programs.

A WasiCryptoAsymmetricCommonModule is a module instance for the WASI-Crypto specification, covering common types and functions for asymmetric operations.

A WasiCryptoCommonModule is a module instance for the WASI-Crypto specification, covering common types and functions for symmetric operations.

A WasiCryptoKxModule is a module instance for the WASI-Crypto specification, covering key exchange interfaces.

A WasiCryptoSignaturesModule is a module instance for the WASI-Crypto specification, covering signatures interfaces.

A WasiCryptoSymmetricModule is a module instance for the WASI-Crypto specification, covering symmetric operations.

A WasiModule is a module instance for the WASI specification.

A WasiNnModule is a module instance for the WASI-NN specification.

A WasmEdgeProcessModule is a module instance for the WasmEdge_Process specification.

Defines a WebAssembly value.

Enums

Defines three types of module instances that can be imported into a WasmEdge Store instance.

Defines the WasiCrypto type.

Traits

The object to be registered into a Vm or an Executor instance is required to implement this trait. The object that implements this trait can be registered via the Vm::register_wasm_from_import function, or the Executor::register_import_object function.

The object as an module instance is required to implement this trait.

The object that is used to perform a host function is required to implement this trait.

Type Definitions

Type alias for a boxed native function. This type is used in thread-safe cases.

Type alias for a boxed native function. This type is used in non-thread-safe cases.