zig-build-system

用途

该技能指导代理编写 build.zig 文件，适用于多文件 Zig 项目的构建配置，涵盖可执行文件、库、C 源码集成、构建选项、测试配置以及 build.zig.zon 包清单。

主要能力与触发场景

• 设置 build.zig 文件
• 向 Zig 项目添加 C 库
• 在 Zig 中定义构建期选项
• 使用 zig build test 运行 Zig 测试
• 了解与使用 build.zig.zon
• 添加 Zig 包依赖

使用方式

1. 项目初始化

mkdir myproject && cd myproject zig init # creates src/main.zig and build.zig zig build zig build run zig build test

1. build.zig 结构

使用 std.Build，通过 standardOptimizeOption 和 standardTargetOptions 获取标准选项；用 addExecutable 定义可执行文件，installArtifact 安装，addRunArtifact 定义 run 步骤，addTest 与 addRunArtifact 定义 test 步骤。

1. 库

静态库用 addStaticLibrary，共享库用 addSharedLibrary（可带 version），通过 linkLibrary 将库链接进可执行文件。

1. 添加 C 源码

单文件用 addCSourceFile，多文件用 addCSourceFiles；include.

目录用 addIncludePath；系统库用 linkSystemLibrary；需要 C 标准库时用 linkLibC。

1. 构建期选项

用 b.option 定义布尔、枚举、整数选项，并通过 b.addOptions 与 root_module.addOptions 传给 Zig 代码，在源码中用 @import("build_options") 使用。命令行示例：zig build -Dlogging=true -Dbackend=vulkan -Dmax-connections=256

1. 模块系统

用 b.addModule 创建模块，通过 root_module.addImport 在可执行文件与测试之间共享模块。

1. 包管理 build.zig.zon

定义 .name、.version、.minimum_zig_version、.dependencies（含 url 与 hash）以及 .paths。首次运行 zig build 会自动获取依赖并生成 zig-cache/packages/；缺少 hash 时 Zig 会打印出来，可复制进 build.zig.zon。在 build.zig 中用 b.dependency 引用依赖并通过 module 导入。

1. 自定义构建步骤

用 addSystemCommand 定义代码生成等步骤，用 addInstallFile 定义自定义安装文件，并通过 step.dependOn 建立依赖关系。

适用场景与限制

适用于多文件 Zig 项目的构建配置编写与调试，包括库、C 互操作、测试、模块、依赖与自定义构建步骤。更高级的 build.zig 模式参见 references/build-zig-patterns.md。相关技能：单文件构建与编译器标志见 zig-compiler；C 库集成见 zig-cinterop；交叉编译见 zig-cross；将 Zig 嵌入 CMake 项目见 cmake。关于该技能的具体收费、价格或额外平台信息，资料中暂未提供。