zig-0-16

Zig Language Reference (v0.16.0)

This skill covers the Zig 0.16.0 language and standard library. Use it when writing, reviewing, or migrating Zig code, working with build.zig / build.zig.zon, standard library modules, and comptime metaprogramming.

Zig evolves rapidly. Training data, blog posts, and many public examples are stale. This skill is the main Zig 0.16.0 aggregate skill for this repository: it condenses the official 0.16.0 language reference, the official std index, the Chinese Zig homepage, and the local offline reference set under references/.

Capability Boundaries

✅ Strong Suits

1. Writing and optimizing Zig 0.16.0 code with standard library modules
2. Using the build.zig / build.zig.zon build system
3. Comptime metaprogramming, builtin functions, and type reflection
4. C interop: @cImport, linking, header management
5. Code review and migration: older versions → 0.16.0

⚠️ Requirements

1. Target version must be confirmed as 0.16.0 (run zig version)
2. Library-specific work (raylib/SDL3) should switch to the dedicated skill
3. Platform-specific APIs may require additional OS knowledge

❌ Out of Scope (with alternatives)

1. Game/graphics API development → use zig-raylib or zig-sdl3-bindings
2. Database/backend service development → use appropriate domain skill
3. Non-Zig language coding → use the corresponding language skill

When to use this skill

Use this skill when the user needs to write, review, debug, or migrate Zig 0.16.0 code, or when working with build.zig / build.zig.zon, std modules, comptime, or C interop.

Data Privacy

This skill does not collect, store, or transmit any user data. All code examples are for local development reference only.

Official Positioning

From the Zig 0.16.0 docs and Chinese homepage, Zig is a general-purpose programming language and toolchain for building robust, optimal, and reusable software.

Core design ideas

• No implicit control flow.
• No implicit memory allocation.
• No preprocessor and no macros.
• comptime makes type-driven programming and code generation first-class.
• Zig is both a language and a cross-platform toolchain for Zig, C, and C++ projects.

Primary official sources

• Language reference
• Introduction
• Standard library index
• Chinese homepage
• Build system documentation
• 0.16.0 release notes

Quick Start

Example invocations:

Write an HTTP server in Zig 0.16 using std.http
Create a build.zig that depends on a third-party library
Review this Zig code for 0.16 compatibility issues
Migrate this Zig 0.14 project to 0.16

Workflow

Step 1. Confirm version — Run zig version to verify the user is on 0.16.0

Step 2. Review official reference — Read the main skill body for the overall framework

Step 3. Look up std modules — Find the relevant module from the std index, then load the matching references/ file

Step 4. Use examples — Load copyable code snippets from examples/

Step 5. Handle migrations — For legacy code, check the Removed Features and Breaking Changes sections

Critical: How to use this skill

