WasmEdge Rust SDK

WasmEdge Rust SDK

Introduction

WasmEdge supports embedding into Rust applications via WasmEdge Rust SDK. WasmEdge Rust SDK consists of three crates:

wasmedge-sdk crate. It defines a group of safe, ergonomic high-level APIs, which are used to build up business applications.
- API documentation
wasmedge-sys crate. It defines a group of low-level Rust APIs, which simply wrap WasmEdge C-API and provide the safe counterparts. It is not recommended to use it directly to build up application.
- API documentation
wasmedge-types crate. The data structures that are commonly used in wasmedge-sdk and wasmedge-sys are defined in this crate.
- API documentation

Versioning Table

The following table provides the versioning information about each release of wasmedge-sdk crate and its dependencies.

wasmedge-sdk	WasmEdge lib	wasmedge-sys	wasmedge-types	wasmedge-macro
0.5.0	0.11.1	0.10	0.3.0	0.1.0
0.4.0	0.11.0	0.9	0.2.1	-
0.3.0	0.10.1	0.8	0.2	-
0.1.0	0.10.0	0.7	0.1	-

Build

To use wasmedge-sdk in your project, you should finish the following two steps before building your project:

First, deploy WasmEdge library on your local system.

You can reference the versioning table and download WasmEdge library from WasmEdge Releases Page. After download the WasmEdge library, you can choose one of the following three ways to specify the locations of the required files:
- By default location
  
  For those who do not want to define environment variables, you can put the downloaded WasmEdge binary package in the default location $HOME/.wasmedge/. The directory structure of the default location should looks like below:
```
// $HOME/.wasmedge/ on Ubuntu-20.04
.
├── bin
│   ├── wasmedge
│   └── wasmedgec
├── include
│   └── wasmedge
│       ├── enum.inc
│       ├── enum_configure.h
│       ├── enum_errcode.h
│       ├── enum_types.h
│       ├── int128.h
│       ├── version.h
│       └── wasmedge.h
└── lib64
    ├── libwasmedge.so
    └── wasmedge
        └── libwasmedgePluginWasmEdgeProcess.so

5 directories, 11 files
```
```
// $HOME/.wasmedge/ on macOS-12
.
├── bin
│   ├── wasmedge
│   └── wasmedgec
├── include
│   └── wasmedge
│       ├── enum.inc
│       ├── enum_configure.h
│       ├── enum_errcode.h
│       ├── enum_types.h
│       ├── int128.h
│       ├── version.h
│       └── wasmedge.h
└── lib
    └── libwasmedge.dylib

4 directories, 10 files
```
- By specifying WASMEDGE_INCLUDE_DIR and WASMEDGE_LIB_DIR.
  
  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
```
- By specifying WASMEDGE_BUILD_DIR
  
  You can choose this way if you'd like to use the latest code in the master branch of the WasmEdge github repo. For example,
  - Suppose that you git clone WasmEdge repo in your local directory, for example, ~/workspace/me/WasmEdge, and follow the instructions to build WasmEdge native library. After that, you should find the generated include and lib directories in ~/workspace/me/WasmEdge/build.
  - Then, set WASMEDGE_BUILD_DIR environment variable to specify the build directory.
```
root@0a877562f39e:~/workspace/me/WasmEdge# export WASMEDGE_BUILD_DIR=/root/workspace/me/WasmEdge/build
```
Second, after deploy the WasmEdge library on your local system, copy/paste the following code into the Cargo.toml file of your project. Now, you can use cargo build command to build your project.

[dependencies]
wasmedge-sdk = "0.4"

wasmedge-sys serves as a wrapper layer of WasmEdge C-API, and provides a group of safe low-level Rust interfaces. For those who are interested in using wasmedge-sys in their projects, you should also deploy the WasmEdge library on your local system as described in the wasmedge-sdk crate section. Then, copy/paste the following code in the Cargo.toml file of your project. For details, please refer to README.

[dependencies]
wasmedge-sys = "0.9"

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

Docker image

For those who would like to dev in Docker environment, you can reference the Use Docker section of this book, which details how to use Docker for WasmEdge application development.

Examples

For helping you get familiar with WasmEdge Rust bindings, the following quick examples demonstrate how to use the APIs defined in wasmedge-sdk and wasmedge-sys, respectively. In addition, we'll add more examples continuously. Please file issues here and let us know if you have any problems with the API usage.

WasmEdge Runtime