Zig

Compile & Run

Common Flags

Cross-Compilation

Zig can cross-compile to over 40 targets out of the box, including every major OS and architecture. No extra toolchains needed.

# List all supported targets
zig targets | jq '.arch'

# Build for ARM Linux from any host
zig build-exe src/main.zig -target aarch64-linux-gnu

# Build for Windows from Linux/macOS
zig build-exe src/main.zig -target x86_64-windows-msvc

# Build for macOS from Linux
zig build-exe src/main.zig -target x86_64-macos-none

# Use Zig as a drop-in C cross-compiler
zig cc -target aarch64-linux-gnu hello.c -o hello

Package Manager (0.12+)

# Add a dependency to build.zig.zon
zig fetch --save https://github.com/user/repo/archive/main.tar.gz

# build.zig.zon declares dependencies
.{
    .name = "my-project",
    .version = "0.1.0",
    .dependencies = .{
        .@"zig-clap" = .{
            .url = "https://github.com/Hejsil/zig-clap/archive/v0.4.0.tar.gz",
            .hash = "122053...",
        },
    },
}

Variable Declarations

// `const` bindings are immutable
const x: i32 = 42;

// `var` bindings are mutable
var y: u8 = 0;
y += 1;

// Type inference with `const`
const name = "Zig";   // inferred as *const [3:0]u8

// Unused variables are compile errors (use _ to discard)
_ = some_function();

// Undefined initialization (dangerous but useful)
var buf: [1024]u8 = undefined;

Primitive Types

Structs, Enums & Unions

// Structs
const Point = struct {
    x: f64,
    y: f64,

    pub fn distance(self: Point, other: Point) f64 {
        const dx = self.x - other.x;
        const dy = self.y - other.y;
        return @sqrt(dx * dx + dy * dy);
    }
};

// Enums
const Color = enum {
    red,
    green,
    blue,

    pub fn isWarm(self: Color) bool {
        return self == .red;
    }
};

// Tagged unions (like Rust enums)
const Token = union(enum) {
    number: f64,
    string: []const u8,
    eof: void,
};

Optionals

Zig uses ?T for optional types instead of null pointers. This forces explicit handling of missing values.

// Optional type: ?T
var maybe: ?u32 = 42;
maybe = null;

// Unwrap with orelse (provide default)
const val = maybe orelse 0;

// Unwrap with if
if (maybe) |value| {
    std.debug.print("Got: {}\n", .{value});
} else {
    std.debug.print("Was null\n", .{});
}

// Unwrap or unreachable (crash if null)
const certain = maybe.?;  // equivalent to `orelse unreachable`

// Optional pointers are pointer-sized (null = 0x0)
var ptr: ?*u32 = null;    // same size as *u32

Error Unions

Error unions combine a return value with a possible error. Written as ErrorSet!ReturnType.

// Error set declaration
const FileError = error {
    FileNotFound,
    PermissionDenied,
    OutOfMemory,
};

// Function returning error union
fn readConfig(path: []const u8) FileError!Config {
    const file = std.fs.cwd().openFile(path, .{}) catch {
        return error.FileNotFound;
    };
    defer file.close();
    // ...
}

// anyerror captures any error type
fn doSomething() anyerror!void { ... }

Compile-Time Evaluation

// comptime forces evaluation at compile time
const len = comptime blk: {
    var n: u32 = 1;
    inline for (0..10) |_| {
        n *= 2;
    }
    break :blk n;  // len = 1024 at compile time
};

// comptime parameters: evaluated at compile time
fn pow(comptime T: type, base: T, exp: T) T {
    var result: T = 1;
    var i: T = 0;
    while (i < exp) : (i += 1) {
        result *= base;
    }
    return result;
}

// Usage — the type is a comptime parameter
const result = pow(u32, 2, 10);  // 1024

Generics via Comptime

Zig has no generics syntax. Instead, pass type as a comptime parameter. This is simpler and more powerful than parametric polymorphism.

// Generic linked list
fn LinkedList(comptime T: type) type {
    return struct {
        const Self = @This();

        const Node = struct {
            data: T,
            next: ?*Node,
        };

        head: ?*Node,
        len: usize,

        pub fn init() Self {
            return .{ .head = null, .len = 0 };
        }

        pub fn push(self: *Self, allocator: std.mem.Allocator, data: T) !void {
            const node = try allocator.create(Node);
            node.* = .{ .data = data, .next = self.head };
            self.head = node;
            self.len += 1;
        }
    };
}

// Usage
var list = LinkedList(i32).init();
try list.push(allocator, 42);

Compile-Time Reflection

// @typeInfo gives you full type metadata at comptime
fn dumpFields(comptime T: type) void {
    const info = @typeInfo(T);
    switch (info) {
        .@"struct" => |s| {
            inline for (s.fields) |field| {
                @compileLog(field.name, field.type);
            }
        },
        else => @compileError("Expected struct"),
    }
}