1. Confirm the user is targeting Zig 0.16.0 or wants modern Zig patterns.
2. Start here for language, build system, std modules, code review, or migration work.
3. Prefer local references/*.md when you need concrete examples or offline guidance.
4. Use the official links above for authority, API confirmation, and section names.
5. Switch to zig-raylib or zig-sdl3-bindings only for those library-specific workflows.

Critical: Official 0.16.0 coverage map

The official Zig 0.16.0 language reference covers these major areas:

• Introduction and Zig Standard Library entry.
• Hello World, comments, doc comments, top-level docs, identifiers, values, literals, assignment, and destructuring.
• test declarations, doctests, leak reporting, test output, and std.testing.
• Integers, floats, operators, arrays, vectors, pointers, many-item pointers, slices, sentinel-terminated types, and optional pointers.
• struct, enum, union, opaque, tuples, anonymous literals, non-exhaustive enums, tagged unions, and result location semantics.
• Blocks, labels, switch, while, for, if, defer, errdefer, unreachable, and noreturn.
• Functions, methods, errors, optionals, casts, coercions, peer type resolution, and zero-bit types.
• comptime, generic data structures, builtin functions, atomics, async-related syntax history, and assembly.
• C interop related builtins such as @cImport, @cInclude, @extern, and @export.
• The Zig Build System, which points to the dedicated build-system docs.

Critical: Standard library 0.16.0 coverage map

The official 0.16.0 std index exposes the modules most often needed for application work:

• Build and tooling: std.Build, std.zig, std.zon
• I/O and OS: std.Io, std.fs, std.process, std.os, std.c
• Memory and text: std.heap, std.mem, std.fmt, std.ascii, std.unicode, std.base64
• Data and networking: std.http, std.json, std.Uri, std.net
• Runtime services: std.log, std.debug, std.testing, std.time, std.Tz
• Algorithms and utilities: std.math, std.hash, std.crypto, std.Random, std.sort, std.simd
• Concurrency and reflection: std.Thread, std.atomic, std.meta
• Containers: std.ArrayList, std.HashMap, std.ArrayHashMap, std.MultiArrayList, std.StaticStringMap, std.bit_set, std.PriorityQueue

Use the official std index to confirm module names and the local references/ folder for curated examples and practical notes.

Critical: Removed Features Still Missing in 0.16

usingnamespace - removed

// WRONG
pub usingnamespace @import("other.zig");

// CORRECT
const other = @import("other.zig");
pub const foo = other.foo;

async/await - removed

These keywords are still not part of normal Zig 0.16 source code patterns. Do not suggest legacy async examples from old posts.

@fence - removed

Use stronger atomic orderings or RMW operations instead.

Critical: I/O API Rewrite

The std.io era patterns remain stale. Modern Zig uses std.Io.Writer and std.Io.Reader with explicit buffers and interface access.

Writing

// WRONG - old API
const stdout = std.io.getStdOut().writer();
try stdout.print("Hello\n", .{});

// CORRECT - modern API
var buf: [4096]u8 = undefined;
var stdout_writer = std.fs.File.stdout().writer(&buf);
const stdout = &stdout_writer.interface;
try stdout.print("Hello\n", .{});
try stdout.flush();

Reading

var buf: [4096]u8 = undefined;
var file_reader = file.reader(&buf);
const r = &file_reader.interface;

while (try r.takeDelimiter('\n')) |line| {
    // line does not include '\n'
}

Fixed writer and reader

var out_buf: [256]u8 = undefined;
var w: std.Io.Writer = .fixed(&out_buf);
try w.print("Hello {s}", .{"world"});
const result = w.buffered();

var r: std.Io.Reader = .fixed("hello\nworld");
const first = (try r.takeDelimiter('\n')).?;
_ = first;

Deprecated names such as BufferedWriter, GenericWriter, AnyWriter, and FixedBufferStream should not be suggested for Zig 0.16 code.

Critical: Build System

The official 0.16.0 docs describe the Zig Build System as a cross-platform, dependency-free way to declare project build logic in build.zig.

Core workflow

• Run zig init or scaffold the project manually.
• Inspect available options with zig build --help.
• Put package metadata and dependencies in build.zig.zon.
• Use std.Build and module-based APIs in build.zig.

Modern build pattern

const std = @import("std");

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

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

    b.installArtifact(exe);
}

root_module is mandatory

// WRONG - removed field on addExecutable/addLibrary/addTest
b.addExecutable(.{
    .name = "app",
    .root_source_file = b.path("src/main.zig"),
});

// CORRECT
b.addExecutable(.{
    .name = "app",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
    }),
});

Module imports changed

// WRONG
exe.addModule("helper", helper_mod);

// CORRECT
exe.root_module.addImport("helper", helper_mod);

Dependency modules

const dep = b.dependency("lib", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("lib", dep.module("lib"));

Compile-level methods like exe.linkSystemLibrary() and exe.addCSourceFiles() should generally move to exe.root_module.* based APIs in modern code.

Critical: Container Initialization

Never suggest .{} for container initialization unless the type is documented to support it. For the common std containers and allocators, Zig 0.16 still expects .empty or .init.

// WRONG
var list: std.ArrayList(u32) = .{};
var gpa: std.heap.DebugAllocator(.{}) = .{};

// CORRECT
var list: std.ArrayList(u32) = .empty;
var map: std.AutoHashMapUnmanaged(u32, u32) = .empty;
var gpa: std.heap.DebugAllocator(.{}) = .init;
var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);

Naming changes that remain relevant

• std.ArrayListUnmanaged -> std.ArrayList
• std.heap.GeneralPurposeAllocator -> std.heap.DebugAllocator

std.BoundedArray replacement

var buffer: [8]i32 = undefined;
var stack = std.ArrayList(i32).initBuffer(&buffer);

Critical: Format Strings

Some custom formatters now require {f}:

// WRONG
std.debug.print("{}", .{std.zig.fmtId("x")});

// CORRECT
std.debug.print("{f}", .{std.zig.fmtId("x")});

Modern format methods also use writer-based signatures:

pub fn format(self: @This(), writer: *std.Io.Writer) std.Io.Writer.Error!void {
    _ = self;
    _ = writer;
}

Official Zig 0.16 workflow

Learn and bootstrap

• Read the Introduction section first.
• Use zig version to confirm the compiler is 0.16.0.
• Use the Chinese homepage positioning when explaining Zig to users: robust, optimal, reusable.

Build, run, test

zig build
zig build run
zig test src/main.zig
zig build test

Chinese homepage sample pattern

const std = @import("std");
const parseInt = std.fmt.parseInt;

test "parse integers" {
    const input = "123 67 89,99";
    const gpa = std.testing.allocator;

    var list: std.ArrayList(u32) = .empty;
    defer list.deinit(gpa);

    var it = std.mem.tokenizeAny(u8, input, " ,");
    while (it.next()) |num| {
        const n = try parseInt(u32, num, 10);
        try list.append(gpa, n);
    }

    const expected = [_]u32{ 123, 67, 89, 99 };
    for (expected, list.items) |exp, actual| {
        try std.testing.expectEqual(exp, actual);
    }
}

Breaking Changes Carried Forward from Recent Releases

These patterns are still useful for 0.16 review and migration work:

@branchHint replaces @setCold

// WRONG
@setCold(true);

// CORRECT
@branchHint(.cold);

@export takes a pointer

// WRONG
@export(foo, .{ .name = "bar" });

// CORRECT
@export(&foo, .{ .name = "bar" });

Typed inline asm clobbers

// WRONG
: "rcx", "r11"

// CORRECT
: .{ .rcx = true, .r11 = true }

Decl literals

const S = struct {
    x: u32,
    const default: S = .{ .x = 0 };
    fn init(v: u32) S { return .{ .x = v }; }
};

const a: S = .default;
const b: S = .init(42);

Labeled switch

state: switch (initial) {
    .idle => continue :state .running,
    .running => if (done) break :state result else continue :state .running,
    .error => return error.Failed,
}

Non-exhaustive enum switch

switch (value) {
    .a, .b => {},
    else => {},  // other named tags
    _ => {},     // unnamed integer values
}

Quick Fixes

Error	Fix
no field 'root_source_file'	Use root_module = b.createModule(.{...}) in addExecutable/addLibrary/addTest
use of undefined value	Arithmetic on undefined is illegal; initialize data before use
type 'f32' cannot represent integer	Use a float literal such as 123_456_789.0
std.io examples don't compile	Use std.Io writer/reader patterns with explicit buffers
Old container init example uses .{}	Prefer .empty or .init depending on the type
ambiguous format string	Use {f} for custom formatter output
sanitize_c = true no longer works	Use the modern enum-style sanitize configuration from recent Zig releases
std.fifo.LinearFifo examples fail	Prefer std.Io.Reader or std.Io.Writer based streaming patterns
posix.sendfile examples fail	Use file writer APIs such as .sendFileAll()
std.fmt.Formatter examples fail	Use std.fmt.Alt in modern code
fmtSliceEscapeLower/fmtSliceEscapeUpper missing	Use std.ascii.hexEscape(bytes, .lower/.upper)
User's zig version is not 0.16.0	Confirm version, then guide to upgrade or switch skills
User asks about raylib/SDL3 API	Guide to use zig-raylib / zig-sdl3-bindings
Code from old blog/tutorial with unknown version	Use Quick Fixes table to check each compilation error pattern
Need module-specific details	Load the matching local references/*.md file
Build-system API uncertainty	Check both local std-build.md and the official build-system docs

Offline Examples

Use the local examples/ directory when you need copyable snippets quickly or cannot rely on live web access:

• examples/quickstart-workflows.md - starter project, tests, JSON, process, HTTP, review checklist
• examples/build-zig-zon-workflows.md - package metadata, dependencies, executable and library layouts
• examples/comptime-patterns.md - reflection, generic helpers, generated types, inline loops
• examples/c-interop-workflows.md - @cImport, exported APIs, static libraries, headers
• examples/std-thread-patterns.md - spawn and join, mutex, wait group, atomic counter patterns

Official Distillations

Use docs/official/ when you need offline distilled versions of the official Zig 0.16 pages themselves rather than topic cards:

• docs/official/official-sources.md - source index and navigation
• docs/official/official-language-reference-0.16.md - language reference coverage map
• docs/official/official-introduction-0.16.md - introduction distillation
• docs/official/official-std-index-0.16.md - standard library index distillation
• docs/official/official-zh-cn-home-0.16.md - Chinese homepage distillation

Language References

Load these references when working with core language features:

Code Style

• Style Guide - Official Zig naming conventions, whitespace rules, doc comment guidance, redundancy avoidance, zig fmt

Language Basics & Built-ins

• Language Basics - Core language: types, control flow, error handling, optionals, structs, enums, unions, pointers, slices, comptime, functions
• Built-in Functions - All @ built-ins: casts, arithmetic, bit ops, memory, atomics, introspection, SIMD, C interop

Standard Library References

Load these references when working with specific modules:

Memory & Slices

• std.mem - Slice search or compare, split or tokenize, alignment, endianness, byte conversion

Text & Encoding

• std.fmt - Format strings, integer or float parsing, custom formatters, {f} notes
• std.ascii - ASCII classification, case conversion, case-insensitive comparison
• std.unicode - UTF-8 and UTF-16 handling, codepoint iteration, validation
• std.base64 - Base64 encoding and decoding

Math & Random

• std.math - Floating-point ops, trig, checked arithmetic, constants
• std.Random - PRNGs, random integers or floats, shuffle, distributions
• std.hash - Hash functions, checksums, auto-hashing

SIMD & Vectorization

• std.simd - SIMD vector utilities and patterns

Time & Timing

• std.time - Timestamps, timers, epoch conversions, calendar helpers
• std.Tz - Timezone database parsing and timezone handling

Sorting & Searching

• std.sort - Sorting algorithms, binary search, min and max helpers

Core Data Structures

• std.ArrayList - Dynamic arrays and buffer-backed patterns
• std.HashMap / AutoHashMap - Hash maps, string maps, ordered maps
• std.ArrayHashMap - Insertion-order preserving maps
• std.MultiArrayList - Struct-of-arrays storage
• std.SegmentedList - Stable pointers and arena-friendly storage
• std.DoublyLinkedList / SinglyLinkedList - Intrusive linked lists
• std.PriorityQueue - Binary heap based queues
• std.PriorityDequeue - Double-ended priority extraction
• std.Treap - Balanced tree with ordered keys
• std.bit_set - Static and dynamic bit sets
• std.BufMap / BufSet - String-owning maps and sets
• std.StaticStringMap - Compile-time string lookup
• std.enums - EnumSet, EnumMap, EnumArray

Allocators

• std.heap - Allocator selection guide and custom allocator patterns

I/O & Files

• std.Io - Reader and Writer API patterns, buffered I/O, streaming, binary data
• std.fs - Files, directories, iteration, atomic writes, paths
• std.tar - Tar archive handling
• std.zip - ZIP archive handling
• std.compress - Compression and decompression modules

Networking

• std.http - HTTP client or server patterns, TLS, compression
• std.net - Socket basics, address parsing, DNS
• std.Uri - URI parsing, percent-encoding, relative resolution

Process Management

• std.process - Child process spawning, environment, arguments, exec

OS-Specific APIs

• std.os - Platform-specific APIs, syscalls, Windows or WASI access
• std.c - C ABI types and libc bindings

Concurrency

• std.Thread - Thread spawning, mutexes, rw locks, conditions, semaphores
• std.atomic - Atomic operations, orderings, compare-and-swap

Patterns & Best Practices

• Zig Patterns - Practical patterns for writing and reviewing Zig code
• Code Review - Review checklist and stale-pattern detection

Audience

User Type	Usage
Zig beginners	Write basic code and learn 0.16 API patterns
Migration users	Migrate from older versions by following the Critical sections
Experienced developers	Deep-dive into std modules via references/ and copy patterns from examples/

Customization options:

• Specify output format (full code / snippet / diff)
• Request a specific module focus (e.g., build.zig only or I/O only)

Gotchas

1. Always confirm the version first — Verify zig version is 0.16.0 before giving advice; API differences cause compilation errors
2. build.zig requires root_module — addExecutable/addLibrary no longer accept root_source_file; use root_module = b.createModule(...)
3. std.Io pattern is mandatory — Old std.io patterns (e.g. std.io.getStdOut().writer()) do not compile under 0.16.0
4. Container init does not use .{ } — ArrayList/HashMap must use .empty or .init
5. Format strings need {f} — Custom formatter output requires {f} instead of {}
6. Prefer offline references — Use references/ local files over web search to ensure 0.16.0 consistency
7. Do not assume the latest compiler — If the user's version is not 0.16.0, guide them to upgrade or switch skills

FAQ

Q: How does this skill differ from zig-0.15? A: zig-0-16 is the primary skill covering the latest stable 0.16.0 release. zig-0.15 is retained as a legacy compatibility reference.

Q: What if example code fails to compile? A: Verify zig version outputs 0.16.0. If the version differs, some APIs may have changed. Use the Quick Fixes table to diagnose.

Q: How do I find a specific std module? A: Look up the module name in the Standard Library References section, then load the matching references/*.md file.

Q: Can I use this offline? A: Yes. All references/ and examples/ files are local copies and work without internet access.

Q: Does this skill collect my code? A: No. This skill is a pure documentation reference and does not collect any user data.

Serialization

• std.json - JSON parsing, serialization, dynamic values, streaming
• std.zon - ZON parsing and serialization for build.zig.zon and configs

Testing & Debug

• std.testing - Unit test assertions and utilities
• std.debug - Panic, assert, stack traces, hex dump
• std.log - Scoped logging and configurable levels

Metaprogramming

• Comptime Reference - Comptime fundamentals, reflection, generic patterns
• std.meta - Type introspection, field iteration, stringToEnum, generic programming

Compiler Utilities

• std.zig - AST parsing, tokenization, source analysis, linters, formatters, ZON parsing

Security & Cryptography

• std.crypto - Hashing, AEAD, signatures, key exchange, password hashing, secure random

Build System

• std.Build - Build system, modules, dependencies, steps, options, testing, C or C++ integration

Interoperability

• C Interop - Exporting C-compatible APIs, calling conventions, libraries, headers, module maps