Meson 工程手册：让构建目录说清目标、机器与依赖来源

Meson 配置状态、机器模型与依赖回退源码声明目标，setup 固化配置，Ninja 执行生成图；native/cross file 与 Wrap fallback 决定构建发生在哪台机器、依赖来自哪里。高清原图

同一个 C/C++ 仓库，在开发机上链接系统库，在 CI 中却悄悄下载 subproject；改了编译器后继续复用旧 builddir，直到链接阶段才暴露 ABI 错误；交叉编译时生成器被编译成目标架构，构建到一半才发现无法在构建机运行。这些现象看似分散，根因都在 Meson 的三个边界：源码树描述什么、builddir 记住了什么、依赖和程序属于哪台机器。

Meson 是上层构建系统。它读取 meson.build 和 meson.options，探测工具链与依赖，生成后端构建图；默认的 Ninja backend 再负责增量调度，编译器和链接器生成最终产物。把 Meson 当作编译器，或者直接修 build.ninja，都会失去真正的配置来源。

先确认命令与构建现场

Meson 通常作为 Python 包安装，也可能由操作系统包管理器或开发环境统一提供。团队入口先输出身份，不要只确认“命令存在”：

meson --version
ninja --version
cc --version
python --version

Windows 使用 MSVC 时，还要在已初始化编译环境的终端中确认 cl 和 link。不要把个人 Python 用户目录、虚拟环境绝对路径或 Visual Studio 临时环境写进仓库；项目应固定可接受的 Meson 版本区间，并由 CI 镜像、工具清单或受控安装脚本提供工具。

源码树与构建目录应分开。下面约定源码在当前目录，构建状态在 build/debug，暂存安装树在 build/stage。builddir 可以删除重建，源码树不应混入对象文件和探测结果。

用最小工程跑通完整闭环

创建 meson.build：

project(
  'hello-meson',
  'c',
  version: '1.0.0',
  default_options: ['c_std=c11', 'warning_level=2'],
)

hello_lib = static_library(
  'hello',
  'src/hello.c',
  include_directories: include_directories('include'),
  install: true,
)

hello_dep = declare_dependency(
  link_with: hello_lib,
  include_directories: include_directories('include'),
)

app = executable('hello-app', 'src/main.c', dependencies: hello_dep, install: true)

test('hello-smoke', app)

install_headers('include/hello.h', subdir: 'hello')

目录中再放入 include/hello.h、src/hello.c 和 src/main.c。第一次配置显式选择后端和构建类型：

meson setup build/debug --backend=ninja --buildtype=debug
meson compile -C build/debug
meson test -C build/debug --print-errorlogs
meson install -C build/debug --destdir "$PWD/build/stage"

setup 读取工程、探测编译器与依赖，并把选择固化到 builddir；compile 调用后端执行目标；test 运行已注册测试；install 按安装声明复制文件。DESTDIR 用于暂存打包根目录，prefix 决定安装树内部前缀，两者不是一回事。安装路径异常时先查看：

meson configure build/debug | grep prefix
find build/stage -type f

Windows PowerShell 可把暂存路径写为环境变量后传给 --destdir，避免依赖 POSIX 的内联赋值语法。

Builddir 是配置状态，不是普通输出目录

Meson 的增量能力建立在持久 builddir 上。编译器身份、探测结果、option、依赖位置和后端都与该目录绑定。日常修改 option 使用：

meson configure build/debug -Dbuildtype=release
meson compile -C build/debug

源码中的 meson.build 变化通常会触发自动重配置；需要明确重跑配置时使用：

meson setup --reconfigure build/debug

--reconfigure 保留已有选择并重新配置，适合工程声明或可重探测输入变化。更换编译器、cross file、sysroot、backend 或大范围机器输入时，优先创建新的 builddir。确实要保留目录名并从头配置，可使用：

meson setup --wipe build/debug --buildtype=debug

--wipe 会清掉构建状态后重新 setup，不等同于普通 target clean。执行前确认目录是可再生 builddir，不能把未经验证的路径交给自动清理脚本。

Ninja backend 执行图，不拥有工程模型

