产物构建与测试验证：Executable、Library、Test 与 ObjCopy

在 Zig 构建系统中，生成最终二进制产物（可执行文件、静态库/动态库、测试程序）的任务由 Step.Compile 负责，并通过 Step.Run、Step.InstallArtifact 以及 Step.ObjCopy 进行执行验证、安装交付与固件提取。

💡 配套可运行示例 关于标准应用程序产物与单元测试构建的完整代码工程，可参考 GitHub 示例：examples/01-zig-app，以及后续实战章节实战一：标准 Zig CLI 应用与单元测试。

1. 构建可执行程序：`b.addExecutable`

const exe = b.addExecutable(.{
    .name = "my_app",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    }),
});

// 将产物安装到 zig-out/bin/ 目录下
b.installArtifact(exe);

// 注册运行命令并支持命令行参数透传
const run_cmd = b.addRunArtifact(exe);
run_cmd.step.dependOn(b.getInstallStep());
run_cmd.addPassthruArgs(); // 记录 .passthru 占位符，执行期由调度器动态注入

const run_step = b.step("run", "Run the application");
run_step.dependOn(&run_cmd.step);

1.1 关键配置：

root_module：挂载主程序的编译上下文与依赖；
产物安装：通过 b.installArtifact(exe) 将生成的可执行文件输出到 zig-out/bin/my_app（在 Windows 平台会自动追加 .exe 后缀）；
参数透传（addPassthruArgs）：通过 addPassthruArgs() 在计算图中注册占位符，由调度器在执行期动态注入命令行参数，避免在配置期读取参数导致配置缓存失效。

1.2 裸机固件与格式转换：`b.addObjCopy`

在嵌入式开发、操作系统内核或微控制器（MCU）固件构建中，编译器输出的标准可执行文件为 ELF 格式，包含头部信息、段符号表与重定位表，无法直接烧录到 Flash 中执行。

通过 lib/std/Build.zig:L1492-L1505 的 addObjCopy 步骤，可以从 ELF 编译产物中直接剥离出纯平铺二进制（.bin）或 Intel 十六进制镜像（.hex）：

// 1. 编译目标为嵌入式无操作系统裸机（如 ARM Cortex-M4）
const kernel_elf = b.addExecutable(.{
    .name = "kernel.elf",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/kernel.zig"),
        .target = b.resolveTargetQuery(.{
            .cpu_arch = .thumb,
            .os_tag = .freestanding,
            .abi = .none,
        }),
        .optimize = .ReleaseSmall,
    }),
});

// 2. 从 ELF 产物中剥离并提取纯二进制 .bin 固件
const bin_step = b.addObjCopy(kernel_elf.getEmittedBin(), .{
    .format = .binary,
});

// 3. 安装裸固件至交付目录：zig-out/firmware.bin
const install_bin = b.addInstallFile(bin_step.getOutput(), "firmware.bin");
b.getInstallStep().dependOn(&install_bin.step);

1.3 链接脚本与符号导出控制：`setLinkerScript` 与 `setVersionScript`

系统级与嵌入式编程中，常需要精确指定内存布局与导出符号：

指定链接脚本（setLinkerScript）：在无操作系统（Freestanding）裸机开发中，通过 lib/std/Build/Step/Compile.zig:L571 指定自定义的 linker.ld，精确规划 Flash、RAM 区域及中断向量表的物理地址：
```
kernel_elf.setLinkerScript(b.path("src/linker.ld"));
```
版本符号控制脚本（setVersionScript）：在构建 Linux 动态共享库时，通过 lib/std/Build/Step/Compile.zig:L577 传入 GNU 链接器版本脚本（Version Script / Symbol Map），精确控制对外公开的导出符号，隐藏内部符号：
```
shared_lib.setVersionScript(b.path("src/exports.map"));
```

2. 构建库文件：`b.addLibrary`

静态库（.a / .lib）与动态库（.so / .dylib / .dll）统一通过 b.addLibrary 声明，通过 .linkage 枚举区分：

// 1. 静态库
const static_lib = b.addLibrary(.{
    .name = "my_lib",
    .linkage = .static,
    .root_module = my_module,
});
b.installArtifact(static_lib);

// 2. 动态共享库
const shared_lib = b.addLibrary(.{
    .name = "my_lib",
    .linkage = .dynamic,
    .version = .{ .major = 1, .minor = 2, .patch = 0 },
    .root_module = my_module,
});
b.installArtifact(shared_lib);

动态库版本控制：

构建动态库时，通过设置 .version（std.SemanticVersion），Zig 会为目标系统生成带有主次版本号的产物与对应的软链接（例如在 Linux 上输出 libmy_lib.so.1.2.0 并创建 libmy_lib.so.1 软链接）。

3. 运行与测试管线：`b.addTest` 与 `b.addRunArtifact`

构建脚本中运行单元测试分为两步：

编译单元测试可执行文件（addTest）；
执行该测试二进制进程（addRunArtifact）。

// 1. 声明测试编译步骤
const unit_tests = b.addTest(.{
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/root.zig"),
        .target = target,
        .optimize = optimize,
    }),
});

// 2. 声明测试运行步骤
const run_unit_tests = b.addRunArtifact(unit_tests);

// 3. 绑定到 "zig build test" 入口
const test_step = b.step("test", "Run all unit tests");
test_step.dependOn(&run_unit_tests.step);

3.1 编译与运行拆分的必要性

支持交叉编译下的测试验证：若指定目标为其他平台架构（如在 macOS 上交叉编译 Linux aarch64 产物），测试程序可以在宿主机缺少仿真环境时，仅执行编译验证；
配置执行环境：run_unit_tests 允许定制工作目录、环境变量，以及断言进程退出码：
```
run_unit_tests.expectExitCode(0);
run_unit_tests.setEnvironmentVariable("LOG_LEVEL", "DEBUG");
```

