WAMR 构建实战指南:iwasm vmcore 与 wamrc AOT 编译器的完整构建教程

原创2026-10-09 15:05:161,854 阅读
文章标签:语言运行时WebAssembly解释器JIT编译编译器嵌入式物联网虚拟化

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):

若要将 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。
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

构建注意事项与验证

  1. 解释器与 AOT 至少启用其一,否则运行时无法执行任何模块。
  2. 部分组合在配置阶段即报错:例如 SIMD 与 Fast JIT 的组合、SIMD 与"仅 Classic Interpreter"的组合、memory64 在 32 位目标上的组合等,构建脚本(build-scripts/unsupported_combination.cmake)会提前拦截。
  3. 默认值来源有两层: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 平台文件)决定。因此同一选项在不同构建入口下的默认值可能不同,组合配置时建议显式声明。
  4. Fast JIT 目前仅覆盖 x86_64;多模块、共享堆、GC 等特性在 Fast JIT 模式下不受支持。
  5. 构建完成后即可用 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(新平台移植)深入实践。

登录后查看全文
wasm-micro-runtime