std.Build - Build System API

The std.Build API provides the build system functionality used in build.zig files. This is the primary interface for configuring how Zig projects are compiled.

Overview

Every build.zig file exports a build function that receives a *Build parameter:

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});
    
    const exe = b.addExecutable(.{
        .name = "myapp",
        .root_module = .{
            .source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        },
    });
    
    b.installArtifact(exe);
}

Build Object

The Build type is the main entry point for build system operations.

Key Fields

allocator

Allocator

Allocator for build-time allocations. Uses arena allocation.

install_prefix

[]const u8

Installation prefix path (e.g., “/usr” or “zig-out”).

build_root

Cache.Directory

Path to the directory containing build.zig.

cache_root

Cache.Directory

Path to the cache directory.

graph

*Graph

Shared state among all Build instances.

Creating Compilation Artifacts

Executables

addExecutable

fn(*Build, ExecutableOptions) *Step.Compile

Creates a step that builds an executable.ExecutableOptions:

Show Fields

name

[]const u8

required

Name of the executable.

root_module

*Module

required

Root module configuration including source file, target, and optimization mode.

version

?std.SemanticVersion

default:"null"

Semantic version of the executable.

linkage

?std.builtin.LinkMode

default:"null"

Linkage mode (static or dynamic).

max_rss

usize

default:"0"

Maximum RSS (resident set size) in bytes.

use_llvm

?bool

default:"null"

Whether to use LLVM backend.

use_lld

?bool

default:"null"

Whether to use LLD linker.

Example:

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

Libraries

addLibrary

fn(*Build, LibraryOptions) *Step.Compile

Creates a step that builds a library (static or dynamic).LibraryOptions:

Show Fields

name

[]const u8

required

Name of the library.

root_module

*Module

required

Root module configuration.

linkage

std.builtin.LinkMode

default:".static"

Linkage mode: .static or .dynamic.

version

?std.SemanticVersion

default:"null"

Library version.

Example:

const lib = b.addLibrary(.{
    .name = "mylib",
    .root_module = .{
        .source_file = b.path("src/lib.zig"),
        .target = target,
        .optimize = optimize,
    },
    .linkage = .dynamic,
});

Object Files

addObject

fn(*Build, ObjectOptions) *Step.Compile

Creates a step that builds an object file (.o).Example:

const obj = b.addObject(.{
    .name = "myobj",
    .root_module = .{
        .source_file = b.path("src/code.zig"),
        .target = target,
        .optimize = optimize,
    },
});

Tests

addTest

fn(*Build, TestOptions) *Step.Compile

Creates an executable containing unit tests.Equivalent to zig test --test-no-exec. This step does not run the tests; use addRunArtifact to create a run step.TestOptions:

Show Fields

name

[]const u8

default:"'test'"

Name of the test executable.

root_module

*Module

required

Root module containing tests.

filters

[]const []const u8

default:"&.{}"

Test name filters.

test_runner

?Step.Compile.TestRunner

default:"null"

Custom test runner.

Example:

const unit_tests = b.addTest(.{
    .root_module = .{
        .source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    },
});

const run_tests = b.addRunArtifact(unit_tests);
const test_step = b.step("test", "Run unit tests");
test_step.dependOn(&run_tests.step);

Running Programs

addRunArtifact

fn(*Build, *Step.Compile) *Step.Run

Creates a step to run a compiled artifact.Example:

const run_exe = b.addRunArtifact(exe);
run_exe.addArg("--verbose");

const run_step = b.step("run", "Run the application");
run_step.dependOn(&run_exe.step);

addSystemCommand

fn(*Build, []const []const u8) *Step.Run

Creates a step to run a system command.Be careful using this function as it introduces a system dependency.Example:

const git_cmd = b.addSystemCommand(&.{ "git", "rev-parse", "HEAD" });

Modules

addModule

fn(*Build, []const u8, Module.CreateOptions) *Module

Creates a module and adds it to the package’s module set, making it available to other packages which depend on this one.Example:

const my_module = b.addModule("mymodule", .{
    .source_file = b.path("src/module.zig"),
});

// Other packages can now import this module

createModule

fn(*Build, Module.CreateOptions) *Module

Creates a private module for use by the current package only.Use addModule to create a public module.Example:

const utils = b.createModule(.{
    .source_file = b.path("src/utils.zig"),
});

exe.root_module.addImport("utils", utils);

Installation

installArtifact

fn(*Build, *Step.Compile) void

Installs an artifact using default options. Adds the install step to the top-level install step dependencies.Example:

b.installArtifact(exe);

addInstallArtifact

fn(*Build, *Step.Compile, Step.InstallArtifact.Options) *Step.InstallArtifact

Creates an install step for an artifact with custom options. Does not automatically add to top-level install step.Example:

const install_exe = b.addInstallArtifact(exe, .{
    .dest_dir = .{ .override = .{ .custom = "custom/path" } },
});
b.getInstallStep().dependOn(&install_exe.step);

addInstallFile

fn(*Build, LazyPath, []const u8) *Step.InstallFile

Installs a file to the installation prefix.Parameters:

source - Source file path
dest_rel_path - Destination path relative to prefix

Example:

const install_readme = b.addInstallFile(
    b.path("README.md"),
    "share/doc/myapp/README.md"
);

addInstallDirectory

fn(*Build, Step.InstallDir.Options) *Step.InstallDir

Installs a directory.Example:

b.installDirectory(.{
    .source_dir = b.path("assets"),
    .install_dir = .prefix,
    .install_subdir = "share/myapp/assets",
});

File Operations

addWriteFiles