// @typeName, @sizeOf, @alignOf are all comptime
const name = @typeName(u32);       // "u32"
const size = @sizeOf(Point);       // 16 (two f64s)
const align = @alignOf(Point);     // 8

Allocators

Zig does not have a default allocator. Functions that need heap memory accept an std.mem.Allocator parameter, making allocation strategy explicit and swappable.

// General purpose allocator with leak detection
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer {
    const check = gpa.deinit();
    if (check == .leak) @panic("Memory leak detected!");
}
const allocator = gpa.allocator();

// Arena allocator — bulk free everything at once
var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
defer arena.deinit();
const arena_alloc = arena.allocator();

// Allocate a slice
const buf = try allocator.alloc(u8, 1024);
defer allocator.free(buf);

defer & errdefer

defer runs cleanup at scope exit. errdefer runs only if the function returns an error. Together they replace RAII destructors and try/finally.

fn createResource(allocator: std.mem.Allocator) !*Resource {
    const ptr = try allocator.create(Resource);
    errdefer allocator.destroy(ptr);  // only runs if we return error

    ptr.* = try Resource.init();      // if this fails, ptr is freed
    return ptr;                        // success: caller owns ptr
}

// Multiple defers execute in reverse order (LIFO)
fn example() void {
    const a = acquire_a();
    defer release_a(a);     // runs third

    const b = acquire_b();
    defer release_b(b);     // runs second

    const c = acquire_c();
    defer release_c(c);     // runs first
}

Stack vs Heap

Arrays

// Fixed-size array (lives on the stack)
const arr: [5]u8 = .{ 1, 2, 3, 4, 5 };

// Comptime-known length via init syntax
const zeros = [_]u8{0} ** 256;  // 256 zero bytes

// Array concatenation (comptime only)
const a = [_]u8{ 1, 2 };
const b = [_]u8{ 3, 4 };
const c = a ++ b;  // [4]u8{ 1, 2, 3, 4 }

// Multi-dimensional arrays
const matrix: [3][3]f32 = .{
    .{ 1, 0, 0 },
    .{ 0, 1, 0 },
    .{ 0, 0, 1 },
};

Slices

A slice is a pointer + length pair. It is the idiomatic way to pass sequences of data around.

// Slice from array
const arr = [_]u8{ 10, 20, 30, 40, 50 };
const slice: []const u8 = arr[1..4];  // { 20, 30, 40 }

// Mutable slice
var data = [_]u8{ 0, 0, 0 };
var mutable_slice: []u8 = &data;
mutable_slice[0] = 42;

// Slice from heap allocation
const heap_buf = try allocator.alloc(u8, 1024);
defer allocator.free(heap_buf);

// String literals are slices
const greeting: []const u8 = "Hello, Zig!";

// Iterate over a slice
for (slice, 0..) |byte, i| {
    std.debug.print("[{}] = {}\n", .{ i, byte });
}

Sentinel-Terminated Types

Sentinel types end with a known value (typically 0). This is how Zig interoperates with C strings and null-terminated arrays.

// Null-terminated string (C compatible)
const c_str: [*:0]const u8 = "hello";

// Sentinel-terminated slice
const msg: [:0]const u8 = "world";

// Convert between types
const slice: []const u8 = std.mem.span(c_str);

// Sentinel-terminated arrays
const arr: [3:0]u8 = .{ 1, 2, 3 };  // followed by 0

Pointer Types at a Glance

try, catch & Error Propagation

// `try` unwraps or returns the error to the caller
fn readFile(path: []const u8) ![]u8 {
    const file = try std.fs.cwd().openFile(path, .{});
    defer file.close();
    return try file.readToEndAlloc(allocator, 1024 * 1024);
}

// `catch` handles the error inline
const content = readFile("config.txt") catch |err| {
    std.log.err("Failed: {}", .{err});
    return;
};

// `catch` with a default value
const port = parsePort(env_var) catch 8080;

// Switch on specific errors
const result = doWork() catch |err| switch (err) {
    error.OutOfMemory => @panic("OOM"),
    error.Timeout => return error.Timeout,
    else => return err,
};

Error Sets

// Named error sets
const ParseError = error {
    InvalidCharacter,
    Overflow,
    EndOfStream,
};

// Error sets can be merged
const AllErrors = ParseError || FileError;

// Inferred error sets (let the compiler figure it out)
fn process() !void {       // `!` with no explicit set
    try step1();
    try step2();              // compiler merges all possible errors
}

// Error return traces (debug builds)
// Zig automatically tracks where errors originated
// — stack traces for errors, not just panics

Error Handling Patterns

@cImport

// Import C headers directly — no bindings generator needed
const c = @cImport({
    @cInclude("stdio.h");
    @cInclude("stdlib.h");
    @cInclude("math.h");
});

pub fn main() void {
    // Call C functions directly
    _ = c.printf("Hello from C! sqrt(2) = %f\n", c.sqrt(2.0));

    // Use C's malloc (but prefer Zig allocators)
    const ptr = c.malloc(100);
    defer c.free(ptr);
}

