WebAssembly实践指南——C++和Rust通过wasmtime实现相互调用实例

C++和Rust通过wasmtime实现相互调用实例1 wasmtime介绍

wasmtime是一个可以运行WebAssembly代码的运行时环境。

WebAssembly是一种可移植的二进制指令集格式，其本身与平台无关，类似于Java的class文件字节码。

WebAssembly本来的设计初衷是想让浏览器可以运行C语言这种编译型语言的代码。通常我们的C语言代码会使用gcc或clang等编译器直接编译链接成与平台相关的二进制可执行文件，这种与平台相关的二进制文件浏览器是无法直接运行的。如果想让浏览器运行C语言代码，就需要使用可将C语言编译成WebAssembly指令的编译器，编译好的代码是wasm格式。然后就可以使用各种wasm运行时来执行wasm代码，这就类似于JVM虚拟机执行class文件。

由于指令集和运行时环境本身与web场景并不绑定，因此随着后来的发展，WebAssembly指令集出现了可以脱离浏览器的独立运行时环境，WebAssembly的用途也变得更加广泛。

相比于浏览器的运行时，wasmtime是一个独立运行时环境，它可以脱离Web环境来执行wasm代码。它本身提供了命令行工具和API两种方式来执行wasm代码。本文主要介绍如何使用API方式来运行wasm代码。

2 wasmtime安装2.1 wasmtime-cli安装

wasmtime-cli包含wasmtime命令，可以让我们直接在shell中运行wasm格式的代码。我们这里安装wasmtime主要是为了测试方便。

1. 在shell中执行如下命令

   curl https://wasmtime.dev/install.sh -sSf | bash

2. wasmtime的可执行文件会被安装在${HOME}/.wasmtime目录下

3. 运行以上命令后会在${HOME}/.bashrc或${HOME}/.bash_profile文件中帮我们添加以下环境变量

   export WASMTIME_HOME="${HOME}/.wasmtime"export PATH="$WASMTIME_HOME/bin:$PATH"

4. 如果希望所有用户（包括root）可以使用wasmtime命令，可以将以上环境变量设置到/etc/profile.d中，我们可以在该目录下创建wasmtime.sh文件，并添加一下代码

   export WASMTIME_HOME=/home//.wasmtime  # 将xxx替换成自己的home目录export PATH="$WASMTIME_HOME/bin:$PATH"

5. 可以使用如下命令直接运行wasm文件

   wasmtime hello.wasm

2.2 wasmtime库安装

如果想在代码中加载wasm文件并运行其中的代码，我们需要为我们使用的语言安装wasmtime库。注意这里的wasmtime库是为了让我们从代码中能够加载wasm文件并在wasmtime运行时中运行。wasmtime并不是wasm编译器，不能将C++或Rust代码编译成wasm文件，如果我们想将其他语言编译成wasm代码，需要下载各个语言自己的wasm编译器，具体安装方式在本文第3节。

目前wasmtime支持的语言有：

• Rust
• C
• C++
• Python
• .NET
• Go

我们这里以Rust和C++为例介绍如何安装wasmtime库

Rust

在Rust中使用wasmtime库非常简单，我们只需要在Cargo.toml配置文件中添加如下依赖

[dependencies]wasmtime = "12.0.2"

C++

wasmtime的C++库需要我们引入wasmtime-cpp这个项目，wasmtime-cpp依赖wasmtime的C API，因此需要先安装C API。

1. 可以在wasmtime的release中找到后缀为-c-api的包，比如我们安装的平台是x86_64-linux，那么我们可以下载如下文件

   wget https://github.com/bytecodealliance/wasmtime/releases/download/v12.0.2/wasmtime-v12.0.2-x86_64-linux-c-api.tar.xz

2. 解压以上文件并将其移动到/usr/local目录下

   tar -xvf wasmtime-v12.0.2-x86_64-linux-c-api.tar.xzsudo mv ./wasmtime-v12.0.2-x86_64-linux-c-api /usr/local/wasmtime

