WAMR 构建实战指南:iwasm vmcore 与 wamrc AOT 编译器的完整构建教程
WAMR 构建实战指南:iwasm vmcore 与 wamrc AOT 编译器的完整构建教程
本文是 WebAssembly Micro Runtime(WAMR)的构建实战指南,围绕 gitbook/tutorial/build-tutorial/README.md 的核心内容展开,系统讲解如何通过 CMake 选项构建 iwasm vmcore(运行时库)与 wamrc(AOT 编译器)。读完本文,你将掌握 WAMR 的六种运行模式(AOT、Classic Interpreter、Fast Interpreter、LLVM JIT、Fast JIT、Multi-tier JIT)的构建选项矩阵、全平台构建步骤、关键编译配置参数及其底层实现影响,能够在 Linux、Windows、macOS 及各类嵌入式平台上按需组合出符合自身场景的 WAMR 运行时。
构建体系全景:vmcore、iwasm 与 wamrc
在动手构建前,先厘清 WAMR 仓库中三个经常被混用的概念:
- WAMR vmcore:即运行时库集合,负责加载并执行 Wasm 模块,是 WAMR 的核心引擎部分,代码主要位于 core 目录下。
- iwasm:基于 vmcore 构建出的可执行二进制,带 WASI 支持与命令行接口,是"开箱即用"的演示与测试入口。其平台工程位于 product-mini 目录。
- wamrc:AOT(Ahead-of-Time)编译器,把
.wasm二进制文件编译为 AOT 文件(.aot),AOT 文件同样可以由 iwasm 直接运行。其源码位于 wamr-compiler 目录。
三者之间的关系是:iwasm 与 wamrc 都构建在 vmcore 之上;iwasm 既能解释执行 .wasm,也能执行 wamrc 生成的 .aot 文件。因此构建教程分两大主线:构建 iwasm vmcore(含编译选项体系) 与 构建 wamrc AOT 编译器。
运行模式与构建选项矩阵
WAMR 的 iwasm vmcore 提供了多种运行模式,通过 CMake 编译选项即可选择。以下是不同运行模式及其构建选项的矩阵(来源:gitbook/tutorial/build-tutorial/README.md):
| 运行模式 | CMake 构建选项 | 特点 |
|---|---|---|
| AOT | 无(默认启用) | 预先编译为 AOT 文件运行,接近原生速度,启动快、占用小 |
| Classic Interpreter | -DWAMR_BUILD_FAST_INTERP=0 |
朴素解释器,便于调试与学习,性能相对较低 |
| Fast Interpreter | 无(默认启用) | 比 Classic Interpreter 快约 2 倍,但需约 2 倍内存存放预编译代码 |
| LLVM JIT | -DWAMR_BUILD_JIT=1 |
基于 LLVM codegen 的 JIT,性能优于 Fast JIT 约 2 倍,冷启动较慢 |
| Fast JIT | -DWAMR_BUILD_FAST_JIT=1 |
轻量 JIT,占用小、启动快、可移植性好,性能约为 LLVM JIT 的 50% |
各模式的详细对比可参见 gitbook/tutorial/running-modes/README.md。补充说明几个模式间的联动关系(依据 doc/build_wamr.md):
- Fast Interpreter 是默认解释器:启用 LLVM JIT、Fast JIT 或解释器调试器(
WAMR_BUILD_DEBUG_INTERP)时,会强制切回 Classic Interpreter(即自动设置WAMR_BUILD_FAST_INTERP=0)。 - Multi-tier JIT:同时设置
-DWAMR_BUILD_FAST_JIT=1与-DWAMR_BUILD_JIT=1,即以 Fast JIT 作为第一层尽快启动执行,同时由后台线程编译 LLVM JIT 函数,编译完成后逐步切换以获得最佳性能。目前仅支持 x86_64 等少数架构。 - Lazy JIT:启用 LLVM JIT 或 Fast JIT 后默认开启,函数在被调用前由后台线程编译,可显著缩短大模块的启动时间。
支持的架构与平台
iwasm 支持以下 CPU 架构(来源:gitbook/tutorial/build-tutorial/README.md):
- X86-64、X86-32
- ARM、THUMB(已验证 ARMV7 Cortex-M7 与 Cortex-A15)
- AArch64(已验证 Cortex-A57 与 Cortex-A53)
- RISCV64、RISCV32(已验证 RISC-V LP64 与 RISC-V LP64D)
- XTENSA、MIPS、ARC
在 build-scripts/config_common.cmake 中可以看到这些目标架构如何被翻译为编译宏:例如 X86_64 对应 -DBUILD_TARGET_X86_64,ARM.* 与 THUMB.* 家族支持可选的 _VFP 后缀(表示参数与返回值使用 VFP 协处理器寄存器 s0-s15 / d0-d7),RISCV64/RISCV32 家族支持 _LP64D、_LP64、_ILP32D、_ILP32F、_ILP32 等 ABI 变体。
支持的操作系统平台及构建指引如下(点击链接跳转到对应构建小节,参考 doc/build_wamr.md 与 product-mini/README.md):
- Linux、Linux SGX(Intel Software Guard Extension)、MacOS、Android、Windows、Windows (MinGW)
- Zephyr、AliOS-Things、VxWorks、NuttX、RT-Thread、ESP-IDF
若要将 WAMR 移植到新平台,可参考 WAMR 移植指南。
构建 iwasm vmcore:以 runtime_lib.cmake 集成到宿主工程
vmcore 本质上是一套可被宿主程序链接的运行时库。最规范的使用方式是在宿主工程的 CMakeLists.txt 中引入 build-scripts/runtime_lib.cmake:
# add this into your CMakeLists.txt
include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
add_library(vmlib ${WAMR_RUNTIME_LIB_SOURCE})
runtime_lib.cmake 会暴露一系列 WAMR_* 变量来控制运行时特性,可在 CMakeLists.txt 中设置,也可在 cmake 命令行传入。一个最小可工作示例:
# Set flags in CMakeLists.txt
# WAMR Interpreter and AOT must be enabled at least one of them
set(WAMR_BUILD_INTERP 1)
# Must have
set(WAMR_BUILD_PLATFORM "linux")
# Include the runtime lib script
include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
add_library(vmlib ${WAMR_RUNTIME_LIB_SOURCE})
这些 WAMR_* CMake 变量最终会被构建脚本翻译为编译宏(-DWASM_ENABLE_* 等)。例如 WAMR_BUILD_AOT 会打开 WASM_ENABLE_AOT,而启用 WAMR_BUILD_MEMORY64 会自动打开 WASM_DISABLE_HW_BOUND_CHECK/WASM_DISABLE_STACK_HW_BOUND_CHECK(见 core/config.h 的宏默认值说明)。
平台与架构配置
- WAMR_BUILD_PLATFORM:设置目标平台,需与 core/shared/platform 下的平台目录名一致,例如
linux、darwin、windows、android。 - WAMR_BUILD_TARGET:设置目标 CPU 架构,支持
X86_64、X86_32、AARCH64、ARM、THUMB、XTENSA、ARC、RISCV32、RISCV64、MIPS。- ARM/THUMB 格式为
<arch>[<sub-arch>][_VFP],如ARMV7、ARMV7_VFP、THUMBV7_VFP; - AARCH64 格式为
<arch>[<sub-arch>],VFP 默认开启,如AARCH64V8.1; - RISCV64 支持
RISCV64、RISCV64_LP64D、RISCV64_LP64;RISCV32 支持RISCV32_ILP32D、RISCV32_ILP32F、RISCV32_ILP32。
- ARM/THUMB 格式为
cmake -DWAMR_BUILD_PLATFORM=linux -DWAMR_BUILD_TARGET=ARM
解释器配置
- WAMR_BUILD_INTERP=1/0:开关 WASM 解释器(解释器与 AOT 至少启用其一)。
- WAMR_BUILD_FAST_INTERP=1/0:选择 Fast Interpreter(默认)或 Classic Interpreter。
AOT 与编译器配置
- WAMR_BUILD_AOT=1/0:开关 AOT,默认开启。
- WAMR_BUILD_WAMR_COMPILER=1/0:用于 wasm loader 与编译流程,指示编译器模式。
- WAMR_BUILD_AOT_VALIDATOR=1/0:默认关闭,即 WAMR 默认信任 AOT 文件的有效性与不可伪造性;开启后会在加载时校验。
LLVM JIT 配置
- WAMR_BUILD_JIT=1/0:开关 LLVM JIT,默认关闭。相比 Fast JIT,LLVM JIT 覆盖更多架构且生成代码优化更好,但冷启动更慢。
- WAMR_BUILD_LAZY_JIT=1/0:Lazy JIT,在纯解释器构建下默认关闭;一旦启用 LLVM JIT 或 Fast JIT 且未显式置 0,则默认开启。
- WAMR_BUILD_QUICK_AOT_ENTRY:快速调用入口,AOT 或 LLVM JIT 启用时默认开启,用于加速宿主原生代码对 AOT/JIT 函数的调用。
Fast JIT 配置
- WAMR_BUILD_FAST_JIT=1/0:开关 Fast JIT,默认关闭。这是一个轻量 JIT:启动快、占用小、可移植性好,性能约为 AOT 的 50%(见 product-mini/README.md)。
- WAMR_BUILD_FAST_JIT_DUMP=1/0:将 Fast JIT 生成的代码 dump 到 stdout 用于调试,默认关闭。
⚠️ Fast JIT 与 Multi-tier JIT 目前仅覆盖少数架构(x86_64)。
libc 配置
- WAMR_BUILD_LIBC_BUILTIN=1/0:WASM 应用的内置 libc 子集,默认开启。
- WAMR_BUILD_LIBC_WASI=1/0:WASI libc 子集,默认开启。
- WAMR_BUILD_LIBC_UVWASI=1/0(实验特性):基于 uvwasi 的 WASI libc,默认关闭;当平台不支持
WAMR_BUILD_LIBC_WASI(如 Windows)时可尝试。 - WAMR_BUILD_LIBC_EMCC=1/0:emcc 兼容的 libc 子集,默认关闭。
⚠️ WAMR 并非在所有平台都是安全沙箱。在
WAMR_BUILD_LIBC_WASI不受支持的平台上改用 uvwasi(WAMR_BUILD_LIBC_UVWASI)是不安全的。
常用特性开关速查
- 线程相关:
WAMR_BUILD_THREAD_MGR、WAMR_BUILD_LIB_PTHREAD、WAMR_BUILD_LIB_WASI_THREADS默认均关闭;启用 lib-pthread 或 wasi-threads 时会自动连带启用 shared memory 与 thread manager。 - 内存相关:
WAMR_BUILD_SHARED_MEMORY(默认关)、WAMR_BUILD_BULK_MEMORY(默认开)、WAMR_BUILD_MEMORY64(默认关,仅支持 Classic Interpreter 与 AOT 模式,且要求 64 位目标)、WAMR_BUILD_GLOBAL_HEAP_POOL/WAMR_BUILD_GLOBAL_HEAP_SIZE(全局堆池,iwasm 应用默认 10 MB)。 - SIMD:
WAMR_BUILD_SIMD默认开启,支持 AOT、LLVM JIT 与 Fast Interpreter 模式;Fast Interpreter 模式下通过 SIMDe 库自动实现,无需额外标志。SIMD 不能与 Fast JIT 或"仅 Classic Interpreter"的组合共存,否则配置阶段会报错。 - 调试与观测:
WAMR_BUILD_DUMP_CALL_STACK(异常时打印调用栈)、WAMR_BUILD_MEMORY_PROFILING、WAMR_BUILD_MEMORY_TRACING、WAMR_BUILD_PERF_PROFILING、WAMR_BUILD_DEBUG_INTERP/WAMR_BUILD_DEBUG_AOT/WAMR_BUILD_DYNAMIC_AOT_DEBUG(源码级调试)。 - 沙箱安全:
WAMR_DISABLE_HW_BOUND_CHECK(默认在 linux/darwin/android/windows/vxworks 64 位平台开启硬件陷阱边界检查)、WAMR_CONFIGURABLE_BOUNDS_CHECKS(特权特性,允许iwasm --disable-bounds-checks关闭解释器模式下的边界检查)。 - 语言特性:
WAMR_BUILD_REF_TYPES(默认开)、WAMR_BUILD_TAIL_CALL(默认关)、WAMR_BUILD_EXCE_HANDLING(默认关,仅支持 Legacy 异常处理提案且仅 Classic Interpreter 模式可用)、WAMR_BUILD_GC(默认关,自动连带开启 reference types)、WAMR_BUILD_MULTI_MODULE(默认关,多模块不支持 Fast JIT/LLVM JIT 模式)。
完整的编译选项表(含 WAMR_APP_THREAD_STACK_SIZE_MAX、WAMR_BH_LOG、WAMR_BH_VPRINTF、WAMR_BUILD_SANITIZER 等近百个选项的逐一说明)请查阅 doc/build_wamr.md 中的 "All compilation flags" 一节。
构建 iwasm 可执行文件
构建 vmcore 后,若要得到一个可直接运行的命令行程序,在对应平台工程下构建 iwasm。以 Linux 为例:
cd product-mini/platforms/linux/
mkdir build && cd build
cmake ..
make
# iwasm is generated under current directory
Linux 上需先安装依赖(Ubuntu 22.04):
sudo apt install build-essential cmake g++-multilib libgcc-11-dev lib32gcc-11-dev ccache
Ubuntu 20.04 用 libgcc-9-dev lib32gcc-9-dev,Ubuntu 18.04 用 libgcc-8-dev lib32gcc-8-dev;Fedora 则执行 sudo dnf install glibc-devel.i686。默认配置下 Linux 构建启用 Fast Interpreter、AOT 与 Libc WASI,关闭 JIT,目标架构依宿主机位宽取 X86_64 或 X86_32。
按运行模式选择构建选项:
# (1) Fast Interpreter(默认)直接运行 wasm 文件
iwasm <wasm file>
# (2) 切换为 Classic Interpreter
cmake .. -DWAMR_BUILD_FAST_INTERP=0
# (3) AOT 模式:先用 wamrc 编译,再运行 AOT 文件
wamrc -o <AOT file> <WASM file>
iwasm <AOT file>
# (4) 启用 LLVM JIT:先构建 LLVM 库
cd product-mini/platforms/linux/
./build_llvm.sh # LLVM 源码克隆到 <wamr_root_dir>/core/deps/llvm 并自动构建
cd build
cmake .. -DWAMR_BUILD_JIT=1
make
# 如需关闭默认开启的 Lazy 编译
cmake .. -DWAMR_BUILD_JIT=1 -DWAMR_BUILD_LAZY_JIT=0
# (5) 启用 Fast JIT
cmake .. -DWAMR_BUILD_FAST_JIT=1
# (6) 启用 Multi-tier JIT
cmake .. -DWAMR_BUILD_FAST_JIT=1 -DWAMR_BUILD_JIT=1
其余平台要点:
- MacOS:安装 Xcode 与 cmake(
brew install cmake),在product-mini/platforms/darwin/下执行cmake .. && make;默认同样启用 Fast Interpreter、AOT 与 Libc WASI。 - Windows:需 MSVC 与 cmake,在
product-mini/platforms/windows/下执行cmake .. && cmake --build . --config Release,产物为./Release/iwasm.exe。 - Windows (MinGW):在 MSYS2 环境先安装
mingw-w64-x86_64-cmake、mingw-w64-x86_64-gcc等包,然后:
cmake .. -G"Unix Makefiles" -DWAMR_DISABLE_HW_BOUND_CHECK=1
由于硬件陷阱边界检查被禁用,用 wamrc 生成 AOT 文件时应加 --bounds-checks=1 以生成边界检查指令保障沙箱安全。注意 MinGW 目前尚未完全支持 WASI。
- Android:下载 Android SDK Command line tools,用 sdkmanager 安装
build-tools;29.0.3、cmake;3.10.2.4988404、ndk;latest、platforms;android-29等组件,导出ANDROID_HOME与ANDROID_NDK_LATEST_HOME后在product-mini/platforms/android/构建,产物位于distribution/wasm。可用-DWAMR_BUILD_TARGET与-DANDROID_ABI组合出 x86/x86_64/armeabi-v7a/arm64-v8a 等目标。 - RT-Thread:通过
scons --menuconfig在 "RT-Thread online packages → tools packages" 中启用 WAMR 软件包,再用 menuconfig 勾选解释器/Fast Interpreter、built-libc、AOT 等特性,最后pkgs --update && scons生成rtthread.bin。 - VxWorks(验证版本 7 SR0620):先构建 VSB 并导出 toolchain 路径,再在
product-mini/platforms/vxworks/下构建;创建 VIP 时需加入INCLUDE_POSIX_PTHREADS、INCLUDE_SHARED_DATA、INCLUDE_SHL等组件。 - Zephyr、NuttX、ESP-IDF、AliOS-Things 等嵌入式平台:分别参考 product-mini/README.md 中对应小节(Zephyr 见其 sample 目录 README,NuttX 在 Kconfig 中启用,ESP-IDF 需 4.3.1+ 并配置工具链文件与
IDF_TARGET,AliOS-Things 需拷贝平台目录并链接<wamr_root_dir>)。 - Docker:执行
cd ci && ./build_wamr.sh,生成的 Linux 兼容库(libiwasm.so、libvmlib.a)与iwasm可执行文件会拷贝到build_out。 - Cross-compilation:在 X86 开发机上构建 ARM 目标时,用
CMAKE_TOOLCHAIN_FILE指定交叉工具链:
cmake .. -DCMAKE_TOOLCHAIN_FILE=$TOOL_CHAIN_FILE \
-DWAMR_BUILD_PLATFORM=linux \
-DWAMR_BUILD_TARGET=ARM
构建 wamrc AOT 编译器
iwasm 同时支持 .wasm 二进制与 .aot 文件;wamrc 负责把 .wasm 编译为 .aot。构建 wamrc 的步骤如下(来源:gitbook/tutorial/build-tutorial/build_wamrc.md)。
Linux(Ubuntu 20.04 示例,先安装依赖):
sudo apt-get install git build-essential cmake g++-multilib libgcc-9-dev lib32gcc-9-dev ccache
cd wamr-compiler
./build_llvm.sh # 或 "./build_llvm_xtensa.sh" 以支持 xtensa 目标
mkdir build && cd build
cmake .. # 或 "cmake .. -DWAMR_BUILD_PLATFORM=darwin" 用于 MacOS
make
# wamrc 生成于当前目录
build_llvm.sh 会克隆并自动构建 LLVM(源码位于 <wamr_root_dir>/core/deps/llvm)。对于本地开发中频繁重建 LLVM 的场景,可通过 build-scripts/build_llvm.py 启用 ccache 加速增量构建:
cd <wamr_root_dir>/build-scripts
python3 build_llvm.py --arch X86 --use-ccache
Windows:
cd wamr-compiler
python build_llvm.py
mkdir build && cd build
cmake ..
cmake --build . --config Release
# wamrc.exe 生成于 .\Release 目录
wamrc 构建完成后的典型用法:
wamrc -o <AOT file> <WASM file>
iwasm <AOT file>
配置组合实战示例
vmcore 的构建选项可以自由组合。以下示例来自 doc/build_wamr.md 的 "Combination of configurations" 一节,可直接在任意平台构建目录中执行:
# 禁用解释器,启用 AOT 与 WASI,面向 linux
cmake .. -DWAMR_BUILD_INTERP=0 -DWAMR_BUILD_AOT=1 -DWAMR_BUILD_LIBC_WASI=1 -DWAMR_BUILD_PLATFORM=linux
# 启用解释器,禁用 AOT 与 WASI,目标架构 X86_32
cmake .. -DWAMR_BUILD_INTERP=1 -DWAMR_BUILD_AOT=0 -DWAMR_BUILD_LIBC_WASI=0 -DWAMR_BUILD_TARGET=X86_32
# Fast Interpreter 模式下启用 SIMD(同时打开 SIMD 与 SIMDe 库)
cmake .. -DWAMR_BUILD_INTERP=1 -DWAMR_BUILD_FAST_INTERP=1 -DWAMR_BUILD_SIMD=1 -DWAMR_BUILD_LIB_SIMDE=1
# 配合 Valgrind 调试时的建议起点
cmake .. -DCMAKE_BUILD_TYPE=Debug \
-DWAMR_DISABLE_HW_BOUND_CHECK=0 \
-DWAMR_DISABLE_WRITE_GS_BASE=0
# 启用最小 Lime1 特性集(关闭默认开启的 bulk memory、reference types、SIMD;
# LIME1 自身会开启 bulk-memory-opt、call-indirect-overlong 与 extended constant expressions)
cmake .. -DWAMR_BUILD_LIME1=1 -DWAMR_BUILD_BULK_MEMORY=0 -DWAMR_BUILD_REF_TYPES=0 -DWAMR_BUILD_SIMD=0
构建注意事项与验证
- 解释器与 AOT 至少启用其一,否则运行时无法执行任何模块。
- 部分组合在配置阶段即报错:例如 SIMD 与 Fast JIT 的组合、SIMD 与"仅 Classic Interpreter"的组合、memory64 在 32 位目标上的组合等,构建脚本(build-scripts/unsupported_combination.cmake)会提前拦截。
- 默认值来源有两层:
build-scripts内部(如config_common.cmake、runtime_lib.cmake)保证平台无关的默认值(例如 bulk memory 默认开、shrunk memory 默认开);而WAMR_BUILD_INTERP、WAMR_BUILD_AOT、WAMR_BUILD_JIT等选项的默认值则由顶层构建入口(仓库根 CMakeLists.txt 或 product-mini 平台文件)决定。因此同一选项在不同构建入口下的默认值可能不同,组合配置时建议显式声明。 - Fast JIT 目前仅覆盖 x86_64;多模块、共享堆、GC 等特性在 Fast JIT 模式下不受支持。
- 构建完成后即可用 iwasm 运行 wasm/AOT 文件验证,例如
iwasm <wasm file>或iwasm <AOT file>;AOT 文件需先用 wamrc 生成。
通过本文覆盖的构建矩阵、平台步骤与配置组合,你可以按需裁剪出面向桌面、服务器或 MCU 场景的 WAMR 运行时,并进一步阅读 doc/build_wamr.md(完整编译选项)、product-mini/README.md(全平台构建细节)与 doc/port_wamr.md(新平台移植)深入实践。