zstd 的 Meson 构建系统完全指南：以 mold 仓库 third-party/zstd 为例详解配置、编译与产物

本篇指南以当前仓库 third-party/zstd/build/meson/README.md 为骨架，系统讲解 zstandard（zstd）压缩库的 Meson 构建方式：包括从零开始的构建命令、meson_options.txt 中全部可配置项的含义与默认值、meson.build 中库/工具/测试/contrib 四条构建管线的组织方式，以及该 Meson 构建系统与 mold 链接器实际使用 zstd 的关联（如 --compress-debug-sections=zstd 的压缩实现）。读完本文，你将能够独立用 Meson 构建并定制 zstd，也能理解 mold 仓库中 vendored zstd 的完整源码布局。

一、这份文档讲什么：为 zstandard 提供的官方 Meson 构建

Meson 是一个以“开箱即用地支持现代软件开发实践（单元测试、覆盖率报告、Valgrind、CCache 等）”为设计目标的构建系统。zstandard 的源码树中除了传统的 Makefile 和 CMake 构建之外，还附带了一套由 Dima Krasner 维护、以“不提供任何担保（provided with no guarantee）”方式发布的 Meson 构建系统，其入口就是 third-party/zstd/build/meson/README.md。

按文档原文，这套构建系统的核心产出是一个 libzstd 库，其形态（共享库还是静态库）由 Meson 的内置选项 default_library 决定。需要说明的是，“一个 libzstd”描述的是库这一主产物，实际上这套构建同时还会按选项产出命令行程序、测试程序与 contrib 工具（详见后文）。

在 mold 仓库中，zstd 作为第三方依赖以完整源码形式随仓库分发（third-party/zstd），mold 自身在 CMakeLists.txt 中优先查找系统 zstd.h，找不到时编译 third-party/zstd/build/cmake 子目录。因此本 Meson 目录是同一份 zstd 源码的另一种独立构建路径，适合希望在 mold 之外单独构建、安装或打包 libzstd 的场景（如发行版打包、CI 缓存等）。

二、从零构建：meson setup / ninja / ninja install

文档给出的构建流程非常直接：先 cd 到 Meson 目录，再依次执行配置、构建与安装：

cd third-party/zstd/build/meson

# 1. 配置构建目录（生成 builddir）
meson setup -Dbin_programs=true -Dbin_contrib=true builddir

# 2. 进入构建目录并编译
cd builddir
ninja             # 构建
ninja install     # 安装

各步骤说明：

• meson setup -Dbin_programs=true -Dbin_contrib=true builddir：初始化名为 builddir 的构建目录，并通过 -D 显式开启命令行程序（bin_programs）与 contrib 组件（bin_contrib）。这两个选项的默认值分别是 true 与 false（见 meson_options.txt），即默认就会构建 zstd 可执行程序，但 contrib（如 pzstd）需要显式开启。
• ninja：实际编译。Meson 默认使用 Ninja 作为后端。
• ninja install：把库、头文件、程序与 man page 安装到 prefix（默认 /usr/local，由 meson setup --prefix 控制）。

若不想污染系统目录，文档推荐使用 staging 目录（暂存安装） 技巧：

DESTDIR=./staging ninja install

DESTDIR 会把安装根目录重定向到 ./staging，所有文件被安装到 ./staging/usr/local/...（依 prefix 而定），常用于打包前收集文件清单。

构建完成后如需调整选项，无需重新 setup，直接用：

meson configure        # 在 builddir 内查看/修改选项

更常见的完整形式是 meson configure builddir（查看）与 meson configure builddir -D选项=值（修改后重新 ninja 生效）。Meson 的完整命令行语义可参阅系统 man meson 手册页。

三、可配置项全景：meson_options.txt 逐项解读

这套构建系统的全部自定义选项集中在 third-party/zstd/build/meson/meson_options.txt，与 Meson 内置选项（prefix、buildtype、default_library、debug 等）共同构成完整的配置面。下表汇总了全部自定义选项的类型、默认值与含义：