3.2 命令行工具集成测试断言与流控

除了源码级单元测试（addTest），命令行应用程序更需要端到端黑盒测试（E2E Integration Testing）。Zig 的 Step.Run 提供了丰富的流捕获与断言校验能力：

// 1. 获取已构建的主程序产物
const run_app = b.addRunArtifact(exe);

// 2. 传入测试命令行参数
run_app.addArgs(&.{ "--config", "test.json", "--verbose" });

// 3. 捕获并断言标准输出 (Stdout)
_ = run_app.captureStdOut(.{});
run_app.expectStdOutMatch("Operation completed successfully");

// 4. 断言异常退出状态码（如错误输入应返回退出码 1）
run_app.expectExitCode(1);

// 5. 注入测试隔离环境变量
run_app.setEnvironmentVariable("APP_ENV", "integration-test");

// 6. 绑定到 test 步骤联动调度
test_step.dependOn(&run_app.step);

💡 提示： captureStdOut(.{}) 接收 CapturedStdIo.Options 选项（如最大捕获字节数，默认传 .{} 即可）。进程的标准输出会被捕获并与预期内容比对；若输出不匹配，构建过程会输出 Diff 报错。

3.3 用于 IDE 语法检查的 `check` 步骤

在日常开发与 IDE 编码中，ZLS（Zig Language Server）每次保存文件都需要触发构建系统获取语法和类型检查报错。如果每次都执行全量编译、链接与落盘，会带来显著延迟。

社区与官方标准做法是在 build.zig 中配置轻量级 check 步骤：

// 为 IDE/语言服务器准备的语义检查步骤（不产生任何最终磁盘二进制）
const exe_check = b.addExecutable(.{
    .name = "check",
    .root_module = exe.root_module, // 复用主应用程序的核心编译配置
});

// 注册专用的顶层 check 命令："zig build check"
const check_step = b.step("check", "Check syntax and type safety without linking or installing");
check_step.dependOn(&exe_check.step);

ZLS 默认会调用 zig build check，仅触发编译器前端语义分析（Sema），跳过后端的机器码优化、代码生成与链接，使编辑器保存时的错误提示缩短至毫秒级。

4. 辅助产物与静态资源交付：文档生成与 `installDirectory`

除了二进制可执行文件与库文件，构建输出还常包含 API 参考文档与静态资源（如 Web 前端资源、着色器、配置文件等）。

4.1 自动化 HTML API 文档生成：`compile.getEmittedDocs()`

Zig 编译器能够直接从源码注释（//! 与 ///）中提取并生成单页 HTML API 参考文档。

通过 lib/std/Build/Step/Compile.zig:L723 的 getEmittedDocs() 获取文档输出的 LazyPath，并接入安装步骤：

// 1. 从编译产物中提取 HTML 文档树 (LazyPath)
const docs = exe.getEmittedDocs();

// 2. 声明文档安装步骤：将生成的 HTML 文档输出到交付目录 zig-out/docs/
const install_docs = b.addInstallDirectory(.{
    .source_dir = docs,
    .install_dir = .prefix,
    .install_subdir = "docs",
});

// 3. 注册顶层命令："zig build docs"
const docs_step = b.step("docs", "Generate and install HTML API documentation");
docs_step.dependOn(&install_docs.step);

开发者在终端执行 zig build docs 即可在 zig-out/docs/ 下生成完整的静态文档网站。

4.2 静态资源目录打包交付：`b.installDirectory`

当应用程序需要打包随行资源（例如游戏中的纹理模型、GUI 客户端中的图标着色器、Web 服务的静态前端 HTML/JS 资源）时，使用 lib/std/Build.zig:L1478 的 installDirectory 将整个物理目录复制到交付目录：

b.installDirectory(.{
    .source_dir = b.path("assets"),
    .install_dir = .prefix,
    .install_subdir = "share/my_app/assets",
});

构建执行后，assets/ 目录下的所有文件会完整保留层级结构投影至 zig-out/share/my_app/assets/ 中。

5. 跨平台测试执行器配置与产物清理局限

5.1 跨平台测试执行与仿真器配置

在开发机上交叉编译目标架构（如在 x86_64 上测试 ARM64 或 RISC-V 产物）时，执行期需要仿真器支持：

命令行自动调度仿真器：Zig 原生集成了外部执行器探测（如 Linux 的 binfmt_misc 或 macOS 的 Rosetta）。用户也可在命令行直接传入 -fqemu 或 -fwasmtime，让构建系统自动挂载仿真环境；
配置跨平台执行容错：在构建脚本中，可以通过 failing_to_execute_foreign_is_an_error 声明策略。缺少目标架构仿真器时可跳过运行，避免中断构建流程：
```
// 遇到非宿主架构（Foreign Binary）时，若无可用仿真器则跳过而不是直接失败
run_unit_tests.failing_to_execute_foreign_is_an_error = false;
```
仅编译测试产物：在缺少运行环境或仿真器的 CI 机器上，可以仅调度 &unit_tests.step（只编译测试二进制），提前发现目标平台的语法和类型错误。

5.2 局限与不足

缺少内置的 clean 目标： Zig 官方未提供 zig build clean 命令。当需要释放磁盘空间或清理缓存时，开发者需要通过外部命令手动删除 .zig-cache 和 zig-out；
交付目录缺少失效产物清理：若在 build.zig 中重命名或删除了某个产物，重新构建时旧的二进制文件仍会留在 zig-out/bin/ 目录中，系统不会自动清理当前构建图未声明的残留文件。

Keyboard shortcuts

Zig 构建系统指南