WAMR 系列教程:如何构建 wamrc AOT 编译器(Linux / Windows 完整指南)
WAMR 系列教程:如何构建 wamrc AOT 编译器(Linux / Windows 完整指南)
本篇教程围绕 WebAssembly Micro Runtime(WAMR)的核心工具 wamrc 展开,详细介绍其在 Linux 与 Windows 平台上的完整构建流程:从安装 LLVM 依赖、执行 build_llvm.sh 脚本,到使用 CMake 编译出可执行文件,最后掌握 wamrc 的命令行参数用法,将 WASM 二进制文件编译为可供 iwasm 运行的 AOT 文件。读完本文,你将能够独立完成 wamrc 的构建、交叉目标编译,并正确配置 AOT 输出格式与各项编译特性。
wamrc 在 WAMR 中的定位
iwasm 运行时同时支持两类可执行文件:WASM 二进制文件(字节码)与 AOT 文件(提前编译后的本地机器码)。其中 AOT 文件由 wamrc AOT 编译器生成——它读取 WASM 二进制文件,借助 LLVM 后端将其编译为特定目标架构的 AOT 文件,该文件同样由 iwasm 加载运行。
AOT 文件相比解释执行拥有更优的性能,且不需要像 JIT 那样在运行时编译,因此非常适合资源受限或追求稳定启动性能的场景。从源码结构看,wamrc 的完整实现位于 wamr-compiler/main.c:它先通过 wasm_runtime_load 加载 WASM 模块,再依次调用 aot_create_comp_data、aot_create_comp_context 与 aot_compile_wasm 完成编译,最后根据输出格式调用 aot_emit_aot_file(或 aot_emit_object_file、aot_emit_llvm_file)写出结果文件。
构建前置条件
在正式构建 wamrc 之前,需要确保系统已安装必要的依赖。以 Ubuntu 20.04 为例,可执行如下命令(在 Debian/Ubuntu 系发行版上):
sudo apt-get install git build-essential cmake g++-multilib libgcc-9-dev lib32gcc-9-dev ccache
其中 g++-multilib、libgcc-9-dev、lib32gcc-9-dev 用于在 64 位主机上支持 32 位目标(如 X86_32 的交叉编译);ccache 则用于加速 LLVM 的增量编译。若使用其他发行版,请按包管理器规则安装对应等价包(例如 Fedora 可安装 glibc-devel.i686)。
Linux 平台构建 wamrc
在 Linux 上构建 wamrc 的完整命令序列如下(以仓库根目录为起点):
cd wamr-compiler
./build_llvm.sh # 或者使用 ./build_llvm_xtensa.sh 以支持 xtensa 目标
mkdir build && cd build
cmake .. # MacOS 平台可改为 cmake .. -DWAMR_BUILD_PLATFORM=darwin
make
# wamrc 生成于当前目录(build 目录)下
第一步:build_llvm.sh —— 获取并编译 LLVM 依赖
wamrc 基于 LLVM 实现代码生成,因此必须先构建 LLVM 库。wamr-compiler/build_llvm.sh 是一个封装脚本:它创建一个临时 Python 虚拟环境,安装 build-scripts/requirements.txt 中声明的依赖后,转调 build-scripts/build_llvm.py 完成 LLVM 的克隆与编译。
该脚本内部的关键行为:
- LLVM 源码被克隆至仓库的
core/deps/llvm目录(默认使用官方 llvm-project 的llvmorg-18.1.8分支;xtensa 平台则使用 espressif 的xtensa_release_18.1.2分支); - 默认编译 X86、AArch64、ARM、Mips、RISCV 等后端(可通过
--arch参数指定,如--arch ARM Mips X86),实验性后端 ARC、Xtensa 会通过LLVM_EXPERIMENTAL_TARGETS_TO_BUILD额外开启; - 采用 Ninja 构建并打包为 LLVM 安装包后解压到
build目录,供后续cmake阶段通过llvm_env.cmake自动发现。
如果你需要支持 xtensa 目标,直接运行:
./build_llvm_xtensa.sh
它等价于 ./build_llvm.sh --platform xtensa(见 wamr-compiler/build_llvm_xtensa.sh),会拉取 espressif 维护的 LLVM 分支并启用 Xtensa 实验性后端。
本地开发时若需要频繁重建 LLVM,可以显式启用 ccache 加速增量编译:
cd <wamr_root_dir>/build-scripts
python3 build_llvm.py --arch X86 --use-ccache
提示:
build_llvm.py还支持--use-clang(用 clang/clang++/lld 替代 gcc 工具链,macOS 除外)、--project clang lldb(额外构建项目,lldb 用于 AOT 源码级调试)、--extra-cmake-flags(透传自定义 CMake 参数)等选项。
第二步:CMake 配置与编译
进入 wamr-compiler 目录后执行 cmake ..。此处的 .. 指向 wamr-compiler/CMakeLists.txt,该文件会:
- 自动检测
WAMR_BUILD_PLATFORM(默认取CMAKE_SYSTEM_NAME,如linux); - 自动检测
WAMR_BUILD_TARGET(默认取主机架构,如X86_64、AARCH64、ARM_32等,可通过-DWAMR_BUILD_TARGET=XXX覆盖); - 默认启用 SIMD(
-DWAMR_BUILD_SIMD=0可关闭)、共享内存、引用类型、memory64、GC 等一系列编译特性; - 构建三个产物:静态库
vmlib(运行时核心)、aotclib(编译相关源码)以及可执行文件wamrc(由main.c生成)。
MacOS 注意事项:在 MacOS 上请使用 cmake .. -DWAMR_BUILD_PLATFORM=darwin 指定平台,其余步骤与 Linux 一致。
编译成功后,wamrc 可执行文件即出现在 build 目录下,可直接用于将 WASM 编译为 AOT 文件:
wamrc -o test.aot test.wasm
Windows 平台构建 wamrc
在 Windows 上构建 wamrc 的步骤如下(需预先安装 MSVC 与 CMake 并加入命令行环境):
cd wamr-compiler
python build_llvm.py
mkdir build && cd build
cmake ..
cmake --build . --config Release
# wamrc.exe 生成于 .\Release 目录下
与 Linux 流程的对应关系:
python build_llvm.py对应 Linux 的./build_llvm.sh,wamr-compiler/build_llvm.py 只是简单地转调build-scripts/build_llvm.py。后者在 Windows 下会使用 MSVC 的 x64 生成器(-A x64)并以--config Release并行构建;cmake ..之后使用cmake --build . --config Release(对应 Linux 的make)完成编译,产物wamrc.exe位于.\Release目录。
从 wamr-compiler/CMakeLists.txt 可以看到,Windows 分支会额外启用 ASM_MASM 语言并定义 COMPILING_WASM_RUNTIME_API;同时针对 MSVC 设置 /SAFESEH:NO 链接标志以适配 AOT 代码生成需求。
wamrc 常用命令行参数
构建完成后,可通过 wamrc --help(实际对应 wamr-compiler/main.c 中的 print_help())查看全部选项。以下按用途分类介绍常用参数:
目标平台与 ABI 控制
| 参数 | 说明 |
|---|---|
--target=<arch-name> |
指定目标架构,格式为 <arch><sub>,如 x86_64、i386、aarch64、arm、thumb、xtensa、mips、riscv64、riscv32;默认为主机架构。也可直接传 <arch>-<vendor>-<os>-<abi> 三元组形式,此时 --target-abi、--cpu、--cpu-features 将被忽略。使用 --target=help 列出全部支持的目标 |
--target-abi=<abi> |
指定目标 ABI,如 gnu、eabi、gnueabihf、msvc;默认在非 riscv 目标上为 gnu,riscv64/riscv32 默认为 lp64d/ilp32d。使用 --target-abi=help 列出全部支持的 ABI |
--cpu=<cpu> |
指定目标 CPU(默认为宿主机 CPU,如 skylake)。使用 --cpu=help 列出全部支持的 CPU |
--cpu-features=<features> |
启用或禁用 CPU 特性,用 +feature 启用、-feature 禁用,如 --cpu-features=+feature1,-feature2 |
典型用法(交叉编译到 32 位 x86 并生成目标文件):
wamrc --target=i386 -o test.aot test.wasm
wamrc --target=i386 --format=object -o test.o test.wasm
优化与代码体积
--opt-level=n:优化级别 0~3,默认 3;--size-level=n:代码体积级别 0~3,默认 3,对应 Large / Medium / Kernel / Small 代码模型。注意在 Windows 与 MacOS(非 arm64)上,若未显式指定,main.c会将其自动降为 1,原因是这些平台无法 mmap 出 0-2GB 内存,可能无法满足部分 AOT 重定位操作的要求;MSVC ABI 下同样会自动设为 1;--stack-usage=<file>:生成栈使用报告文件,类似clang -fstack-usage。
边界检查与安全
--bounds-checks=1/0:启用/禁用内存访问的软件边界检查。64 位平台默认关闭(改用硬件 trap,SGX 或 memory64 场景除外,此时默认软件检查);32 位平台默认开启软件检查。注意:--bounds-checks=0会启用一些优化,导致生成的 AOT 模块与不支持硬件边界检查的运行时不兼容。在 MinGW 等禁用硬件边界检查的平台上编译 AOT 文件时,应显式加上--bounds-checks=1以保证沙箱安全;--stack-bounds-checks=1/0:单独控制原生栈的边界检查,未设置时与--bounds-checks保持一致;-sgx:为 Intel SGX 平台生成代码,同时会把 size level 强制置为 0 并启用软件边界检查。
输出格式
--format=<format>:指定输出文件格式,支持四种取值:
| 取值 | 含义 |
|---|---|
aot(默认) |
AOT 文件(二进制格式,iwasm 可直接运行) |
object |
原生目标文件(.o) |
llvmir-unopt |
未优化的 LLVM IR |
llvmir-opt |
优化后的 LLVM IR |
例如生成可继续参与原生链接的目标文件:wamrc --target=i386 --format=object -o test.o test.wasm。
WebAssembly 特性开关
| 参数 | 说明 |
|---|---|
--disable-bulk-memory |
关闭 MVP bulk memory 特性(默认开启) |
--enable-bulk-memory-opt |
启用 bulk memory 优化 |
--enable-extended-const |
启用 extended const expr 特性 |
--enable-multi-thread |
启用多线程特性,并自动连带启用 bulk-memory 与 thread-mgr |
--enable-tail-call |
启用 post-MVP 尾调用特性 |
--disable-simd |
关闭 128 位 SIMD(目前仅 x86-64 与 aarch64 支持,默认在这两个目标上开启) |
--disable-ref-types |
关闭引用类型特性(GC 开启时会被强制关闭) |
--enable-call-indirect-overlong |
启用 call indirect overlong 特性 |
--enable-gc |
启用 GC(垃圾回收)特性,开启后会自动关闭引用类型、启用标准栈帧 |
--enable-lime1 |
启用 Lime1 最小特性集,会自动连带启用 call-indirect-overlong、bulk-memory-opt 与 extended-const |
调试与性能分析
--enable-dump-call-stack:启用 AOT 模块的调用栈追踪(配合运行时的WAMR_BUILD_DUMP_CALL_STACK使用,见 doc/build_wamr.md);--call-stack-features=<features>:定制调用栈内容,可用特性包括bounds-checks、ip、func-idx、trap-ip、values,逗号分隔;仅在--enable-dump-call-stack生效时起作用;--enable-perf-profiling:启用函数级性能剖析(自动开启 func-idx 调用栈特性);--enable-memory-profiling:启用内存用量剖析(同时自动开启栈用量估算);--enable-linux-perf:启用 Linux perf 支持,用于生成火焰图(仅 Linux 构建可用);--emit-custom-sections=<section names>:将指定的自定义段(逗号分隔)保留到 AOT 文件中,例如--emit-custom-sections=name可在启用调用栈转储时保留函数名段。
执行模式与平台优化
--xip:--enable-indirect-mode与--disable-llvm-intrinsics的组合简写,用于生成跨平台/位置无关的可执行代码;--enable-indirect-mode:通过符号表间接调用函数而非直接调用;--disable-llvm-intrinsics:禁用 LLVM 内建 intrinsics;配合--enable-builtin-intrinsics=<flags>可选择性启用(如i32.clz、i64.ctz等,完整列表见 doc/xip.md);--enable-segue[=<flags>]:在 Linux x86-64 上使用段寄存器 GS 作为线性内存基址以提升性能,可用标志包括i32.load、i64.store、v128.load等(逗号分隔,不带参数表示全部启用);--enable-shared-heap/--enable-shared-chain:启用共享堆 / 共享堆链特性(后者会显著增大代码体积);--disable-llvm-lto、--enable-llvm-pgo、--enable-llvm-passes=<passes>、--use-prof-file=<file>:LLVM LTO、PGO 与自定义 pass 相关控制;--native-lib=<lib>:将共享库(.so)注册到 WASM 模块中,可多次指定,例如--native-lib=test1.so --native-lib=test2.so(需平台支持 dlopen);--invoke-c-api-import:将未知导入函数视为 wasm-c-api 导入函数,从 AOT 代码快速调用;--mllvm=<option>:透传 LLVM 命令行选项;-v=n:设置日志详细级别 0~5,默认 2,数值越大日志越多;--version/--llvm-version:分别显示 wamrc 版本与 LLVM 版本信息。
快速验证与帮助
main.c 中内置了一个 8 字节的 dummy_wasm_file(WASM 魔数头 + 版本号)。当使用 --target=help、--target-abi=help、--cpu=help、--cpu-features=+help 时,wamrc 会加载该虚拟文件以列出可选项,无需真实输入文件。
构建与使用 iwasm 验证 AOT 文件
wamrc 生成的 AOT 文件由 iwasm 运行时加载执行。iwasm 本身的构建方法见 product-mini/README.md(Linux 默认启用 fast interpreter、AOT 与 Libc WASI,默认关闭 JIT)。构建完成后,完整的使用链路为:
# 1. 用 wamrc 将 WASM 编译为 AOT 文件
wamrc -o <AOT file> <WASM file>
# 2. 用 iwasm 直接运行 AOT 文件
iwasm <AOT file>
一个完整的示例:
cd wamr-compiler && ./build_llvm.sh && mkdir build && cd build && cmake .. && make
# 假设已有 test.wasm
./wamrc -o test.aot test.wasm
# 在 product-mini/platforms/linux 下构建 iwasm 后执行
iwasm test.aot
在 Linux 上运行 AOT 文件时,若构建 iwasm 时启用了硬件边界检查(默认),请保持 wamrc 生成的 AOT 文件与之匹配;若因平台限制禁用了硬件边界检查(如 MinGW),务必按前文所述在 wamrc 中显式传入 --bounds-checks=1。
常见问题与要点回顾
- 找不到 LLVM:
cmake ..阶段会通过 build-scripts/llvm_env.cmake 解析LLVM_DIR,因此请确保已先执行./build_llvm.sh(或python build_llvm.py)完成 LLVM 的克隆与构建。 - 32 位目标支持:在 64 位主机上编译 X86_32 目标时,CMakeLists 会自动追加
-m32链接标志,故需安装 multilib 相关包(如g++-multilib、lib32gcc-9-dev)。 - 目标与平台的区别:
WAMR_BUILD_PLATFORM决定运行平台(对应core/shared/platform下的目录),WAMR_BUILD_TARGET/--target决定目标 CPU 架构,二者需按实际部署环境正确组合。 - 产物位置:Linux/macOS 下 wamrc 位于
wamr-compiler/build/,Windows 下wamrc.exe位于wamr-compiler/build/Release/。
至此,你已经掌握了 wamrc 在主流平台上的完整构建流程与核心命令行用法。更深入的 AOT 相关特性(如 XIP、SEGUE 优化、PGO、Linux perf 火焰图)可继续阅读 doc/perf_tune.md、doc/xip.md 以及 doc/build_wamr.md 中的对应章节。