选项	类型	默认值	说明
legacy_level	integer（0–7）	5	旧格式兼容级别：7 到 1 分别对应支持 v0.7+ 到 v0.1+ 的旧版 zstd 格式；0 表示完全禁用 legacy 支持
debug_level	integer（0–9）	1	运行时调试级别，对应 lib/common/debug.h 中的 DEBUGLEVEL 宏
backtrace	feature	disabled	运行时异常时是否打印栈回溯（backtrace）
static_runtime	boolean	false	在 MSVC 下链接静态运行时库（对应 /MT）
bin_programs	boolean	true	是否构建命令行程序（zstd、zstd-frugal 等）
bin_tests	boolean	false	是否构建测试程序并注册到 meson test
bin_contrib	boolean	false	是否构建 contrib 组件（pzstd 等）
multi_thread	feature	enabled	检测到 pthread 或 Windows 时启用多线程
zlib	feature	auto	是否启用 zlib 支持（使 zstd CLI 可读写 gzip 格式）
lzma	feature	auto	是否启用 lzma 支持（使 zstd CLI 可读写 xz/lzma 格式）
lz4	feature	auto	是否启用 lz4 支持（使 zstd CLI 可读写 lz4 格式）

其中 legacy_level 直接映射为编译宏 -DZSTD_LEGACY_SUPPORT=<n>，并决定是否把 third-party/zstd/lib/legacy 下的 zstd_v01.c～zstd_v07.c 编入库中；multi_thread 映射为 -DZSTD_MULTITHREAD；zlib/lzma/lz4 三个 feature 选项按 Meson 惯例可取 enabled / disabled / auto，为 auto 时若系统检测到对应依赖库（dependency('zlib')、dependency('liblzma')、dependency('liblz4')）则自动启用。

四、顶层 meson.build：项目元数据与子目录调度

顶层构建脚本 third-party/zstd/build/meson/meson.build 承担了项目声明、依赖探测、编译标志设定和子目录调度四件事：

1. 项目声明。 project('zstd', ['c','cpp'], license: ['BSD','GPLv2'], ...) 声明 zstd 同时使用 C 与 C++（C++ 用于 pzstd），许可为 BSD/GPLv2 双许可，并要求 meson_version: '>=0.50.0'。默认选项设置了 cpp_std=c++11、buildtype=release、warning_level=3。

2. 版本号自动提取。 项目版本并非硬编码，而是通过运行脚本 third-party/zstd/build/meson/GetZstdLibraryVersion.py 从 lib/zstd.h 中解析 ZSTD_VERSION_* 宏得到：

version: run_command(
  find_program('GetZstdLibraryVersion.py'), '../../lib/zstd.h',
  check: true).stdout().strip(),

这意味着库版本（libzstd 的 soname 版本）始终与源码中的版本宏保持一致，避免手工同步。

3. 依赖探测。 依次探测 libm（cc.find_library('m', required: false)）、线程（dependency('threads')，Windows 下跳过）、zlib、liblzma、liblz4。探测结果保存在 use_zlib / use_lzma / use_lz4 等变量中，供 programs 子目录使用。

4. 编译标志。 对所有 C 目标统一注入 -DXXH_NAMESPACE=ZSTD_（把内置 xxHash 符号重命名到 ZSTD_ 前缀，避免符号冲突）；对 GCC/Clang 追加 -Wundef、-Wshadow、-Wcast-align、-Wcast-qual 及 -Wa,--noexecstack / -Wl,-z,noexecstack；对 MSVC 则注入 /D_UNICODE、/DUNICODE，多线程开启时加 /MP，static_runtime 开启时加 /MT。

5. 子目录调度是整棵构建树的“总开关”：

subdir('lib')                       # 永远构建 libzstd

if bin_programs or bin_tests        # 需要程序时才进入
  subdir('programs')
endif

if bin_tests                        # 只有 bin_tests=true 才构建测试
  subdir('tests')
endif

if bin_contrib                      # 只有 bin_contrib=true 才构建 contrib
  subdir('contrib')
endif

可以看出 lib 是必选项，其余三棵子树均可按需裁剪。

五、libzstd 库的组装：源码清单、汇编、legacy 与静态/共享处理

库的构建细节集中在 third-party/zstd/build/meson/lib/meson.build，其要点如下：