Meson 默认生成 Ninja 图。推荐调用 meson compile -C builddir，因为它提供稳定的上层入口，也能在其他 backend 下工作。需要诊断 Ninja 时再下沉：

ninja -C build/debug -t targets
ninja -C build/debug -d explain
ninja -C build/debug -t commands hello-app

build.ninja、.ninja_log 和 .ninja_deps 都属于 builddir。生成图错误时应修 meson.build、machine file、option 或生成器版本，然后重配置；手工修改 build.ninja 会在下一次重生成时丢失，而且让 CI 无法复现。

并行度最终由后端调度，但资源模型不能只看 CPU 核数。链接器内存、代码生成器许可证、磁盘 I/O 和容器限额都可能成为上限。团队可通过统一入口传递并行参数，并在 CI 保存峰值资源与耗时，而不是无条件把 -j 拉满。

Target 与依赖对象承载传播关系

executable()、library()、static_library()、shared_library() 和 custom_target() 都会创建目标。依赖关系应通过 target、dependency() 和 declare_dependency() 表达，不靠全局拼接 include 路径和链接参数。

上面的 hello_dep 把头文件目录和库绑定成一个可消费对象。真实项目还可以用 both_libraries() 生成静态与动态变体，用 executable(..., native: true) 明确交叉构建中的宿主工具，用 generator() 表达逐输入代码生成。关键不是 API 数量，而是每条边都回答：谁消费、传播什么、在哪台机器运行。

查看已生成目标和 build option：

meson introspect build/debug --targets
meson introspect build/debug --buildoptions
meson introspect build/debug --dependencies

机器可读 JSON 比解析人类日志稳定，适合 IDE、审计脚本和 CI 证据采集。不要依赖未声明稳定性的内部文件结构代替 meson introspect。

Option 要表达产品选择，而不是个人机器路径

项目 option 放在 meson.options：

option('cli', type: 'feature', value: 'auto', description: 'Build command-line tool')
option('tls_backend', type: 'combo', choices: ['openssl', 'mbedtls'], value: 'openssl')
option('max_connections', type: 'integer', min: 1, max: 4096, value: 256)

在 meson.build 中读取：

cli_opt = get_option('cli')
tls_backend = get_option('tls_backend')

feature 的 enabled、disabled、auto 很适合可选依赖：强制开启时缺依赖应失败，禁用时不探测，自动时允许按环境决定。团队交付配置不要长期依赖 auto，否则开发机与 CI 可能生成不同能力集；应在 CI preset 或命令入口显式固定。

编译器、sysroot、pkg-config 路径等机器事实进入 native/cross file；业务能力、是否构建测试、库形态等工程选择进入 option。把个人 SDK 绝对路径写成 project option 会让配置不可移植，也容易泄露本机信息。

Subproject 与 Wrap 决定依赖从哪里来

Meson 先用 dependency() 查找外部依赖，也可以在缺失时回退到 subprojects/ 中的源码工程：

zlib_dep = dependency(
  'zlib',
  version: '>=1.2.13',
  fallback: ['zlib', 'zlib_dep'],
  default_options: ['tests=disabled'],
)

这里的第二个 zlib_dep 是子项目通过 meson.override_dependency() 或变量提供的依赖对象。subprojects/zlib.wrap 可以描述归档、Git 或 WrapDB 来源。Wrap 是获取与嵌入源码的机制，不是完整 lockfile，也不自动证明来源可信。

依赖策略通过 setup 参数显式控制：

meson setup build/system --wrap-mode=nofallback
meson setup build/vendor --wrap-mode=forcefallback
meson setup build/offline --wrap-mode=nodownload

nofallback 用于发行版或系统依赖优先场景，forcefallback 用于验证 vendored 路径，nodownload 禁止配置阶段下载但要求材料已存在。官方的 Subprojects 与 Wrap dependency system 说明了这些模式和 wrap 文件行为。

同一进程混用系统版与 subproject 版的同名库，可能带来符号、ABI 和全局状态冲突。CI 至少分别验证“只用批准系统依赖”和“只用受控 fallback”中的实际交付路线，并保存 meson introspect --dependencies 输出。Wrap 文件、补丁、下载哈希、许可证和更新责任都应进入依赖评审。