3. 在/etc/profile.d/wasmtime.sh中添加环境变量

   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/wasmtime/libexport LIBRARY_PATH=$LIBRARY_PATH:/usr/local/wasmtime/libexport C_INCLUDE_PATH=$C_INCLUDE_PATH:/usr/local/wasmtime/includeexport CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:/usr/local/wasmtime/include

4. 下载wasmtime-cpp项目的include/wasmtime.hh文件，将其放到wasmtime.h所在的目录下，按照我们的安装步骤，需要放置到/usr/local/wasmtime/include目录下

5. 如此就可以在我们的C++项目中引入wasmtime库了

   #include 

3 wasm编译器安装Rust安装

Rust语言的编译器目前其实是一个LLVM的编译前端，它将代码编译成LLVM IR，然后经过LLVM编译成相应的目标平台代码。

因此我们并不需要替换Rust语言本身的编译器，只需要在编译时设置目标平台为wasm即可。我们在安装rust时，通常只会安装本机平台支持的目标，因此我们需要先安装wasm目标。

# 列出所有可安装的target列表rustup target list

使用上面的命令后可以看到很多可以安装的target列表，其中已经安装的target后面会有(installed)标示。注意到其中有3个wasm相关的target。

wasm32-unknown-emscriptenwasm32-unknown-unknownwasm32-wasi

1. wasm32-unknown-emscripten：这个target是为了在Emscripten工具链下编译Wasm。Emscripten是一个将C/C++代码编译为Wasm和JavaScript的工具链。使用这个target，你可以在浏览器环境中运行编译后的Wasm代码。
2. wasm32-unknown-unknown：这个target是为了在没有任何操作系统支持的情况下运行WebAssembly代码而设计的。这种情况下，WebAssembly代码将运行在一个“裸机”环境中，没有任何操作系统提供的支持。因此，如果你需要在裸机环境中运行WebAssembly代码，那么使用这个target是一个不错的选择。
3. wasm32-wasi：这个target是为了在WebAssembly System Interface (WASI)上运行WebAssembly代码而设计的。WASI是一个标准接口，它提供了一些操作系统级别的功能，如文件系统和网络访问等。因此，如果你需要在WebAssembly中访问这些操作系统级别的功能，那么使用这个target是一个不错的选择。

由于我们不需要在Web环境中运行Rust代码，因此我们选择安装wasm32-unknown-unknown和wasm32-wasi两个目标。运行以下两条指令，将这两个目标平台加入到当前使用的Rust工具链中。

rustup target add wasm32-unknown-unknownrustup target add wasm32-wasi

使用

当我们需要将一个Rust项目编译成wasm时，可以选择执行如下的两种编译命令

# 在项目根目录执行cargo build --target wasm32-unknown-unknown  # 将在target/wasm32-unknown-unknown目录中生成build中间结果和wasm文件# 或者执行cargo build --target wasm32-wasi  # 将在target/wasm32-wasi目录中生成build中间结果和wasm文件

C++安装

目前，要将C++项目编译成WebAssembly，最常用的工具链是emscripten。emscripten支持将C，C++或任何使用了LLVM的语言编译成浏览器，Node.js或wasm运行时可以运行的代码。

Emscripten is a complete compiler toolchain to WebAssembly, using LLVM, with a special focus on speed, size, and the Web platform.

WebAssembly目前支持两种标准API：

• Web APIs
• WASI APIs

Emscripten对JavaScript API做了重构，将其包装在与WASI接口一样的API中，然后Emscripten在编译代码时，将尽可能的使用WASI APIs，以此来避免不必要的API差异。因此Emscripten编译出来的wasm文件大部分时候可以同时运行在Web和非Web环境中。

使用如下命令下载emsdk

git clone https://github.com/emscripten-core/emsdk.gitcd emsdk

使用如下命令安装最新的工具

git pull./emsdk install latest./emsdk activate latest