源码清单按模块组织。 libzstd_sources 明确列出了来自 lib/common（entropy_common、fse_decompress、threading、pool、zstd_common、error_private、xxhash）、lib/compress（hist、fse_compress、huf_compress、zstd_compress 及 fast/double_fast/lazy/opt/ldm 等策略文件、zstdmt_compress、zstd_preSplit）、lib/decompress（huf_decompress、zstd_decompress、zstd_decompress_block、zstd_ddict）与 lib/dictBuilder（cover、fastcover、divsufsort、zdict）的 30 余个 C 源文件，与 third-party/zstd/lib 的目录布局一一对应。

汇编与降级路径。 只有当编译器是 GCC 或 Clang（即具备 __GNUC__ 定义、满足 ZSTD_ASM_SUPPORTED 门控条件）时，才把 lib/decompress/huf_decompress_amd64.S 加入编译；否则注入 -DZSTD_DISABLE_ASM 显式关闭汇编加速。

legacy 支持按需叠加。 根据 legacy_level 注入 -DZSTD_LEGACY_SUPPORT=<n>；n=0 时打印 "Legacy support: DISABLED"，否则按 1～7 循环把 legacy_level <= i 对应的 zstd_v0i.c 追加进源码列表，并补充 lib/legacy 头文件路径。

多线程与调试。 multi_thread 启用时注入 -DZSTD_MULTITHREAD 并把线程依赖链入库；--debug 构建时注入 -DDEBUGLEVEL=<debug_level>，并追加一组严格告警标志（-Wswitch-enum、-Wdeclaration-after-statement、-Wformat=2 等）。

静态库与共享库的“双链接”策略。 库以 gnu_symbol_visibility: 'hidden' 编译（隐藏内部符号），同时内部又大量使用私有符号，因此 lib/meson.build 采用“共享库（暴露公共符号）+ 静态库（保留私有符号）一起链接”的手法：default_library=static 时直接复用；shared 时用 libzstd.extract_all_objects(recursive: true) 把共享库对象抽出制成 zstd_objlib 静态库；both 时取 get_static_lib()。MSVC 由于不支持同时链接同名符号（LNK2005），走单独分支。

安装内容。 生成库的同时注册 pkg-config 元数据（pkgconfig.generate(libzstd, name: 'libzstd', ...)），并安装公共头文件 lib/zstd.h、lib/zdict.h、lib/zstd_errors.h（私有头文件不暴露）。

六、命令行工具与安装脚本：zstd、zstd-frugal、符号链接与 man page

third-party/zstd/build/meson/programs/meson.build 负责所有面向用户的产物：

• zstd 主程序：由 programs/zstdcli.c、fileio.c、benchzstd.c、datagen.c、dibio.c 等 11 个源文件构成，build_by_default: bin_programs、install: bin_programs，即是否构建和安装完全跟随 bin_programs 选项。
• zstd-frugal 精简版：只保留压缩/解压与文件 IO（zstdcli.c + timefn.c + util.c + fileio.c + fileio_asyncio.c），通过 -DZSTD_NOBENCH -DZSTD_NODICT -DZSTD_NOTRACE 去掉基准测试、字典与 trace 功能，作为最小体积的 CLI 安装。
• 格式桥接：use_zlib/use_lzma/use_lz4 分别注入 -DZSTD_GZCOMPRESS -DZSTD_GZDECOMPRESS、-DZSTD_LZMACOMPRESS -DZSTD_LZMADECOMPRESS、-DZSTD_LZ4COMPRESS -DZSTD_LZ4DECOMPRESS，让 zstd 能透明读写 gzip/xz/lz4 文件；use_backtrace 则通过探测 execinfo.h 决定是否注入 -DBACKTRACE_ENABLE=1（Windows 下还需 export_dynamic）。
• 辅助脚本与文档：安装 zstdgrep、zstdless 脚本（install_data）与 zstd.1、zstdgrep.1、zstdless.1 手册页（install_man）。
• 符号链接：借助 third-party/zstd/build/meson/InstallSymlink.py 在安装阶段创建 zstdcat→zstd、unzstd→zstd（多线程开启时还有 zstdmt→zstd）的可执行与 man page 软链接，兼容 Unix 传统命令命名习惯。

七、测试体系：bin_tests 开启后的完整回归面

