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.zig

  1. const Builder = @import("std").build.Builder;
  2. pub fn build(b: *Builder) void {
  3. // Standard target options allows the person running `zig build` to choose
  4. // what target to build for. Here we do not override the defaults, which
  5. // means any target is allowed, and the default is native. Other options
  6. // for restricting supported target set are available.
  7. const target = b.standardTargetOptions(.{});
  8. // Standard release options allow the person running `zig build` to select
  9. // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.
  10. const mode = b.standardReleaseOptions();
  11. const exe = b.addExecutable("example", "src/main.zig");
  12. exe.setTarget(target);
  13. exe.setBuildMode(mode);
  14. exe.install();
  15. const run_cmd = exe.run();
  16. run_cmd.step.dependOn(b.getInstallStep());
  17. if (b.args) |args| {
  18. run_cmd.addArgs(args);
  19. }
  20. const run_step = b.step("run", "Run the app");
  21. run_step.dependOn(&run_cmd.step);
  22. }

Building a Library

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

build.zig

  1. const Builder = @import("std").build.Builder;
  2. pub fn build(b: *Builder) void {
  3. const mode = b.standardReleaseOptions();
  4. const lib = b.addStaticLibrary("example", "src/main.zig");
  5. lib.setBuildMode(mode);
  6. lib.install();
  7. var main_tests = b.addTest("src/main.zig");
  8. main_tests.setBuildMode(mode);
  9. const test_step = b.step("test", "Run library tests");
  10. test_step.dependOn(&main_tests.step);
  11. }

Compiling C Source Code

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