fn(*Build) *Step.WriteFile

Creates a step that writes files to the cache directory.Example:

const wf = b.addWriteFiles();
wf.add("version.txt", "1.0.0");
const version_file = wf.getDirectory().path(b, "version.txt");

addUpdateSourceFiles

fn(*Build) *Step.UpdateSourceFiles

Creates a step that updates source files (useful for generated code).Example:

const update_files = b.addUpdateSourceFiles();
update_files.addCopyFileToSource(generated_file, "src/generated.zig");

addConfigHeader

fn(*Build, Step.ConfigHeader.Options, anytype) *Step.ConfigHeader

Creates a C header file, possibly based on a template (e.g., config.h.in).Example:

const config_h = b.addConfigHeader(.{
    .style = .{ .cmake = b.path("config.h.in") },
}, .{
    .HAVE_FEATURE_X = 1,
    .VERSION_STRING = "1.0.0",
});

exe.addConfigHeader(config_h);

Build Options

addOptions

fn(*Build) *Step.Options

Creates a set of key-value pairs that can be converted into a Zig source file and imported.Provides a way to expose build.zig values to Zig source code.Example:

const options = b.addOptions();
options.addOption([]const u8, "version", "1.0.0");
options.addOption(bool, "enable_feature_x", true);

exe.root_module.addOptions("build_options", options);

In your source code:

const build_options = @import("build_options");
const version = build_options.version;

User Options

option

fn(*Build, comptime T: type, []const u8, []const u8) ?T

Creates a configuration option to be passed to the build script.Users can set these with -D arguments when running zig build.Returns null when the option is left to default.Parameters:

T - Type of the option
name - Option name
description - Help text

Supported types:

bool, int, float
enum
[]const u8 (string)
[]const []const u8 (list of strings)
LazyPath
std.zig.BuildId

Example:

const enable_feature = b.option(bool, "enable-feature", "Enable feature X") orelse false;
const log_level = b.option(enum { debug, info, warn, err }, "log-level", "Log level") orelse .info;

const options = b.addOptions();
options.addOption(bool, "feature_enabled", enable_feature);

Usage: zig build -Denable-feature=true -Dlog-level=debug

standardOptimizeOption

fn(*Build, StandardOptimizeOptionOptions) std.builtin.OptimizeMode

Exposes standard zig build options for choosing optimization mode.Example:

const optimize = b.standardOptimizeOption(.{});

Usage: zig build --release=fast or zig build -Doptimize=ReleaseFast

standardTargetOptions

fn(*Build, StandardTargetOptionsArgs) ResolvedTarget

Exposes standard zig build options for choosing a target and resolves the target query.StandardTargetOptionsArgs:

Show Fields

default_target

Target.Query

default:".{}"

Default target when none specified.

whitelist

?[]const Target.Query

default:"null"

Allowed targets (null means all targets allowed).

Example:

const target = b.standardTargetOptions(.{});

Usage: zig build -Dtarget=x86_64-linux

Steps

step

fn(*Build, []const u8, []const u8) *Step

Creates a new top-level step that users can invoke.Parameters:

name - Step name (used in zig build <name>)
description - Help text

Example:

const docs_step = b.step("docs", "Generate documentation");
docs_step.dependOn(&install_docs.step);

Usage: zig build docs

getInstallStep

fn(*Build) *Step

Returns the top-level install step.Example:

b.getInstallStep().dependOn(&custom_install.step);

Dependencies

dependency

fn(*Build, []const u8, anytype) *Dependency

Fetches a dependency and returns its Build instance.Parameters:

name - Dependency name (from build.zig.zon)
args - Options to pass to the dependency’s build.zig

Example:

const dep = b.dependency("mylib", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("mylib", dep.module("mylib"));

Utilities

path

fn(*Build, []const u8) LazyPath

References a file or directory relative to the source root.Example:

const readme = b.path("README.md");

fmt

fn(*Build, comptime []const u8, anytype) []u8

String formatting using allocator.Example:

const msg = b.fmt("Building version {s}", .{version});

dupe

fn(*Build, []const u8) []u8

Duplicates a string without handling out of memory.Example:

const owned = b.dupe(borrowed_str);

pathJoin

fn(*Build, []const []const u8) []u8

Joins path components.Example:

const full_path = b.pathJoin(&.{ "src", "main.zig" });

Step

type

Represents a single build step.Location: lib/std/Build/Step.zig

Module

type

Represents a Zig module with configuration.Location: lib/std/Build/Module.zig

Cache

type

Build cache management.Location: lib/std/Build/Cache.zig

Core

Data Structures

Memory

System

Utilities

std.Build - Build System API

Overview

Build Object

Key Fields

Creating Compilation Artifacts

Executables

Libraries

Object Files

Tests

Running Programs

Modules

Installation

File Operations

Build Options

User Options

Steps

Dependencies

Utilities

Step

Module

Cache

See Also

Build docs developers (and LLMs) love

Core

Data Structures

Memory

System

Utilities

Documentation Index

​Overview

​Build Object

​Key Fields

​Creating Compilation Artifacts

​Executables

​Libraries

​Object Files

​Tests

​Running Programs

​Modules

​Installation

​File Operations

​Build Options

​User Options

​Steps

​Dependencies

​Utilities

​Related Types

​Step

​Module

​Cache

​See Also

Build docs developers (and LLMs) love

Overview

Build Object

Key Fields

Creating Compilation Artifacts

Executables

Libraries

Object Files

Tests

Running Programs

Modules

Installation

File Operations

Build Options

User Options

Steps

Dependencies

Utilities

Related Types

Step

Module

Cache

See Also