Crate wasmedge_sdk
source · [−]Expand description
Overview
The wasmedge-sdk crate defines a group of high-level Rust APIs, which are used to build 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-sdk | WasmEdge lib | wasmedge-sys | wasmedge-types |
|---|---|---|---|
| 0.3.0 | 0.10.1 | 0.8 | 0.2 |
| 0.1.0 | 0.10.0 | 0.7 | 0.1 |
Build
To use or build the wasmedge-sdk 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_DIRandWASMEDGE_LIB_DIRto specify the paths to theincludeandlibdirectories, respectively. For example, use the following commands to specify the paths after usingbash install.sh --path=$HOME/wasmedge-installto 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/.wasmedgedirectory. It looks like below on Ubuntu 20.04.wasmedge-sdkwill search the directory automatically, you do not have to set any environment variables for it.// $HOME/.wasmedge/ . |-- bin | |-- wasmedge | `-- wasmedgec |-- include | `-- wasmedge | |-- dense_enum_map.h | |-- enum.inc | |-- enum_configure.h | |-- enum_errcode.h | |-- enum_types.h | |-- int128.h | |-- spare_enum_map.h | |-- version.h | `-- wasmedge.h `-- lib64 |-- libwasmedge_c.so `-- wasmedge `-- libwasmedgePluginWasmEdgeProcess.so 5 directories, 13 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/wasmedgeExample
The example below is using wasmedge-sdk to run a WebAssembly module written with its WAT format (textual format):
// If the version of rust used is less than v1.63, please uncomment the follow attribute.
// #![feature(explicit_generic_args_with_impl_trait)]
use wasmedge_sdk::{Executor, FuncTypeBuilder, ImportObjectBuilder, Module, Store};
use wasmedge_sys::WasmValue;
use wasmedge_types::wat2wasm;
#[cfg_attr(test, test)]
fn main() -> anyhow::Result<()> {
let wasm_bytes = wat2wasm(
br#"
(module
;; First we define a type with no parameters and no results.
(type $no_args_no_rets_t (func (param) (result)))
;; Then we declare that we want to import a function named "env" "say_hello" with
;; that type signature.
(import "env" "say_hello" (func $say_hello (type $no_args_no_rets_t)))
;; Finally we create an entrypoint that calls our imported function.
(func $run (type $no_args_no_rets_t)
(call $say_hello))
;; And mark it as an exported function named "run".
(export "run" (func $run)))
"#,
)?;
// We define a function to act as our "env" "say_hello" function imported in the
// Wasm program above.
fn say_hello_world(_inputs: Vec<WasmValue>) -> Result<Vec<WasmValue>, u8> {
println!("Hello, world!");
Ok(vec![])
}
// create an import module
let import = ImportObjectBuilder::new()
.with_func::<(), ()>("say_hello", Box::new(say_hello_world))?
.build("env")?;
// loads a wasm module from the given in-memory bytes
let module = Module::from_bytes(None, &wasm_bytes)?;
// create an executor
let mut executor = Executor::new(None, None)?;
// create a store
let mut store = Store::new()?;
// register the module into the store
store.register_import_module(&mut executor, &import)?;
let extern_instance = store.register_named_module(&mut executor, "extern", &module)?;
// get the exported function "run"
let run = extern_instance.func("run").ok_or(anyhow::Error::msg(
"Not found exported function named 'run'.",
))?;
// run host function
run.call(&mut executor, [])?;
Ok(())
}
See also
Modules
Defines the structs used to construct configurations.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge error types.
Defines the general types.
Defines wasi module instance types, including WasiInstance, WasiNnInstance, wasi-crypto instances.
Macros
Used to pass arguments to Func::call, FuncRef::call, Engine::run_func, or Engine::run_func_ref. Notice that to use the macro, it is required to use WasmVal trait. If the version of rust used is less than v1.63, please place #![feature(explicit_generic_args_with_impl_trait)] on the root of the program.
Structs
Defines WasmEdge ahead-of-time(AOT) compiler and the relevant APIs.
The version info of WasmEdge core
Defines WasmEdge Driver functions
Defines an execution environment for both pure WASM and compiled WASM.
Defines the types of the exported instances.
Defines a host function instance.
Defines a reference to a host function.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Struct of WasmEdge FuncType.
Defines a type builder for creating a FuncType instance.
Defines a WebAssembly global variable, which stores a single value of the given GlobalType and a flag indicating whether it is mutable or not.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Struct of WasmEdge GlobalType.
Defines an import object that contains the required import data used when instantiating a module.
Creates a normal, wasi, or wasmedge process import object.
Defines the types of the imported instances.
Represents an instantiated module.
Defines a linear memory.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Struct of WasmEdge MemoryType.
Defines compiled in-memory representation of an input WASM binary.
Used to collect statistics of the WasmEdge runtime, such as the count of instructions in execution.
Defines a table storing the references to host functions or external objects.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Struct of WasmEdge TableType.
Represents a wasmedge_process module instance.
Enums
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge AOT compiler optimization level.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge AOT compiler output binary format.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines the type of external WasmEdge instances.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines the mutability property of WasmEdge Global variables.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge reference types.
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge value types.
Traits
The object used 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.
Defines the function converting a value of Rust type to the one of Wasm type.
Describes the mapping of Rust type to Wasm type.
Describes the mapping of a tuple of Rust types to Wasm types.
Functions
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module.
Type Definitions
Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module The WasmEdge result type.
WebAssembly value type.