当 meson setup -Dbin_tests=true 时，third-party/zstd/build/meson/tests/meson.build 会构建一批测试可执行文件并注册到 Meson 测试框架（可用 meson test --list 查看全部用例）：

测试程序	对应源码（tests 目录）	作用
datagen	datagencli.c + loremOut.c	生成随机/可复现测试数据
fullbench	fullbench.c	各压缩参数下的完整基准
fuzzer	fuzzer.c	模糊测试（默认 --no-big-tests，限时 200s）
zstreamtest	zstreamtest.c + seqgen.c	流式 API 测试（含 --newapi 变体）
paramgrill	paramgrill.c	压缩参数搜索调优
roundTripCrash / longmatch / invalidDictionaries	同名源文件	崩溃/长匹配/非法字典专项测试
decodecorpus	decodecorpus.c	解码语料生成与校验
poolTests / checkTag / legacy	同名源文件	线程池、版本标签、legacy 格式（仅 0<legacy_level<=4 时）

此外还包含两层系统级测试：

• 检测到 valgrind 时，通过 third-party/zstd/build/meson/tests/valgrindTest.py 对 zstd、datagen、fuzzer、fullbench 做内存检查（600 秒超时）；
• 运行 tests/playTests.sh 端到端脚本测试。Meson ≥ 0.57 时将其拆分为 fast 与 slow（--test-large-data）两个 suite，并利用 add_test_setup('fast', is_default: true, exclude_suites: ['slow']) 让默认 meson test 只跑快速用例，meson test --setup slow 才跑大数据用例，超时上限放宽到 2800 秒以适配 HDD。

八、contrib 子树：pzstd 与 gen_html

bin_contrib=true 时进入 third-party/zstd/build/meson/contrib/meson.build，其下包含：

• pzstd（contrib/pzstd/meson.build）：基于 C++11 与线程库的并行 zstd 工具，由 contrib/pzstd/main.cpp、Options.cpp、Pzstd.cpp、SkippableFrame.cpp 组成，通过 override_options: ['b_ndebug=true'] 强制关闭断言以获得更优性能；
• gen_html：从源码生成 HTML 文档的辅助工具。

由于这两个组件默认不构建（bin_contrib 默认 false），meson setup -Dbin_programs=true -Dbin_contrib=true builddir 中显式开启 bin_contrib 正是文档默认命令的用意所在。

九、与 mold 项目的实际关联：zstd 在链接器中的用途

本 Meson 构建系统服务于 mold 仓库内 vendored 的 zstd 源码，而 mold 对 zstd 的真实消费点集中在“压缩/解压 ELF 调试信息”这一功能上，可作为理解该第三方依赖价值的注脚：

• mold 的 CMakeLists.txt 优先探测系统 zstd.h（check_include_file(zstd.h HAVE_ZSTD_H)），未找到时编译内置 third-party/zstd/build/cmake 并链接 libzstd_static——这是与 Meson 构建同一份源码的另一条集成路径。
• 命令行 --compress-debug-sections=zstd 会把 ctx.arg.compress_debug_sections 设为 ELFCOMPRESS_ZSTD（见 src/cmdline.cc 与 src/elf.h）。
• 压缩侧：mold 在 lib/compress.cc 中实现 ZstdCompressor——先把调试信息按 1 MiB 分片，再用 TBB parallel_for 对每片调用 ZSTD_compress 并行压缩，最后拼接输出（文件头注释明确说明 zstd 压缩数据可像 zlib 一样靠分片拼接合并）。可见 zstd 正是以库 API 形式被消费，而非子进程调用。
• 解压侧：读入已压缩的 .zdebug_* 段时，src/input-sections.cc 使用 ZSTD_createDCtx / ZSTD_decompressStream 流式解压，出错时通过 ZSTD_getErrorName 给出错误信息。

因此，无论是想为 mold 补充一个可独立安装的 zstd 构建，还是想深入定制 --compress-debug-sections=zstd 所依赖的库本身，这套 Meson 构建系统都是与 CMake 构建并列、可直接落地的方案。其完整选项面（legacy_level、multi_thread、zlib/lzma/lz4 桥接等）可让打包者在不改动任何 zstd 源码的前提下，产出恰好符合发行版需求的 libzstd 与 zstd 工具集。