离线构建不是把开发机的 subprojects/packagecache 整体打包就算完成。应先准备批准的源码归档与 wrap，启用 --wrap-mode=nodownload，在断网或阻断源站的环境中从空 builddir 重建，确认没有隐式回退公网。

Native file 固定构建机工具，Cross file 描述目标机

machine file 使用 INI 风格。native file 可固定本机构建的编译器、工具和公共参数：

[binaries]
c = 'clang'
cpp = 'clang++'
pkg-config = 'pkg-config'

[built-in options]
c_std = 'c11'
warning_level = '2'

meson setup build/clang --native-file config/clang.ini

cross file 则描述目标环境：

[binaries]
c = 'aarch64-linux-gnu-gcc'
ar = 'aarch64-linux-gnu-ar'
strip = 'aarch64-linux-gnu-strip'
pkg-config = 'aarch64-linux-gnu-pkg-config'

[host_machine]
system = 'linux'
cpu_family = 'aarch64'
cpu = 'armv8-a'
endian = 'little'

[properties]
sys_root = '/opt/sdk/sysroot'
needs_exe_wrapper = true

[built-in options]
c_args = ['--sysroot=/opt/sdk/sysroot']
c_link_args = ['--sysroot=/opt/sdk/sysroot']

meson setup build/aarch64 --cross-file config/aarch64.ini
meson compile -C build/aarch64

示例中的 SDK 路径需要由受控环境提供，仓库中更适合保存模板、相对路径约定或由 CI 生成的机器文件。凭证、内部下载地址和个人目录不得进入 machine file。

官方 Cross and Native File reference 还支持 constants、properties、built-in options 与项目 option。命令行优先级高于 machine file，machine file 又高于构建声明中的默认值；排障时必须查看最终配置，不要只读文件猜结果。

Build、Host、Target 三台机器不要凭名字猜

Meson 的机器模型沿用经典交叉编译语义：

build machine：Meson 与编译过程实际运行的机器。host machine：当前生成的二进制将运行的机器。target machine：当生成出来的程序本身又是编译器等工具时，它将生成代码所面向的机器。

普通本机构建三者相同。常见交叉编译只需要区分 build 与 host；Canadian Cross 等场景才真正用到第三台 target machine。

代码生成器必须在 build machine 运行，因此要标记为 native: true，它依赖的库也应在 build machine context 中解析。最终应用和目标库属于 host machine。若需要在构建期间运行 host 二进制，必须提供 exe_wrapper，例如 QEMU；否则 Meson 应把它视为不可运行，而不是碰运气执行。

meson introspect build/aarch64 --machines

这份输出应成为交叉构建证据。只看到编译器前缀正确还不够，pkg-config、sysroot、生成器、测试执行器和依赖库架构也必须对齐。

测试、Benchmark 与安装验证是不同证据

注册测试后，常用入口是：

meson test -C build/debug
meson test -C build/debug --print-errorlogs
meson test -C build/debug --suite unit
meson test -C build/debug --repeat 3

测试默认并行，依赖共享端口、临时目录或全局环境的用例需要显式隔离，不能靠 --num-processes 1 长期掩盖竞态。交叉构建中无法运行目标程序时，可只完成编译与安装检查，或配置受控 exe wrapper；CI 报告应区分“已编译”和“已在目标等价环境执行”。

安装验证不能停在 meson install 成功。把产物安装到临时根目录后，用一个空白消费工程通过 pkg-config、CMake config 或声明的接口重新链接，才能发现遗漏头文件、错误 rpath、缺少传递依赖和 Debug/Release 混用。

Introspection 把配置事实变成可比较证据

除了 targets、options 与 dependencies，常用查询还有：

meson introspect build/debug --projectinfo
meson introspect build/debug --tests
meson introspect build/debug --installed
meson introspect build/debug --compilers
meson introspect build/debug --machines

CI 可以把这些 JSON 与 Meson/Ninja/编译器版本、setup 命令、machine file 哈希一起保存。发生“本机成功、CI 失败”时，先比较最终 option、编译器、机器与依赖来源，再比较编译命令，通常比盲目 wipe 更快。