Linking C Libraries

// In build.zig — link against system libraries
const exe = b.addExecutable(.{
    .name = "my-app",
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
});

// Link system C library
exe.linkLibC();

// Link a specific system library (e.g., SDL2)
exe.linkSystemLibrary("SDL2");

// Or compile C source files as part of the build
exe.addCSourceFiles(.{
    .files = &.{ "vendor/sqlite3.c" },
    .flags = &.{ "-DSQLITE_THREADSAFE=0" },
});
exe.addIncludePath(b.path("vendor/"));

Zig as a C/C++ Compiler

Zig bundles a C and C++ compiler. You can use zig cc as a drop-in replacement for gcc or clang, with built-in cross-compilation.

# Compile C code with zig
zig cc -o hello hello.c

# Cross-compile C for ARM
zig cc -target aarch64-linux-gnu hello.c -o hello-arm

# Use as CC in Makefiles or CMake
CC="zig cc" make
CMAKE_C_COMPILER="zig cc" cmake ..

# Compile C++ with zig
zig c++ -o app main.cpp -lstdc++

Type Compatibility

build.zig Anatomy

const std = @import("std");

pub fn build(b: *std.Build) void {
    // Target and optimization from command line
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Main executable
    const exe = b.addExecutable(.{
        .name = "my-app",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Install artifact to zig-out/bin/
    b.installArtifact(exe);

    // Run step: `zig build run`
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());

    // Forward CLI args: `zig build run -- arg1 arg2`
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }

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

    // Test step: `zig build test`
    const tests = b.addTest(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    const run_tests = b.addRunArtifact(tests);
    const test_step = b.step("test", "Run unit tests");
    test_step.dependOn(&run_tests.step);
}

build.zig.zon (Dependencies)

// build.zig.zon — declarative package manifest
.{
    .name = "my-project",
    .version = "0.1.0",
    .minimum_zig_version = "0.13.0",
    .dependencies = .{
        .@"zig-clap" = .{
            .url = "https://github.com/Hejsil/zig-clap/archive/v0.4.0.tar.gz",
            .hash = "1220abcdef...",
        },
        .@"zap" = .{
            .url = "https://github.com/zigzap/zap/archive/v0.8.0.tar.gz",
            .hash = "1220fedcba...",
        },
    },
    .paths = .{ "src", "build.zig", "build.zig.zon" },
}

// Then in build.zig, import the dependency:
const clap_dep = b.dependency("zig-clap", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("clap", clap_dep.module("clap"));

Build Commands

Writing Tests

const std = @import("std");
const expect = std.testing.expect;
const expectEqual = std.testing.expectEqual;

// Tests live alongside production code
fn add(a: i32, b: i32) i32 {
    return a + b;
}

test "basic addition" {
    try expectEqual(@as(i32, 4), add(2, 2));
}

test "negative numbers" {
    try expectEqual(@as(i32, 0), add(-1, 1));
}

test "overflow detection" {
    // In Debug mode, overflow is a detectable illegal behavior
    const result = @addWithOverflow(@as(u8, 250), 10);
    try expect(result[1] == 1);  // overflow flag is set
}

// Test with allocator (catches memory leaks)
test "allocator usage" {
    const allocator = std.testing.allocator;
    const list = try allocator.alloc(u8, 10);
    defer allocator.free(list);  // test fails if this is missing!
    try expect(list.len == 10);
}

Test Assertions

Debugging

// Print debug info (removed in release builds)
std.debug.print("x = {}, y = {}\n", .{ x, y });

// Log with severity levels
std.log.info("Starting up...", .{});
std.log.warn("Config missing, using defaults", .{});
std.log.err("Failed to open: {}", .{err});

// Stack traces on panic (debug builds)
@panic("something went wrong");

// Breakpoint for debugger attachment
@breakpoint();

// GDB/LLDB work out of the box with debug builds
// $ gdb ./zig-out/bin/my-app
// (gdb) break src/main.zig:42
// (gdb) run

Running Tests

Replacing C

Zig is designed as a practical successor to C. It interoperates seamlessly with C code, compiles C sources, and can be incrementally adopted in existing C projects.

Game Engines & Graphics

Zig's deterministic performance, manual memory control, and comptime make it attractive for game development.

Embedded & Systems Programming

// Zig can target bare-metal platforms
// No OS, no stdlib, no allocator

// Freestanding target in build.zig
const exe = b.addExecutable(.{
    .name = "firmware",
    .root_source_file = b.path("src/main.zig"),
    .target = b.resolveTargetQuery(.{
        .cpu_arch = .thumb,
        .os_tag = .freestanding,
        .abi = .eabi,
    }),
});

// Specify linker script for memory layout
exe.setLinkerScript(b.path("linker.ld"));

// MMIO register access (comptime-known addresses)
const GPIOA = @as(*volatile u32, @ptrFromInt(0x40020000));
GPIOA.* = 0x01;  // set pin 0 high

Notable Projects Using Zig