Back to Details

zig-build-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zig Build System

Zig构建系统

Purpose

用途

Guide agents through writing 
build.zig
files: executables, libraries, C source integration, build options, test configuration, and 
build.zig.zon
package manifests.
指导开发者编写
build.zig
文件：包括可执行文件、库、C源文件集成、构建选项、测试配置以及
build.zig.zon
包清单的相关内容。

Triggers

触发场景

  • "How do I set up a build.zig file?"
  • "How do I add a C library to a Zig project?"
  • "How do I define build-time options in Zig?"
  • "How do I run Zig tests with zig build test?"
  • "What is build.zig.zon and how do I use it?"
  • "How do I add a Zig package dependency?"
  • "如何设置build.zig文件？"
  • "如何在Zig项目中添加C库？"
  • "如何在Zig中定义构建时选项？"
  • "如何使用zig build test运行Zig测试？"
  • "什么是build.zig.zon，如何使用它？"
  • "如何添加Zig包依赖？"

Workflow

工作流程

1. Project initialization

1. 项目初始化

bash
undefined
bash
undefined

Initialize a new project

初始化新项目

mkdir myproject && cd myproject zig init # creates src/main.zig and build.zig
mkdir myproject && cd myproject zig init # 创建src/main.zig和build.zig文件

Build

构建项目

zig build
zig build

Run

运行项目

zig build run
zig build run

Test

运行测试

zig build test
undefined
zig build test
undefined

2. build.zig structure

2. build.zig结构

zig
const std = @import("std");

pub fn build(b: *std.Build) void {
    // Standard options (--optimize, --target)
    const optimize = b.standardOptimizeOption(.{});
    const target = b.standardTargetOptions(.{});

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

    // Install step (zig build → copies to zig-out/bin/)
    b.installArtifact(exe);

    // Run step (zig build run)
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }
    const run_step = b.step("run", "Run the app");
    run_step.dependOn(&run_cmd.step);

    // Test step (zig build test)
    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
const std = @import("std");

pub fn build(b: *std.Build) void {
    // 标准选项（--optimize、--target）
    const optimize = b.standardOptimizeOption(.{});
    const target = b.standardTargetOptions(.{});

    // 可执行文件
    const exe = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    // 安装步骤（zig build → 复制到zig-out/bin/）
    b.installArtifact(exe);

    // 运行步骤（zig build run）
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }
    const run_step = b.step("run", "Run the app");
    run_step.dependOn(&run_cmd.step);

    // 测试步骤（zig build test）
    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);
}

3. Libraries

3. 库

zig
// Static library
const lib = b.addStaticLibrary(.{
    .name = "mylib",
    .root_source_file = b.path("src/mylib.zig"),
    .target = target,
    .optimize = optimize,
});
b.installArtifact(lib);

// Shared library
const shared_lib = b.addSharedLibrary(.{
    .name = "mylib",
    .root_source_file = b.path("src/mylib.zig"),
    .target = target,
    .optimize = optimize,
    .version = .{ .major = 1, .minor = 0, .patch = 0 },
});
b.installArtifact(shared_lib);

// Link library into executable
exe.linkLibrary(lib);
zig
// 静态库
const lib = b.addStaticLibrary(.{
    .name = "mylib",
    .root_source_file = b.path("src/mylib.zig"),
    .target = target,
    .optimize = optimize,
});
b.installArtifact(lib);

// 共享库
const shared_lib = b.addSharedLibrary(.{
    .name = "mylib",
    .root_source_file = b.path("src/mylib.zig"),
    .target = target,
    .optimize = optimize,
    .version = .{ .major = 1, .minor = 0, .patch = 0 },
});
b.installArtifact(shared_lib);

// 将库链接到可执行文件
exe.linkLibrary(lib);

4. Adding C source files

4. 添加C源文件

zig
// Single C file
exe.addCSourceFile(.{
    .file = b.path("src/legacy.c"),
    .flags = &.{ "-std=c11", "-Wall", "-Wextra" },
});

// Multiple C files
exe.addCSourceFiles(.{
    .files = &.{
        "src/a.c",
        "src/b.c",
        "src/c.c",
    },
    .flags = &.{ "-std=c11", "-O2" },
});

