build#

build.zig is where you configure how your project compiles - what files to include, what dependencies to pull in, what artifacts to produce. zig's build system is written in zig itself, so it's just code.

0.15 change#

the way you attach dependencies to your executable changed. before 0.15, you'd call exe.addModule() after creating the executable. now you declare everything upfront in a createModule call with an imports array:

const exe = b.addExecutable(.{
    .name = "myapp",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{
            .{ .name = "websocket", .module = websocket.module("websocket") },
        },
    }),
});

the .name in the imports array is what you'll use in your code: @import("websocket").

dependency hash trick#

dependencies are declared in build.zig.zon with a hash for verification. to get the correct hash for a new dependency, just put any placeholder hash and run zig build. the error message tells you what the hash should be:

error: hash mismatch... expected 1220abc..., found 1220def...

copy the "found" value into your .zon file.

don't forget#

after creating your executable, you need to tell zig to actually install it:

b.installArtifact(exe);

without this line, zig build runs successfully but produces no output. easy to miss.

x86 backend (default in 0.15)#

the self-hosted x86 backend is now the default for debug builds. roughly 5x faster compilation than LLVM for most code. threaded codegen adds up to 50% more on top of that.

if you hit codegen bugs, fall back to LLVM:

zig build -fllvm           # use LLVM backend
zig build -Doptimize=ReleaseFast  # release modes always use LLVM

the x86 backend passes more behavior tests than LLVM (1984 vs 1977) but generates slower machine code. debug builds prioritize compilation speed; release builds prioritize runtime performance.

test-obj#

0.15 added zig test-obj for compiling tests to object files instead of running them. useful when linking test code into external harnesses:

zig test-obj src/foo.zig   # produces .o file

in build.zig: addTest(.{ ... }).emit_object = true;

Configure Feed