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.
-
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.
-
wasmedge-types crate. The data structures that are commonly used in
wasmedge-sdk
andwasmedge-sys
are defined in this crate.
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 theWasmEdge
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
andWASMEDGE_LIB_DIR
.If you choose to use install.sh to install WasmEdge Runtime on your local system, please use
WASMEDGE_INCLUDE_DIR
andWASMEDGE_LIB_DIR
to specify the paths to theinclude
andlib
directories respectively. For example, use the following commands to specify the paths after usingbash 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 theWasmEdge
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 generatedinclude
andlib
directories in~/workspace/me/WasmEdge/build
. -
Then, set
WASMEDGE_BUILD_DIR
environment variable to specify thebuild
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 theCargo.toml
file of your project. Now, you can usecargo build
command to build your project.
[dependencies]
wasmedge-sdk = "0.4"
wasmedge-sys
crate
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.