// Include directories
exe.addIncludePath(b.path("include/"));
exe.addIncludePath(.{ .cwd_relative = "/usr/local/include" });

// System libraries
exe.linkSystemLibrary("curl");
exe.linkSystemLibrary("ssl");
exe.linkLibC();  // link libc (required if calling C stdlib)
zig
// 单个C文件
exe.addCSourceFile(.{
    .file = b.path("src/legacy.c"),
    .flags = &.{ "-std=c11", "-Wall", "-Wextra" },
});

// 多个C文件
exe.addCSourceFiles(.{
    .files = &.{
        "src/a.c",
        "src/b.c",
        "src/c.c",
    },
    .flags = &.{ "-std=c11", "-O2" },
});

// 包含目录
exe.addIncludePath(b.path("include/"));
exe.addIncludePath(.{ .cwd_relative = "/usr/local/include" });

// 系统库
exe.linkSystemLibrary("curl");
exe.linkSystemLibrary("ssl");
exe.linkLibC();  // 链接libc（如果调用C标准库则需要）

5. Build-time options

5. 构建时选项

zig
pub fn build(b: *std.Build) void {
    // Boolean option
    const enable_logging = b.option(
        bool,
        "logging",
        "Enable debug logging",
    ) orelse false;

    // Enum option
    const Backend = enum { opengl, vulkan, software };
    const backend = b.option(
        Backend,
        "backend",
        "Rendering backend",
    ) orelse .opengl;

    // Integer option
    const max_connections = b.option(
        u32,
        "max-connections",
        "Maximum concurrent connections",
    ) orelse 64;

    // Pass to Zig code as compile-time constant
    const options = b.addOptions();
    options.addOption(bool, "enable_logging", enable_logging);
    options.addOption(Backend, "backend", backend);
    options.addOption(u32, "max_connections", max_connections);

    exe.root_module.addOptions("build_options", options);
}
In Zig source:
zig
const build_options = @import("build_options");

pub fn main() void {
    if (build_options.enable_logging) {
        std.debug.print("Logging enabled\n", .{});
    }
}
bash
undefined
zig
pub fn build(b: *std.Build) void {
    // 布尔选项
    const enable_logging = b.option(
        bool,
        "logging",
        "Enable debug logging",
    ) orelse false;

    // 枚举选项
    const Backend = enum { opengl, vulkan, software };
    const backend = b.option(
        Backend,
        "backend",
        "Rendering backend",
    ) orelse .opengl;

    // 整数选项
    const max_connections = b.option(
        u32,
        "max-connections",
        "Maximum concurrent connections",
    ) orelse 64;

    // 作为编译时常量传递给Zig代码
    const options = b.addOptions();
    options.addOption(bool, "enable_logging", enable_logging);
    options.addOption(Backend, "backend", backend);
    options.addOption(u32, "max_connections", max_connections);

    exe.root_module.addOptions("build_options", options);
}
在Zig源码中：
zig
const build_options = @import("build_options");

pub fn main() void {
    if (build_options.enable_logging) {
        std.debug.print("Logging enabled\n", .{});
    }
}
bash
undefined

Pass options on command line

在命令行传递选项

zig build -Dlogging=true -Dbackend=vulkan -Dmax-connections=256
undefined
zig build -Dlogging=true -Dbackend=vulkan -Dmax-connections=256
undefined

6. Module system

6. 模块系统

zig
// Create a module (reusable across targets)
const mymodule = b.addModule("mymodule", .{
    .root_source_file = b.path("src/mymodule.zig"),
});

// Use module in executable
exe.root_module.addImport("mymodule", mymodule);

// Share module between exe and tests
const utils = b.addModule("utils", .{
    .root_source_file = b.path("src/utils.zig"),
});
exe.root_module.addImport("utils", utils);
unit_tests.root_module.addImport("utils", utils);
In Zig source:
zig
const utils = @import("utils");
const mymodule = @import("mymodule");
zig
// 创建模块（可跨目标复用）
const mymodule = b.addModule("mymodule", .{
    .root_source_file = b.path("src/mymodule.zig"),
});

