Zig Build System

The Zig Build System provides a cross-platform, dependency-free way to declare the logic required to build a project. With this system, the logic to build a project is written in a build.zig file, using the Zig Build System API to declare and configure build artifacts and other tasks.

Some examples of tasks the build system can help with:

• Creating build artifacts by executing the Zig compiler. This includes building Zig source code as well as C and C++ source code.
• Capturing user-configured options and using those options to configure the build.
• Surfacing build configuration as comptime values by providing a file that can be imported by Zig code.
• Caching build artifacts to avoid unnecessarily repeating steps.
• Executing build artifacts or system-installed tools.
• Running tests and verifying the output of executing a build artifact matches the expected value.
• Running zig fmt on a codebase or a subset of it.
• Custom tasks.

To use the build system, run zig build —help to see a command-line usage help menu. This will include project-specific options that were declared in the build.zig script.

Building an Executable

This build.zig file is automatically generated by zig init-exe.

build_executable.zig

const std = @import("std");
pub fn build(b: *std.Build) void {
    // Standard target options allows the person running `zig build` to choose
    // what target to build for. Here we do not override the defaults, which
    // means any target is allowed, and the default is native. Other options
    // for restricting supported target set are available.
    const target = b.standardTargetOptions(.{});
    // Standard optimization options allow the person running `zig build` to select
    // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not
    // set a preferred release mode, allowing the user to decide how to optimize.
    const optimize = b.standardOptimizeOption(.{});
    const exe = b.addExecutable(.{
        .name = "example",
        .root_source_file = .{ .path = "src/main.zig" },
        .target = target,
        .optimize = optimize,
    });
    exe.install();
    const run_cmd = exe.run();
    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);
}

Building a Library

This build.zig file is automatically generated by zig init-lib.

build_library.zig

const std = @import("std");
pub fn build(b: *std.Build) void {
    const optimize = b.standardOptimizeOption(.{});
    const lib = b.addStaticLibrary(.{
        .name = "example",
        .root_source_file = .{ .path = "src/main.zig" },
        .optimize = optimize,
    });
    lib.install();
    const main_tests = b.addTest(.{
        .root_source_file = .{ .path = "src/main.zig" },
        .optimize = optimize,
    });
    const test_step = b.step("test", "Run library tests");
    test_step.dependOn(&main_tests.step);
}

Compiling C Source Code

lib.addCSourceFile("src/lib.c", &[_][]const u8{
    "-Wall",
    "-Wextra",
    "-Werror",
});