meson configure builddir 适合人读，meson introspect 适合程序读。两者都来自配置后的 builddir，因此不能用来证明源码在另一台机器上会得到相同结果；真正的可复现性仍要靠空 builddir 重建。

常见失败沿状态、来源和机器排查

换了编译器却仍出现旧 ABI

查看 meson introspect --compilers 与实际编译命令。如果 builddir 曾由另一套工具链配置，创建新目录；不要只改 CC 后继续复用，因为环境变量通常只在初次 setup 时决定编译器。

本机找到依赖，CI 开始下载 subproject

比较 --wrap-mode、pkg-config/CMake 搜索路径、依赖版本与 introspection 输出。把交付路线固定为 system 或 fallback，并单独测试另一条路线；不要让 auto 来源成为默认治理策略。

交叉构建把生成器编译成目标架构

确认生成器 target 是否 native: true，其依赖是否来自 build machine，cross file 是否提供 exe wrapper。不要把宿主可执行文件复制到目标 sysroot 假装解决。

修改 option 后行为没有变化

用 meson configure builddir 查看最终值，检查命令行、machine file 与默认值优先级。若 option 只在第一次配置时影响子项目，创建新 builddir 验证，避免把缓存状态误判为 Meson 忽略配置。

meson test 通过但安装包不可用

测试可能直接链接 build tree。检查 meson introspect --installed、暂存树和空白消费工程；重点核对 public headers、pkg-config/CMake metadata、动态库搜索路径与传递依赖。

CI 迁移要先并行验证，再切换权威入口

从 Make/CMake 等现有系统迁移时，先冻结一组代表性输入与产物基线：编译器组合、平台、feature、测试、安装树、导出符号和关键性能。随后让 Meson 与旧系统并行构建同一提交，比较行为和产物契约，不要求字节完全相同，但差异必须可解释。

迁移顺序通常从叶子库开始：

用 target 表达源码、头文件与依赖传播。把平台探测移入 Meson 检查，把机器路径移入 machine file。建立 test、install 和空白消费验证。

分别验证 system dependency 与受控 fallback。覆盖干净、增量、并行和交叉构建。CI 稳定后再切换默认入口，保留旧入口一个明确回滚窗口。

回滚单位应包含 Meson 版本、Ninja 版本、machine file、option 集、Wrap 提交与 CI 命令。只回滚 meson.build，却继续使用新 subproject 或新工具链，不能恢复旧构建身份。

Meson 的高速度容易让团队忽略配置状态。热 builddir 连续成功只证明这份状态能继续执行，不能证明新环境可重建。每个受支持平台都要定期从空目录 setup、compile、test、install，并保留 introspection 证据。

Wrap fallback 是供应链执行入口。归档 URL、Git revision、哈希、packagefiles 补丁和子项目构建脚本都会影响最终二进制。普通 PR 不应任意更新来源；离线材料与允许联网更新的任务要分权。

交叉编译最危险的不是“编译器找不到”，而是部分输入来自 build machine、部分输入来自 host sysroot，却仍能成功链接。团队要对编译器、pkg-config、CMake prefix、sysroot 和 executable wrapper 建立一致的机器归属检查。

安装前缀和 rpath 会把构建环境带进交付物。产物扫描应阻断个人绝对路径、构建目录、内部 SDK 地址和不可解释的运行时搜索路径；暂存安装树必须在干净消费环境验证。

源码树与 builddir 分离，工具版本和权威 setup 命令可追踪。target、dependency object 与 option 表达工程关系，不依赖全局路径拼接。Ninja 只执行生成图，生成文件不被手工维护。

system dependency、subproject fallback 与离线策略显式，Wrap 来源和补丁受审查。native/cross file 不含个人路径与凭证，build/host/target 归属可由 introspection 证明。clean、incremental、parallel、test、install 和空白消费验证都有代表性平台证据。

reconfigure、wipe 和新 builddir 的使用边界明确，清理脚本只触碰可再生目录。CI 迁移保留新旧构建对比，升级和回滚覆盖工具、配置、依赖与缓存整组输入。

遇到命令行为或 machine file 字段变化时，优先查 Meson command reference、Built-in options、Machine files 和 Reference manual。链接应服务于正在排查的具体对象，不用搜索摘要替代当前版本的官方说明。