如果临时将emsdk的工具目录加入环境变量，可以运行

source ./emsdk_env.sh

或者可以在/etc/profile.d目录中创建emsdk.sh文件，并加入如下环境变量的配置，需要将替换为emsdk所在的目录。

export PATH=$PATH:/emsdk:/emsdk/node/16.20.0_64bit/bin:/emsdk/upstream/emscriptenexport EMSDK=/emsdkexport EMSDK_NODE=/emsdk/node/16.20.0_64bit/bin/node

使用如下命令测试是否安装成功，如果输出下面的信息，说明我们已经可以正常使用emscripten的工具链。

> emcc -vemcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.1.45 (ef3e4e3b044de98e1811546e0bc605c65d3412f4)clang version 18.0.0 (https://github.com/llvm/llvm-project d1e685df45dc5944b43d2547d0138cd4a3ee4efe)Target: wasm32-unknown-emscriptenThread model: posixInstalledDir: /emsdk/upstream/bin

使用

由于我们不使用Web运行时，下面将只介绍将C或C++代码编译成独立wasm二进制文件的使用方法。

1. 简单使用

emcc -O3 hello.cpp -o hello.wasm

当我们将输出目标的后缀名指定为wasm时，编译器会自动帮我们设置如下连接选项，上面的命令与下面的命令时等价的

emcc -O3 hello.cpp -o hello.wasm -s STANDALONE_WASM

这样编译出来的结果不会包含js文件，只会包含一个可被wasmtime运行的wasm文件。

2. 结合cmake使用

更常用的方式通常是将整个C++项目编译成wasm，因此我们需要将工具链与cmake结合来构建整个项目。

假设我们有一个cmake项目有如下项目结构

hello_project   |-hello.cpp   |-CMakeLists.txt

其中hello.cpp中有如下代码

#include int main() {  printf("hello, world!\n");  return 0;}

CMakeLists.txt应该按照下面的方式进行改写

cmake_minimum_required(VERSION 3.26)project(hello_project)add_definitions(-std=c++17)set(CMAKE_CXX_STANDARD 17)if (DEFINED EMSCRIPTEN)    add_executable(hello hello.cpp)    set(CMAKE_EXECUTABLE_SUFFIX  ".wasm")    set_target_properties(foo PROPERTIES COMPILE_FLAGS "-Os")    set_target_properties(foo PROPERTIES LINK_FLAGS "-Os -s WASM=1 -s STANDALONE_WASM")else()    add_executable(hello hello.cpp)endif ()

以上CMakeLists.txt表示，当我们使用emscripten工具链进行编译时，将输出.wasm文件，且添加对应的编译和连接选项。当我们使用其他工具链编译时，将直接输出对应平台的可执行文件。

按照上面的方式写好CMakeLists.txt后，需要使用以下命令来执行编译的过程

# 在项目根目录下mkdir buildcd build# 执行emcmake命令会帮我们自动配置cmake中指定的工具链为emscripten的工具链，这样就确保了使用的编译工具为emcc或em++，同时使用的标准库更改为emscripten提供的标准库emcmake cmake ..# 再执行make进行编译，编译后可以发现build目录中生成了hello.wasm文件make

使用wasmtime-cli运行hello.wasm文件

> wasmtime hello.wasmhello, world!

4 小试牛刀实验场景

需要测试Rust代码被编译成wasm，C++代码被编译成wasm，在wasmtime中正确运行。其中C++代码可以调用Rust代码中的函数，然后外部可以调用C++代码中的函数。

1. Rust项目：包含一个add函数，做两个整数的加法并返回结果，可以被外部调用。需要编译成wasm。
2. C++项目：包含一个foo函数，调用Rust中的add函数并返回结果。需要编译成wasm。
3. wasmtime项目：需要加载前面两个项目生成的wasm文件，并运行foo函数，看是否能获取正确的结果。

Rust项目编译成wasm

创建一个项目叫做demo-rust-wasmtime

cargo new demo-rust-wasmtime --lib

创建好的项目结构如下

demo-rust-wasmtime├── Cargo.lock├── Cargo.toml└── src  └── lib.rs

首先需要在Cargo.toml中配置生成的库为cdylib，这表示按照C语言的FFI来生成动态库，要想不同语言之间能够互相调用对方的函数，通常需要将不同的语言按照相同的FFI来进行编译，确保函数调用的方式是相同的。这里同时我们将Rust项目的名称修改为calc。

[package]name = "calc"version = "0.1.0"edition = "2021"# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html[lib]crate-type = ["cdylib"][dependencies]

在lib.rs中实现我们需要的add函数

#[no_mangle]pub extern "C" fn add(left: i32, right: i32) -> i32 {    left + right}

这里有两个地方需要注意：

• #[no_mangle]会通知Rust编译器，其后面的函数编译时名字不要进行混淆，确保使用add这个名称进行链接时能找到正确的函数。
• extern "C"表示编译器需要确保函数在编译时使用与C语言相同的调用约定(ABI)，从而使得函数可以与C语言代码无缝地进行交互，当然如果我们将不同的语言都遵照C语言的ABI进行编译，那么它们之间就可以互相调用。

C语言的调用约定规定了函数参数的传递方式、返回值的处理方式以及堆栈的清理方式。

这样就定义好了Rust项目中可以让外部使用的add方法。

我们使用如下命令对项目进行编译

cargo build --target wasm32-unknown-unknown# 或cargo build --target wasm32-wasi

这里两种target都可以使用，因为我们的项目中并没有使用任何系统的API，所以通常使用第一种target即可。

编译后可以在target/wasm-xxx/debug/目录下看到生成的calc.wasm文件。

可以使用wasmtime-cli实验一下是否能够调用add方法：

> wasmtime calc.wasm --invoke add 101 202warning: using `--invoke` with a function that takes arguments is experimental and may break in the futurewarning: using `--invoke` with a function that returns values is experimental and may break in the future303

可以看到已经正确输出了结果，说明这个Rust项目已经被正确编译成了wasm。

C++项目编译成wasm

创建一个项目叫做demo-cpp-wasmtime，使用cmake作为构建工具，其目录结构如下

demo-cpp-wasmtime├── CMakeLists.txt├── toolbox.cpp└── toolbox.h

正如第3节讲到的，我们需要使用emscripten工具链代替gcc工具链来将这个C++项目编译成wasm。

cmake配置

因此我们需要按照如下方式配置CMakeLists.txt文件

cmake_minimum_required(VERSION 3.26)project(demo_cpp_wasmtime)add_definitions(-std=c++17)set(CMAKE_CXX_STANDARD 17)if (DEFINED EMSCRIPTEN)    add_executable(toolbox toolbox.cpp toolbox.h)    set(CMAKE_EXECUTABLE_SUFFIX  ".wasm")    set_target_properties(toolbox PROPERTIES COMPILE_FLAGS "-Os -s SIDE_MODULE=1")    set_target_properties(toolbox PROPERTIES LINK_FLAGS "-Os -s WASM=1 -s SIDE_MODULE=1 -s STANDALONE_WASM --no-entry")else()    add_library(toolbox toolbox.cpp)endif ()

这里有几点需要注意的

1. 在使用emscripten时，我们使用add_executable指定编译目标为可执行文件，这是因为wasm本身是可执行的二进制代码，在没有特殊配置时，编译后的wasm代码中会生成一个_start函数，这个函数就是运行时执行wasm代码的入口。这里如果我们将add_executable替换成add_library，则使用emscripten编译后只会生成libtoolbox.a库文件，而不会生成wasm代码。

2. 针对emscripten编译工具链，我们配置了编译参数和链接参数

   • -Os表示开启编译优化

   • -s SIDE_MODULE=1表示将toolbox编译成module，这样生成的wasm就类似动态链接库，可以让wasmtime在运行时动态链接这份wasm代码。

     emscripten支持将代码编译成两种不同的module

     1. Main modules：系统库会被链接进去
     2. Side modules：系统库不会被链接进去

     通常一个完整的项目只能有一个Main module，这个Main module可以链接多个Side module

     这里的编译选项SIDE_MODULE可以被设置为1或者2，设置成2则编译器会优化掉大量未被使用的代码或未被标记为EMSCRIPTEN_KEEPALIVE的代码，设置成1则会保留所有代码。

   • -s WASM=1表示只输出wasm文件，设置为0表示只输出js代码，设置成2表示两种代码都输出

   • -s STANDALONE_WASM表示编译的wasm是不依赖web环境而运行的

   • --no-entry编译生成的wasm代码通常需要有一个入口函数，也就是C++中需要有main函数，然而我们这里toolbox.cpp中将只有一个foo函数，因此我们需要使用这个链接参数来表示我们不需要入口函数。

代码实现

toolbox.h头文件如下

#pragma onceextern "C" {int foo(int right);}

类似Rust，这里我们声明了一个函数foo，并使用extern "C"表示这个foo函数需要按照C语言ABI进行编译。

接下来是toolbox.cpp的实现

#ifdef __EMSCRIPTEN__#include #else#define EMSCRIPTEN_KEEPALIVE#define EM_IMPORT(NAME)#endifextern "C" {EM_IMPORT(add) int add(int a, int b);}extern "C" {EMSCRIPTEN_KEEPALIVE int foo(int right) {    return add(1, right);}}

下面解释一下代码中的几个宏的作用：

• #ifdef __EMSCRIPTEN__：当我们使用emscripten工具链编译这个项目时，__EMSCRIPTEN__会被自动定义

• EMSCRIPTEN_KEEPALIVE和EM_IMPORT(NAME)：

  这是头文件emscripten.h中定义的宏，查看源码可以发现

  #define EMSCRIPTEN_KEEPALIVE __attribute__((used))#ifdef __wasm__#define EM_IMPORT(NAME) __attribute__((import_module("env"), import_name(#NAME)))#else#define EM_IMPORT(NAME)#endif

  __attribute__((used))的作用是告诉编译器，即使该变量或函数没有被直接使用，也不要将其优化掉。这在一些特殊的情况下很有用，例如当你想要确保某个变量或函数在编译后的可执行文件中存在，即使它在代码中没有被显式调用或使用。这样就确保了我们的foo函数不会被编译器优化掉

  __attribute__((import_module("env"), import_name(#NAME)))是用于WebAssembly的特殊属性，用于指定导入函数所属的模块和导入函数的名称。在WebAssembly中，可以从外部导入函数，这些函数通常由宿主环境（如浏览器或wasmtime）提供。当你使用__attribute__((import_module("env"), import_name(#NAME)))属性时，它告诉WebAssembly运行时，该函数属于名为”env”的模块，并且其导入名称为#NAME。

使用EM_IMPORT(add)宏告诉编译器，这里声明的add方法其具体实现来自于其他模块，具体就是来自于env模块中的add函数。因此这里声明的add方法其实可以起任意的名字，只要签名与env模块中的add方法相同即可。

编译

使用如下命令进行编译

# 在项目根目录下mkdir buildcd buildemcmake cmake ..make

编译后在build目录下会生成toolbox.wasm二进制文件。

我们可以使用wasm2wat命令将编译好的wasm二进制文件转换成可读的wat文件来看一下生成的代码的结构

如果没有安装wasm2wat命令可以使用一下命令来安装

sudo apt install wabt

执行wasm2wat toolbox.wasm -o toolbox.wat命令后，可以打开toolbox.wat文件查看其结构如下

(module  (type (;0;) (func (param i32 i32) (result i32)))  (type (;1;) (func))  (type (;2;) (func (param i32) (result i32)))  (import "env" "add" (func (;0;) (type 0)))  (func (;1;) (type 1))  (func (;2;) (type 2) (param i32) (result i32)    i32.const 1    local.get 0    call 0)  (export "__wasm_call_ctors" (func 1))  (export "__wasm_apply_data_relocs" (func 1))  (export "foo" (func 2)))

可以看出，代码中import "env" "add"表示add函数来自env module的add函数。同时export "foo"表示toolbox.wasm对外暴露了foo函数。

wasmtime项目

wasmtime项目可以使用wasmtime支持的各种语言实现，这里我们以C++为例，看看如何将前面两个项目生成的.wasm文件调用起来。

创建一个项目叫做demo-run，使用cmake进行项目构建，其目录结构如下

demo-run├── CMakeLists.txt└── main.cpp

cmake配置

wasmtime项目可以使用gcc工具链进行编译，因此它的CMakeLists.txt可以正常进行配置

cmake_minimum_required(VERSION 3.26)project(demo_run)set(CMAKE_CXX_STANDARD 17)add_executable(demo_run main.cpp)target_link_libraries(demo_run PUBLIC wasmtime)

因为我们需要在代码中使用wasmtime的库，因此这里需要使用target_link_libraries(demo_run PUBLIC wasmtime)将wasmtime链接进来。这也就要求必须先按照第2节中的安装方式配置好wasmtime的环境变量。

代码实现

具体wasmtime提供的每个API的用法在这里不多做赘述，具体可以参考wasmtime官方文档和官方提供的examples

#include #include #include using namespace wasmtime;std::vector readFile(const char *name) {    std::ifstream watFile(name, std::ios::binary);    std::vector arr;    char byte;    while (watFile.get(byte)) {        arr.push_back(byte);    }    return arr;}int main() {    std::cout << "Compiling module" << std::endl;    Engine engine;    // 加载calc.wasm成为module    auto calcByteArr = readFile("calc.wasm");    Span calcSpan(calcByteArr.data(), calcByteArr.size());    auto calcModule = Module::compile(engine, calcSpan).unwrap();    // 加载toolbox.wasm成为module    auto toolboxByteArr = readFile("toolbox.wasm");    Span toolboxSpan(toolboxByteArr.data(), toolboxByteArr.size());    auto toolboxModule = Module::compile(engine, toolboxSpan).unwrap();    std::cout << "Initializing..." << std::endl;    Store store(engine);    store.context().set_wasi(WasiConfig()).unwrap();    std::cout << "Linking..." << std::endl;    Linker linker(engine);    linker.define_wasi().unwrap();    // 链接器初始化calc module，实例化成具体的Instance    auto calcInst = linker.instantiate(store, calcModule).unwrap();    // 将上一步的calcInst中的所有export的对象定义到env module名下    linker.define_instance(store, "env", calcInst).unwrap();    // 链接器初始化toolbox module，实例化成具体的Instance    auto toolboxInst = linker.instantiate(store, toolboxModule).unwrap();    // 获取toolboxInst中的foo方法    auto func = std::get(toolboxInst.get(store, "foo").value());    // 调用foo方法，传入参数7,    auto fooRes = func.call(store, {7}).unwrap();    // 打印结果 FooResult: 8    std::cout << "FooResult: " << fooRes[0].i32() << std::endl;    return 0;}

就像注释中写的那样，我们将calc.wasm中export的方法add添加到了名称为env的module下，这样上一步中C++编译成的.wasm代码就可以链接到这个add方法。

编译与运行

mkdir buildcd buildcmake ..make

执行编译后会生成可执行文件demo_run，由于代码还要依赖两个.wasm文件，因此我们这里手动将前面两个项目生成的.wasm文件拷贝到demo_run可执行文件的同级目录下。

运行生成的demo_run可执行文件后可得如下输出

> ./demo_runCompiling moduleInitializing...Linking...FooResult: 8

以上就实现了C++和Rust通过wasmtime实现相互调用的过程。