Zig 0.16.x Programming

Version scope: Pinned to Zig 0.16.x (specifically 0.16.0). For master/nightly, APIs may differ. Always check official docs for the target version.

Many LLMs have outdated Zig knowledge (0.11-0.14) that causes compilation errors. This skill ensures correct 0.16.x API usage.

Official Documentation

• Language Reference: https://ziglang.org/documentation/0.16.2/
• Standard Library: https://ziglang.org/documentation/0.16.2/std/
• Release Notes: https://ziglang.org/download/0.16.1/release-notes.html
• Build System: https://ziglang.org/learn/build-system/
• Source: https://codeberg.org/ziglang/zig

Critical API Changes in 0.16

ArrayList -- Allocator Now Required

All mutating methods require an explicit allocator parameter. AssumeCapacity variants do not.

var list = try std.ArrayList(T).initCapacity(allocator, 16);
defer list.deinit(allocator);
try list.append(allocator, item);
try list.appendSlice(allocator, items);
_ = try list.addOne(allocator);
_ = try list.toOwnedSlice(allocator);

list.appendAssumeCapacity(item); // no allocator needed

I/O Rewrite (Writergate)

New std.Io.Writer and std.Io.Reader are non-generic, buffer-in-interface, ring-buffer-based types.

// stdout (0.16+)
var stdout_buffer: [1024]u8 = undefined;
var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
const stdout: *std.Io.Writer = &stdout_writer.interface;
try stdout.print("Hello\n", .{});
try stdout.flush();

// adapter for old-style writers
fn useOldWriter(old_writer: anytype) !void {
    var adapter = old_writer.adaptToNewApi(&.{});
    const w: *std.Io.Writer = &adapter.new_interface;
    try w.print("{s}", .{"example"});
}

@typeInfo Enum Cases -- Lowercase

// 0.16+ uses lowercase / @"" escaped names
if (@typeInfo(T) == .slice) { ... }
if (@typeInfo(T) == .pointer) { ... }
if (@typeInfo(T) == .@"struct") { ... }
if (@typeInfo(T) == .@"enum") { ... }
if (@typeInfo(T) == .@"union") { ... }

Custom Format Functions -- {f} Specifier

// 0.16+: use {f}, simplified signature
pub fn format(self: Self, writer: anytype) !void {
    try writer.writeAll("...");
}
// Usage: std.fmt.bufPrint(&buf, "{f}", .{value});

usingnamespace Removed

// explicit re-exports instead
pub const foo = @import("other.zig").foo;
// or namespace via field
pub const other = @import("other.zig");

async/await Keywords Removed

Async functionality will be provided via the standard library's new I/O interface in a future release.

Build System (build.zig)

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "hello",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    b.installArtifact(exe);

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

    const unit_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = b.graph.host,
        }),
    });
    const run_tests = b.addRunArtifact(unit_tests);
    const test_step = b.step("test", "Run unit tests");
    test_step.dependOn(&run_tests.step);
}

Key changes from 0.14:

• root_source_file moved inside b.createModule(...) via root_module
• Use b.path("src/main.zig") instead of .{ .path = "src/main.zig" }
• Libraries: b.addLibrary(.{ .linkage = .dynamic, ... }) replaces addSharedLibrary
• Module deps: exe.root_module.addImport("sdk", sdk_module) replaces exe.addModule
• Test target: use b.graph.host for native

Common Patterns

HashMap

// Managed (stores allocator)
var map = std.StringHashMap(V).init(allocator);
defer map.deinit();
try map.put(key, value);

// Unmanaged (allocator per call)
var map = std.StringHashMapUnmanaged(V){};
defer map.deinit(allocator);
try map.put(allocator, key, value);

JSON

// Parse
const parsed = try std.json.parseFromSlice(MyStruct, allocator, json_str, .{});
defer parsed.deinit();
const data = parsed.value;

// Serialize (no stringifyAlloc in 0.16.2)
const formatted = try std.fmt.allocPrint(allocator, "{f}", .{std.json.fmt(data, .{})});
defer allocator.free(formatted);

Testing

test "no memory leaks" {
    const allocator = std.testing.allocator;
    const data = try allocator.alloc(u8, 100);
    defer allocator.free(data);
}

test "assertions" {
    try std.testing.expect(condition);
    try std.testing.expectEqual(expected, actual);
    try std.testing.expectEqualSlices(u8, expected, actual);
    try std.testing.expectError(error.SomeError, result);
    try std.testing.expectEqualStrings("hello", str);
}

Memory Operations

@memcpy(dest, src);
@memset(buffer, 0);
const equal = std.mem.eql(u8, slice1, slice2);
const index = std.mem.indexOf(u8, haystack, needle);

Common Error Messages

Verification Workflow

1. Run zig build to check compilation
2. Match errors against the table above and apply fixes
3. Run zig build test to verify functionality
4. Use zig build -Doptimize=ReleaseFast test to catch UB

Additional References

• For stdlib API details (HTTP, Ed25519, Base64): references/stdlib-api-reference.md
• For build system details: references/build-system.md
• For migration patterns from 0.13/0.14: references/migration-patterns.md

Community Resources

• Zig Cookbook: https://cookbook.ziglang.cc/
• awesome-zig: https://github.com/zigcc/awesome-zig
• Zigistry (package registry): https://zigistry.dev/

Production Codebases