Zig Knowledge Patch Skill

Zig Knowledge Patch

Claude's baseline knowledge covers Zig through 0.12.x. This skill provides breaking changes and new features in 0.13.0 and 0.14.0.

Breaking Changes Quick Reference

| Version | Change | Impact | Details | |---------|--------|--------|---------| | 0.13.0 | ComptimeStringMap -> StaticStringMap | API rename + new init pattern | stdlib-changes | | 0.13.0 | zig-cache -> .zig-cache | Update .gitignore | stdlib-changes | | 0.13.0 | std.Progress rework | Pass Node by value, new init API | stdlib-changes | | 0.14.0 | std.builtin.Type fields lowercased | .Int -> .int, .Struct -> .@"struct" | language-changes | | 0.14.0 | @setCold removed | Use @branchHint(.cold) | language-changes | | 0.14.0 | @fence removed | Use stronger atomic orderings | language-changes | | 0.14.0 | @export takes pointer | Add & operator | language-changes | | 0.14.0 | CallingConvention overhauled | Tagged union, .C -> .c | language-changes | | 0.14.0 | Anonymous struct types removed | Tuples unified, structural equivalence | language-changes | | 0.14.0 | GeneralPurposeAllocator -> DebugAllocator | New init pattern | stdlib-changes | | 0.14.0 | ArrayList deprecated | Use ArrayListUnmanaged, pass allocator | stdlib-changes | | 0.14.0 | std.mem.page_size removed | Use std.heap.pageSize() | stdlib-changes | | 0.14.0 | Build API: root_module | addExecutable takes root_module | build-system | | 0.14.0 | Package hash format changed | New format includes name/version/fingerprint | build-system |

New Language Features (0.14.0)

Labeled Switch

Switch statements can be labeled and targeted by continue for state machines:

foo: switch (@as(u8, 1)) {
    1 => continue :foo 2, // jump to case 2
    2 => continue :foo 3,
    3 => return,
    else => unreachable,
}

Generates optimized branch prediction code. Also supports break from labeled switch.

Decl Literals

.foo syntax resolves to declarations on the target type (not just enum variants):

const S = struct {
    x: u32,
    const default: S = .{ .x = 123 };
    fn init(val: u32) S {
        return .{ .x = val + 1 };
    }
};
const a: S = .default; // S.default
const b: S = .init(100); // S.init(100)

Key pattern: Unmanaged containers use .empty instead of .{}:

var list: std.ArrayListUnmanaged(u32) = .empty;
foo: std.ArrayListUnmanaged(u32) = .empty, // as struct field default

Fields and declarations in the same container cannot share names.

@branchHint

Replaces @setCold. Must be first statement in block:

@branchHint(.unlikely);  // .none, .likely, .unlikely, .cold, .unpredictable

@FieldType Builtin

comptime assert(@FieldType(MyStruct, "field_name") == u32);

@splat for Arrays

var pixels: [W][H]Rgba = @splat(@splat(.black));

See references/language-changes.md for full details.

Standard Library (0.14.0)

Allocator Changes

// DebugAllocator (replaces GeneralPurposeAllocator)
var debug_allocator: std.heap.DebugAllocator(.{}) = .init;
const gpa = debug_allocator.allocator();
defer _ = debug_allocator.deinit();

// SmpAllocator (for ReleaseFast, competitive with glibc)
const allocator = std.heap.smp_allocator;

New remap on Allocator.VTable enables relocation during resize (uses mremap on Linux).

Unmanaged Containers (managed versions deprecated)

var list: std.ArrayListUnmanaged(i32) = .empty;
defer list.deinit(gpa);
try list.append(gpa, 1234);  // allocator passed to methods

Same for ArrayHashMapUnmanaged. popOrNull renamed to pop.

ZON Support

Runtime: std.zon.parse.fromSlice(T, allocator, zon_bytes, .{}). Compile-time: const cfg: Config = @import("config.zon");.

Runtime Page Size

std.heap.pageSize() (runtime, memoized). Comptime bounds: page_size_min, page_size_max.

See references/stdlib-changes.md for full details.

Build System (0.14.0)

File System Watching

zig build --watch                # rebuilds on source changes
zig build --watch --debounce 100 # custom debounce (default 50ms)

Module-First API

const mod = b.createModule(.{
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
});
const exe = b.addExecutable(.{ .name = "hello", .root_module = mod });
// Reuse same module for tests:
const tests = b.addTest(.{ .name = "hello-test", .root_module = mod });

Incremental Compilation (opt-in)

zig build -Dno-bin -fincremental --watch  # fast error-checking loop

x86 Backend

98% behavior test pass rate. Select with -fno-llvm. Expected default for debug mode in 0.15.0.

See references/build-system.md for full details.

Major Deprecation Removals (0.14.0)

Now compile errors: std.mem.tokenize (use tokenizeAny/tokenizeSequence/tokenizeScalar), std.mem.split (use splitSequence/splitAny/splitScalar), std.rand (use std.Random), std.TailQueue (use std.DoublyLinkedList), std.zig.CrossTarget (use std.Target.Query), std.fs.MAX_PATH_BYTES (use max_path_bytes).

Reference Files

| File | Contents | |------|----------| | language-changes.md | Labeled switch, decl literals, @branchHint, @fence removal, CallingConvention, type field renames, packed struct changes, tuple unification | | stdlib-changes.md | DebugAllocator, SmpAllocator, remap API, unmanaged containers, ZON, runtime page size, StaticStringMap, Progress rework, deprecations | | build-system.md | --watch, root_module API, addLibrary, package hash format, incremental compilation, fuzzer, WriteFile/RemoveDir changes |

Agent Skills: Zig Knowledge Patch

Install this agent skill to your local

Skill Files