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;