第9章 构建系统 (Build System)

在 C/C++ 世界中，构建系统一直是一个令人头疼的话题。Make, CMake, Autotools, Ninja… 工具繁多且语法各异。

Zig 选择了一条不同的道路：直接使用 Zig 语言本身来编写构建脚本。

这意味着你不需要学习一种新的 DSL（特定领域语言），你可以利用 Zig 强大的逻辑表达能力、类型检查和标准库来管理你的构建过程。构建脚本通常位于项目根目录的 build.zig 文件中。

1. 为什么 Zig 的构建系统很强？

1. 统一性：构建逻辑就是 Zig 代码。你可以使用变量、循环、函数，甚至导入其他模块。
2. 交叉编译：Zig 内置了强大的交叉编译能力，只需一行代码即可为不同的操作系统和架构构建二进制文件。
3. 零依赖：你不需要安装 CMake 或 Python，只需要 zig 编译器本身。
4. C/C++ 支持：它不仅能构建 Zig，还能充当 C/C++ 编译器，甚至可以无缝混合编译 C/C++ 和 Zig。

2. build.zig 剖析

每个 build.zig 文件都必须导出一个公共的 build 函数。当你在命令行运行 zig build 时，编译器会编译并运行这个函数。

const std = @import("std");

pub fn build(b: *std.Build) void {
    // 1. 定义构建目标 (Target)
    const target = b.standardTargetOptions(.{});

    // 2. 定义优化模式 (Optimize Mode)
    const optimize = b.standardOptimizeOption(.{});

    // 3. 定义可执行文件 (Artifact)
    const exe = b.addExecutable(.{
        .name = "hello", // 输出文件名
        .root_source_file = b.path("src/main.zig"), // 入口文件
        .target = target,
        .optimize = optimize,
    });

    // 4. 安装工件
    b.installArtifact(exe);
}

关键概念

• b: *std.Build：构建器对象，提供了一系列创建构建步骤的方法。
• Step (步骤)：构建过程由一系列步骤组成（如编译、链接、运行命令）。这些步骤形成了一个依赖图（DAG）。
• Artifact (工件)：构建的产物，如可执行文件 (.exe)、静态库 (.a) 或动态库 (.so/.dll)。

3. 标准选项

Target (目标平台)

b.standardTargetOptions(.{}) 允许用户通过命令行参数 -Dtarget=... 来指定编译目标。

• 默认：本机架构 (Native)。
• 示例：zig build -Dtarget=x86_64-windows

Optimize (优化模式)

b.standardOptimizeOption(.{}) 允许用户通过 -Doptimize=... 指定优化级别。

• Debug (默认)：启用断言，无优化，编译快。
• ReleaseSafe：开启优化，但保留安全检查（边界检查等）。
• ReleaseFast：开启激进优化，禁用安全检查（追求极致速度）。
• ReleaseSmall：最小化二进制体积。

4. 常用构建任务

添加 “Run” 步骤

除了构建，我们通常还希望直接运行程序。

// ... 定义 exe ...

// 创建一个运行该 exe 的命令
const run_cmd = b.addRunArtifact(exe);

// 允许通过 `zig build run -- arg1 arg2` 传递参数
if (b.args) |args| {
    run_cmd.addArgs(args);
}

// 创建一个名为 "run" 的步骤
const run_step = b.step("run", "Run the app");
run_step.dependOn(&run_cmd.step);

现在你可以运行：

zig build run

添加单元测试步骤

const unit_tests = b.addTest(.{
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
});

const run_unit_tests = b.addRunArtifact(unit_tests);

const test_step = b.step("test", "Run unit tests");
test_step.dependOn(&run_unit_tests.step);

运行测试：

zig build test

5. 依赖管理

Zig 0.11+ 引入了包管理器。你可以通过 build.zig.zon 文件来声明依赖。

假设你要使用一个名为 zap 的 HTTP 库。

步骤 1：在 build.zig.zon 中声明

.{
    .name = "my-project",
    .version = "0.1.0",
    .dependencies = .{
        .zap = .{
            .url = "https://github.com/zigzap/zap/archive/....tar.gz",
            .hash = "...", // 使用 `zig fetch --save <url>` 自动生成
        },
    },
}

步骤 2：在 build.zig 中引用

// 获取依赖
const zap_dep = b.dependency("zap", .{
    .target = target,
    .optimize = optimize,
});

// 获取依赖中的模块
const zap_module = zap_dep.module("zap");

// 将模块添加到你的可执行文件
exe.root_module.addImport("zap", zap_module);

6. 构建 C/C++ 项目

Zig 能够极其轻松地集成 C 代码。

假设你的项目包含 main.zig 和 utils.c。

const exe = b.addExecutable(.{ ... });

// 添加 C 源文件
exe.addCSourceFile(.{
    .file = b.path("src/utils.c"),
    .flags = &.{ "-Wall", "-Wextra" }, // 传递 C 编译器标志
});

// 链接 libc
exe.linkLibC();

你甚至可以使用 exe.addIncludePath(...) 添加头文件搜索路径。

这使得 Zig 成为构建现有 C/C++ 项目的一个极具吸引力的替代方案，也就是所谓的 “Zig cc” 模式。

总结

Zig 的构建系统体现了其“全栈掌控”的野心。它不仅是一个构建脚本，更是一个跨平台的依赖管理器和工具链编排器。

掌握 build.zig，你就能轻松驾驭从简单的 CLI 工具到复杂的跨语言、多平台项目的构建流程。

---

原文出处: https://pedropark99.github.io/zig-book/