本速查表汇总了 Zig 构建系统中最常用、最核心的构建系统 API 及其使用场景。
| API 签名 | 描述与用途 |
|---|
b.standardTargetOptions(.{}) | 解析 -Dtarget 参数，返回目标平台解析结果 |
b.standardOptimizeOption(.{}) | 解析 -Doptimize 参数，返回优化模式（Debug / ReleaseFast 等） |
b.option(T, name, desc) | 声明自定义强类型命令行参数（如 b.option(bool, "enable-tls", ...)） |
b.step(name, desc) | 注册顶层命名构建目标（如 zig build <name>） |
b.path(sub_path) | 基于当前项目根目录创建只读源码 LazyPath |
b.createModule(.{ ... }) | 创建工程内部私有的 *std.Build.Module |
b.addModule(name, .{ ... }) | 创建并注册公共暴露的 *std.Build.Module，供下游依赖通过 dep.module() 消费 |
b.addExecutable(.{ ... }) | 创建可执行文件编译步骤（*Step.Compile） |
b.addLibrary(.{ ... }) | 创建静态库或动态库编译步骤（*Step.Compile） |
b.addTest(.{ ... }) | 创建单元测试二进制编译步骤（*Step.Compile） |
b.installArtifact(artifact) | 将编译产物安装到交付目录（zig-out/bin/ 或 zig-out/lib/） |
b.installDirectory(options) | 将整个目录树（如静态资源 assets）安装到交付目录 |
b.addInstallFile(source, dest) | 将任意生成物 LazyPath 安装到 zig-out 前缀相对路径 |
b.addRunArtifact(artifact) | 创建执行某个编译产物的 *Step.Run 任务 |
b.findProgramLazy(opts) | 推迟外部程序查找到执行期，返回 LazyPath，避免污染配置缓存 |
b.dependOnFileContents(path) | 显式声明配置期依赖该文件的内容哈希，纳入配置缓存凭据 |
b.dependOnDirectoryContents(p) | 显式声明配置期依赖目录条目（新增/删除/重命名） |
b.dependency(name, args) | 实例化 build.zig.zon 中声明的第三方包依赖 |
b.dependencyLazy(name, args) | 惰性按需实例化依赖，未就绪时返回 error.LazyDependencyNeeded 供主进程拉取重试 |
b.addTranslateC(.{ ... }) | 创建 C 头文件转译步骤（*Step.TranslateC） |
b.addConfigHeader(opts, values) | 创建基于 CMake 风格的配置头文件渲染步骤（*Step.ConfigHeader） |
b.addOptions() | 创建强类型的编译期配置常量生成器（*Step.Options） |
b.addWriteFiles() | 创建动态写出代码或配置文件的任务构建器（*Step.WriteFile） |
b.addNamedWriteFiles(name) | 创建并向外部跨包公开导出的命名 WriteFiles 步骤 |
b.addNamedLazyPath(name, lp) | 向外部跨包公开暴露命名的生成路径或文件 |
b.addUpdateSourceFiles() | 创建将生成物安全回写同步至 src/ 源码树（Git 仓库）的专用步骤 |
b.systemIntegrationOption(name, .{}) | 声明发行版系统包集成选项，支持源码 vendored 与系统动态库模式按需切换 |
b.addObjCopy(source, opts) | 从 ELF 产物中提取裸机固件镜像（.bin / .hex）或剥离符号 |
b.addFail(error_msg) | 创建条件构建下的防御性延迟报错步骤（*Step.Fail） |
| 命令 / 参数 | 描述与用途 |
|---|
zig build check | IDE 语法与类型诊断（约定步骤，需在 build.zig 中显式注册） |
zig build docs | 生成 HTML 格式的 API 文档（约定步骤，需在 build.zig 中显式注册） |
zig build --fork=[path] | 通过包名与指纹将依赖重定向至本地源码目录，免改 build.zig.zon |
zig build --watch | 进入会话监听模式，源文件变动时由 Maker 进程自动增量重跑 |
zig build --listen=- | 启动官方 Build Server Protocol (BSP) 服务端，与 IDE 通信 |
zig build --cache-poison=disallowed | 强制要求构建逻辑保持纯函数性，发生环境污染时立刻 panic（用于 CI 门禁检查） |
zig build --fetch=[needed|all] | 控制依赖树拉取的激进程度（默认 needed 按需下载） |
zig build -fsys=[name] | 针对指定依赖包启用系统集成（优先链接系统已安装的库） |
zig build --system | Linux 发行版全局系统包模式：禁用网络拉取并启用所有系统集成 |
zig cache-cat <digest> | 反序列化并打印紧凑二进制 Manifest 记录，诊断缓存未命中原因 |