// 在可执行文件中使用模块
exe.root_module.addImport("mymodule", mymodule);

// 在可执行文件和测试之间共享模块
const utils = b.addModule("utils", .{
    .root_source_file = b.path("src/utils.zig"),
});
exe.root_module.addImport("utils", utils);
unit_tests.root_module.addImport("utils", utils);
在Zig源码中：
zig
const utils = @import("utils");
const mymodule = @import("mymodule");

7. Package management with build.zig.zon

7. 使用build.zig.zon进行包管理

zig
// build.zig.zon
.{
    .name = "myapp",
    .version = "0.1.0",
    .minimum_zig_version = "0.13.0",

    .dependencies = .{
        .zig_clap = .{
            .url = "https://github.com/Hejsil/zig-clap/archive/refs/tags/0.9.1.tar.gz",
            .hash = "1220...",  // Run zig build to get the hash
        },
        .known_folders = .{
            .url = "https://github.com/ziglibs/known-folders/archive/refs/heads/master.tar.gz",
            .hash = "1220...",
        },
    },

    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "LICENSE",
        "README.md",
    },
}
zig
// build.zig — use the dependency
const clap_dep = b.dependency("zig_clap", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("clap", clap_dep.module("clap"));
bash
undefined
zig
// build.zig.zon
.{
    .name = "myapp",
    .version = "0.1.0",
    .minimum_zig_version = "0.13.0",

    .dependencies = .{
        .zig_clap = .{
            .url = "https://github.com/Hejsil/zig-clap/archive/refs/tags/0.9.1.tar.gz",
            .hash = "1220...",  // 运行zig build获取哈希值
        },
        .known_folders = .{
            .url = "https://github.com/ziglibs/known-folders/archive/refs/heads/master.tar.gz",
            .hash = "1220...",
        },
    },

    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "LICENSE",
        "README.md",
    },
}
zig
// build.zig — 使用依赖
const clap_dep = b.dependency("zig_clap", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("clap", clap_dep.module("clap"));
bash
// 获取依赖（创建zig-cache/packages/目录）
zig build    // 首次运行时自动获取

// 如果缺少哈希值，Zig会打印出来 — 将其复制到build.zig.zon中

Fetch dependencies (creates zig-cache/packages/)

8. 自定义构建步骤

zig build # auto-fetches on first run
zig
// 代码生成步骤
const gen_step = b.addSystemCommand(&.{
    "python3", "scripts/gen.py", "--output", "src/generated.zig",
});
exe.step.dependOn(&gen_step.step);

// 自定义安装步骤
const install_config = b.addInstallFile(
    b.path("config/default.toml"),
    "share/myapp/config.toml",
);
b.getInstallStep().dependOn(&install_config.step);
有关高级build.zig模式，请参阅references/build-zig-patterns.md。

Zig will print the hash if missing — copy it into build.zig.zon

相关技能

undefined
  • 单文件构建和编译器标志相关内容，请使用
    skills/zig/zig-compiler
  • build.zig中的C库集成相关内容，请使用
    skills/zig/zig-cinterop
  • build.zig中的交叉编译相关内容，请使用
    skills/zig/zig-cross
  • 将Zig嵌入CMake项目时，请使用
    skills/build-systems/cmake

8. Custom build steps

—
zig
// Code generation step
const gen_step = b.addSystemCommand(&.{
    "python3", "scripts/gen.py", "--output", "src/generated.zig",
});
exe.step.dependOn(&gen_step.step);

// Custom install step
const install_config = b.addInstallFile(
    b.path("config/default.toml"),
    "share/myapp/config.toml",
);
b.getInstallStep().dependOn(&install_config.step);
For advanced build.zig patterns, see references/build-zig-patterns.md.
—

Related skills

—
  • Use 
    skills/zig/zig-compiler
    for single-file builds and compiler flags
  • Use 
    skills/zig/zig-cinterop
    for C library integration in build.zig
  • Use 
    skills/zig/zig-cross
    for cross-compilation in build.zig
  • Use 
    skills/build-systems/cmake
    when embedding Zig into a CMake project
—