WAMR 系列教程:如何构建 wamrc AOT 编译器(Linux / Windows 完整指南)

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

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。

常见问题与要点回顾

  1. 找不到 LLVM:cmake .. 阶段会通过 build-scripts/llvm_env.cmake 解析 LLVM_DIR,因此请确保已先执行 ./build_llvm.sh(或 python build_llvm.py)完成 LLVM 的克隆与构建。
  2. 32 位目标支持:在 64 位主机上编译 X86_32 目标时,CMakeLists 会自动追加 -m32 链接标志,故需安装 multilib 相关包(如 g++-multilib、lib32gcc-9-dev)。
  3. 目标与平台的区别:WAMR_BUILD_PLATFORM 决定运行平台(对应 core/shared/platform 下的目录),WAMR_BUILD_TARGET/--target 决定目标 CPU 架构,二者需按实际部署环境正确组合。
  4. 产物位置: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 中的对应章节。

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