Zig Book

https://www.zigbook.net/chapters/
Admin
Zig Book is a comprehensive guide and documentation for the Zig programming language, covering...
Tokens:246,909
Snippets:683
Trust Score:6.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Minimal Zig Executable Build Script

Source: https://www.zigbook.net/chapters/22__build-system-deep-dive

A basic `build.zig` file that creates a single executable named 'hello' from 'main.zig'. It configures the compilation target to the host machine and sets the optimization level to Debug. The executable is then registered for installation into the output directory. This serves as the foundational example for Zig build scripts.

```zig
const std = @import("std");

// Minimal build.zig: single executable, no options
// Demonstrates the simplest possible build script for the Zig build system.
pub fn build(b: *std.Build) void {
    // Create an executable compilation step with minimal configuration.
    // This represents the fundamental pattern for producing a binary artifact.
    const exe = b.addExecutable(.{
        // The output binary name (becomes "hello" or "hello.exe")
        .name = "hello",
        // Configure the root module with source file and compilation settings
        .root_module = b.createModule(.{
            // Specify the entry point source file relative to build.zig
            .root_source_file = b.path("main.zig"),
            // Target the host machine (the system running the build)
            .target = b.graph.host,
            // Use Debug optimization level (no optimizations, debug symbols included)
            .optimize = .Debug,
        }),
    });
    
    // Register the executable to be installed to the output directory.
    // When `zig build` runs, this artifact will be copied to zig-out/bin/
    b.installArtifact(exe);
}

```

--------------------------------

### Zig Main Function Setup

Source: https://www.zigbook.net/chapters/30__project-parallel-wordcount

Initializes the general purpose allocator and sets up buffered stdout for efficient printing. This is the entry point for the main execution of the program.

```zig
const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Set up buffered stdout for efficient printing
    var stdout_buf: [1024]u8 = undefined;
    var stdout_state = std.fs.File.stdout().writer(&stdout_buf);

```

--------------------------------

### Zig's Compile-Time Entry Point Logic Example

Source: https://www.zigbook.net/chapters/19__modules-and-imports-root-builtin-discovery

Illustrates how Zig's `std.start` uses compile-time information like `output_mode`, `os`, `link_libc`, and target architecture to determine the exported symbol. This example shows a basic structure for defining a custom entry point.

```zig
// Example of custom entry point wiring, often found in linux.zig
const std = @import("std");

pub export fn _start() noreturn {
    // Initialize stdio, etc.
    main();
}

fn main() {
    // Your application logic
    std.debug.print("Hello, world!\n", .{});
}
```

--------------------------------

### Run Zig 'While' Loop Example

Source: https://www.zigbook.net/chapters/00__zigbook_introduction

Executes the Zig program demonstrating the `while` loop. This command compiles and runs the `squares_demo.zig` file, showing the output of calculated squares.

```shell
zig run squares_demo.zig
```

--------------------------------

### Build and Run Zig AllocPrint Example

Source: https://www.zigbook.net/chapters/45__text-formatting-and-unicode

Instructions to compile and execute the Zig code that demonstrates dynamic string formatting with `std.fmt.allocPrint`. This involves creating an executable and then running it from the shell.

```shell
$ zig build-exe allocprint.zig && ./allocprint

```

--------------------------------

### Build and Run Example with Flags

Source: https://www.zigbook.net/chapters/22__build-system-deep-dive

Provides the command to build and run a Zig program with specific target and optimization flags. This demonstrates the practical application of `standardTargetOptions` and `standardOptimizeOption`.

```shell
$ zig build -Dtarget=x86_64-linux -Doptimize=ReleaseFast run
```

--------------------------------

### Zig Program Output Example

Source: https://www.zigbook.net/chapters/01__boot-basics

Shows the expected output when the Zig program is executed. This includes the application name, optimization mode, and target information as printed by the `main` function.

```shell
app: Boot Basics Tour
optimize mode: Debug
target: x86_64-linux-gnu

```

--------------------------------

### Main Function Setup in Zig

Source: https://www.zigbook.net/chapters/54__project-zip-unzip-with-progress

This is the main entry point of the program, setting up essential components like the general-purpose allocator and standard output writer. It initializes a temporary directory for testing and a string hash map for metrics, ensuring proper cleanup of resources using `defer`. The `Progress` object is also initialized to track the overall progress of operations. Dependencies include standard Zig heap, testing, and progress utilities. The primary purpose is to establish a clean and controlled environment for subsequent operations.

```zig
pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer {
        const leak_status = gpa.deinit();
        std.debug.assert(leak_status == .ok);
    }
    const allocator = gpa.allocator();

    var stdout_buffer: [512]u8 = undefined;
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    const out = &stdout_writer.interface;

    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    var metrics = std.StringHashMap(EntryMetrics).init(allocator);
    defer {
        var it = metrics.iterator();
        while (it.next()) |kv| {
            allocator.free(kv.key_ptr.*);
        }
        metrics.deinit();
    }

    var progress_root = std.Progress.start(.{
        .root_name = "zip-pipeline",
        .estimated_total_items = 3,
        .disable_printing = true,
    });
}

```

--------------------------------

### Verify Zig Installation

Source: https://www.zigbook.net/chapters/00__zigbook_introduction

This command verifies that the Zig toolchain has been correctly installed and is accessible in the system's PATH. It's a crucial first step to ensure compatibility with Zig examples.

```shell
zig version
```

--------------------------------

### Zig Testing: Test Execution Output

Source: https://www.zigbook.net/chapters/55__style-guide-highlights

Example output from running Zig tests, confirming that all defined tests within the module have passed.

```shell
All 2 tests passed.
```

--------------------------------

### Zig Modules and Imports: Basic Setup

Source: https://www.zigbook.net/chapters/01__boot-basics

This Zig code demonstrates importing modules for standard library, built-in functions, and the root module. It defines a public constant `app_name` and a `main` function that prints application information including the name, optimization mode, and target triple.

```zig
// File: chapters-data/code/01__boot-basics/imports.zig

// Import the standard library for I/O, memory management, and core utilities
const std = @import("std");
// Import builtin to access compile-time information about the build environment
const builtin = @import("builtin");
// Import root to access declarations from the root source file
// In this case, we reference app_name which is defined in this file
const root = @import("root");

// Public constant that can be accessed by other modules importing this file
pub const app_name = "Boot Basics Tour";

// Main entry point of the program
// Returns an error union to propagate any I/O errors during execution
pub fn main() !void {
    // Allocate a fixed-size buffer on the stack for stdout operations
    // This buffer batches write operations to reduce syscalls
    var stdout_buffer: [256]u8 = undefined;
    // Create a buffered writer wrapping stdout
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    // Get the generic writer interface for polymorphic I/O operations
    const stdout = &stdout_writer.interface;

    // Print the application name by referencing the root module's declaration
    // Demonstrates how @import("root") allows access to the entry file's public declarations
    try stdout.print("app: {s}\n", .{root.app_name});
    
    // Print the optimization mode (Debug, ReleaseSafe, ReleaseFast, or ReleaseSmall)
    // @tagName converts the enum value to its string representation
    try stdout.print("optimize mode: {s}\n", .{@tagName(builtin.mode)});
    
    // Print the target triple showing CPU architecture, OS, and ABI
    // Each component is extracted from builtin.target and converted to a string
    try stdout.print(
        "target: {s}-{s}-{s}\n",
        ,{
            @tagName(builtin.target.cpu.arch),
            @tagName(builtin.target.os.tag),
            @tagName(builtin.target.abi),
        },
    );
    
    // Flush the buffer to ensure all accumulated output is written to stdout
    try stdout.flush();
}

```

--------------------------------

### Main Function: HTTP Client and Server Setup (Zig)

Source: https://www.zigbook.net/chapters/32__project-http-json-client

Sets up a general-purpose allocator, binds an HTTP server to localhost, and spins it up on a background thread. It then initializes an HTTP client, creates an arena allocator for parsed data, and constructs the URL to fetch status information. Finally, it calls functions to fetch and render the summary. Dependencies include Zig's standard library for networking, threading, memory management, and HTTP.

```zig
pub fn main() !void {
    // Set up a general-purpose allocator for long-lived allocations (client, server).
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Bind to localhost on an OS-assigned port (port 0 → automatic selection).
    const address = try std.net.Address.parseIp("127.0.0.1", 0);
    var server = try address.listen(.{ .reuse_address = true });
    defer server.deinit();

    // Spin up the server fixture on a background thread.
    var ready = std.Thread.ResetEvent{};
    const server_thread = try std.Thread.spawn(.{}, serveStatus, .{ServerTask{
        .server = &server,
        .ready = &ready,
    }});
    defer server_thread.join();

    // Wait for the server thread to signal that it's ready to accept connections.
    ready.wait();

    // Retrieve the actual port chosen by the OS.
    const port = server.listen_address.in.getPort();

    // Initialize the HTTP client with the main allocator.
    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    // Create an arena allocator for all parsed data.
    // The arena owns all slices in the Summary; they're freed when the arena is destroyed.
    var arena_inst = std.heap.ArenaAllocator.init(allocator);
    defer arena_inst.deinit();
    const arena = arena_inst.allocator();

    // Set up buffered stdout for logging.
    var stdout_buffer: [256]u8 = undefined;
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    const log_out = &stdout_writer.interface;

    // Construct the full URL with the dynamically assigned port.
    var url_buffer: [128]u8 = undefined;
    const url = try std.fmt.bufPrint(&url_buffer, "http://127.0.0.1:{d}/api/status", .{port});
    try log_out.print("Fetching {s}...\n", .{url});

    // Fetch and decode the status endpoint.
    const summary = try fetchSummary(arena, &client, url);
    try log_out.print("Parsed {d} regions.\n\n", .{summary.regions.len});
    try log_out.flush();

    // Render the final report to stdout.
    try renderSummary(summary);
}

```

--------------------------------

### Basic std.Progress Usage in Zig

Source: https://www.zigbook.net/chapters/47__time-logging-and-progress

Demonstrates the basic usage of `std.Progress` to report progress on a series of tasks. It shows how to start a root task, add child tasks, complete individual steps, and end tasks. The `disable_printing` option is used for deterministic output in this example.

```zig
const std = @import("std");

pub fn main() void {
    // Progress can draw to stderr; disable printing in this demo for deterministic output.
    const root = std.Progress.start(.{ .root_name = "build", .estimated_total_items = 3, .disable_printing = true });
    var compile = root.start("compile", 2);
    compile.completeOne();
    compile.completeOne();
    compile.end();

    var link = root.start("link", 1);
    link.completeOne();
    link.end();

    root.end();
}

```

--------------------------------

### Zig Demo: Registering and Displaying Package Details

Source: https://www.zigbook.net/chapters/20__concept-primer-modules-vs-programs-vs-packages-vs-libraries

This Zig code demonstrates how to register a module using the `--dep` and `-M` flags and then import and utilize it. It defines a `main` function that populates package details (name, role, optimization mode, target OS) and renders a summary to standard output using a separate library (`overlay`). Dependencies include the standard library (`std`) and the `builtin` module for compile-time information.

```zig
const std = @import("std");
const builtin = @import("builtin");
const overlay = @import("overlay");

/// Entry point for the package overlay demonstration program.
/// Demonstrates how to use the overlay_widget library to display package information
/// including build mode and target operating system details.
pub fn main() !void {
    // Allocate a fixed-size buffer on the stack for stdout operations
    // This avoids heap allocation for simple output scenarios
    var stdout_buffer: [512]u8 = undefined;
    // Create a buffered writer for stdout to improve performance by batching writes
    var file_writer = std.fs.File.stdout().writer(&stdout_buffer);
    const stdout = &file_writer.interface;

    // Populate package details structure with information about the current package
    // This includes compile-time information like optimization mode and target OS
    const details = overlay.PackageDetails{
        .package_name = "overlay",
        .role = "library package",
        // Extract the optimization mode name (e.g., Debug, ReleaseFast) at compile time
        .optimize_mode = @tagName(builtin.mode),
        // Extract the target OS name (e.g., linux, windows) at compile time
        .target_os = @tagName(builtin.target.os.tag),
    };

    // Render the package summary to stdout using the overlay library
    try overlay.renderSummary(stdout, details);
    // Ensure all buffered output is written to the terminal
    try stdout.flush();
}

```

--------------------------------

### Shell Command: Building and Running Zig Package Demo

Source: https://www.zigbook.net/chapters/20__concept-primer-modules-vs-programs-vs-packages-vs-libraries

This shell command demonstrates how to compile a Zig executable (`overlay_demo`) using the new `-M` and `--dep` flags. It specifies the main entry point (`-Mroot`), the dependency module (`-Moverlay`), and the output format and name. After successful compilation, it executes the generated program.

```shell
$ zig build-exe --dep overlay -Mroot=package_overlay_demo.zig -Moverlay=overlay_widget.zig -femit-bin=overlay_demo && ./overlay_demo

```

--------------------------------

### Zig Module Layout: Retry Policy Example

Source: https://www.zigbook.net/chapters/55__style-guide-highlights

Demonstrates a layered Zig module structure for a retry policy. It includes public types (RetryPolicyError, RetryPolicy, PartialRetryOptions), a factory function (makeRetryPolicy), a private validation function, and public API (finalizeRetryPolicy) along with colocated tests. This structure aids in organizing code and provides executable documentation.

```zig
//! Highlights a layered module layout with focused helper functions and tests.
const std = @import("std");

/// Errors that can emerge while normalizing user-provided retry policies.
pub const RetryPolicyError = error{
    ZeroAttempts,
    ExcessiveDelay,
};

/// Encapsulates retry behaviour for a network client, including sensible defaults.
pub const RetryPolicy = struct {
    max_attempts: u8 = 3,
    delay_ms: u32 = 100,

    /// Indicates whether exponential backoff is active.
    pub fn isBackoffEnabled(self: RetryPolicy) bool {
        return self.delay_ms > 0 and self.max_attempts > 1;
    }
};

/// Partial options provided by configuration files or CLI flags.
pub const PartialRetryOptions = struct {
    max_attempts: ?u8 = null,
    delay_ms: ?u32 = null,
};

/// Builds a retry policy from optional overrides while keeping default reasoning centralized.
pub fn makeRetryPolicy(options: PartialRetryOptions) RetryPolicy {
    return RetryPolicy{
        .max_attempts = options.max_attempts orelse 3,
        .delay_ms = options.delay_ms orelse 100,
    };
}

fn validate(policy: RetryPolicy) RetryPolicyError!RetryPolicy {
    if (policy.max_attempts == 0) return RetryPolicyError.ZeroAttempts;
    if (policy.delay_ms > 60_000) return RetryPolicyError.ExcessiveDelay;
    return policy;
}

/// Produces a validated policy, emphasising the flow from raw input to constrained output.
pub fn finalizeRetryPolicy(options: PartialRetryOptions) RetryPolicyError!RetryPolicy {
    const policy = makeRetryPolicy(options);
    return validate(policy);
}

test "finalize rejects zero attempts" {
    try std.testing.expectError(
        RetryPolicyError.ZeroAttempts,
        finalizeRetryPolicy(.{ .max_attempts = 0 }),
    );
}

test "finalize accepts defaults" {
    const policy = try finalizeRetryPolicy(.{});
    try std.testing.expectEqual(@as(u8, 3), policy.max_attempts);
    try std.testing.expect(policy.isBackoffEnabled());
}

```

--------------------------------

### Shell Command: Zig Compiler Bootstrap Example

Source: https://www.zigbook.net/chapters/20__concept-primer-modules-vs-programs-vs-packages-vs-libraries

This shell command illustrates how the Zig compiler itself is built using the `-M`/`--dep` system during its bootstrap process (`zig1` to `zig2`). It defines multiple dependencies (`--dep build_options`, `--dep aro`) and maps them to specific module entry points (`-Mroot`, `-Mbuild_options`, `-Maro`), outputting C code (`-ofmt=c`) for the next stage of the build.

```shell
zig1 <lib-dir> build-exe -ofmt=c -lc -OReleaseSmall \
  --name zig2 \
  -femit-bin=zig2.c \
  -target <host-triple> \
  --dep build_options \
  --dep aro \
  -Mroot=src/main.zig \
  -Mbuild_options=config.zig \
  -Maro=lib/compiler/aro/aro.zig

```

--------------------------------

### Set Install Prefix and Library Directory in Zig

Source: https://www.zigbook.net/chapters/26__build-system-advanced-topics

Configures the installation directory for build artifacts in Zig. `b.setInstallPrefix` and `b.setLibDir` are used to route outputs to specific locations, which is useful for managing large workspaces and avoiding default directory limits.

```zig
const std = @import("std");

fn setupBuildPaths (b: *std.Build) void {
    // Example: Set a custom install prefix
    b.setInstallPrefix("/path/to/custom/install");

    // Example: Set a custom library directory
    b.setLibDir("lib/my_library");

    // ... add artifacts after setting paths ...
    // const exe = b.addExecutable(...);
    // b.installArtifact(exe);
}

```

--------------------------------

### Zig: Example Error Messages

Source: https://www.zigbook.net/chapters/12__config-as-data

This snippet shows example error messages formatted according to Zig's standards for reporting configuration validation failures. The format includes file location, severity (error/note), and a descriptive message, aiding in parsing and IDE integration.

```shell
config.toml:12:8: error: port must be between 1024 and 65535
config.toml:15:1: error: TLS enabled but cert_file not specified
config.toml:15:1: note: set cert_file and key_file when tls = true

```

--------------------------------

### Minimal Zig Program Entry Point

Source: https://www.zigbook.net/chapters/22__build-system-deep-dive

The `main.zig` file for a minimal Zig build example. It imports the standard library and defines the `main` function, which prints a simple greeting to the console. This serves as the entry point for the executable built by the `build.zig` script.

```zig
// Entry point for a minimal Zig build system example.
// This demonstrates the simplest possible Zig program structure that can be built
// using the Zig build system, showing the basic main function and standard library import.
const std = @import("std");

pub fn main() !void {
    std.debug.print("Hello from minimal build!\n", .{});
}

```

--------------------------------

### Zig Build Output Example

Source: https://www.zigbook.net/chapters/27__project-multi-package-workspace-and-vendor

This output sample demonstrates the results of running the Zig build executable. It displays performance metrics for different datasets, including status, mean, range, and sample counts, as generated by the 'workspace-dashboard' application.

```shell
dataset      status    mean       range      samples
------------------------------------------------------
frontend     stable    111.80     3.90       5
checkout     stable    100.60     6.40       5
analytics    alert     77.42      24.00      5

```

--------------------------------

### Zig: Demonstrate Dependency Types

Source: https://www.zigbook.net/chapters/21__zig-init-and-package-metadata

This Zig code demonstrates how to define and compare different dependency specification patterns: remote with URL and hash, local with a file path, and a lazy remote dependency. It iterates through these definitions and prints their properties, highlighting the differences in how they are fetched and managed.

```Zig
const std = @import("std");

pub fn main() !void {
    std.debug.print("--- Dependency Types Comparison ---\\n\\n", .{}); 

    // Demonstrate different dependency specification patterns
    const deps = [_]Dependency{
        .{ 
            .name = "remote_package",
            .kind = .{ .remote = .{ 
                .url = "https://example.com/pkg.tar.gz",
                .hash = "122012345678...", 
            } },
            .lazy = false,
        },
        .{ 
            .name = "local_package",
            .kind = .{ .local = .{ 
                .path = "../local-lib",
            } },
            .lazy = false,
        },
        .{ 
            .name = "lazy_optional",
            .kind = .{ .remote = .{ 
                .url = "https://example.com/opt.tar.gz",
                .hash = "1220abcdef...", 
            } },
            .lazy = true,
        },
    };

    for (deps, 0..) |dep, i| {
        std.debug.print("Dependency {d}: {s}\\n", .{ i + 1, dep.name });
        std.debug.print("  Type: {s}\\n", .{@tagName(dep.kind)});
        std.debug.print("  Lazy: {s}\\n", .{dep.lazy});

        switch (dep.kind) {
            .remote => |r| {
                std.debug.print("  URL: {s}\\n", .{r.url});
                std.debug.print("  Hash: {s}\\n", .{r.hash});
                std.debug.print("  (Fetched from network, cached locally)\\n", .{});
            },
            .local => |l| {
                std.debug.print("  Path: {s}\\n", .{l.path});
                std.debug.print("  (No hash needed, relative to build root)\\n", .{});
            },
        }
        std.debug.print("\\n", .{});
    }

    std.debug.print("Key differences:\\n", .{});
    std.debug.print("  - Remote: Uses hash as source of truth\\n", .{});
    std.debug.print("  - Local: Direct filesystem path\\n", .{});
    std.debug.print("  - Lazy: Only fetched when actually imported\\n", .{});
}

const Dependency = struct {
    name: []const u8,
    kind: union(enum) {
        remote: struct {
            url: []const u8,
            hash: []const u8,
        },
        local: struct {
            path: []const u8,
        },
    },
    lazy: bool,
};

```

--------------------------------

### Perform HTTP GET Request and Parse JSON Response

Source: https://www.zigbook.net/chapters/31__networking-http-and-json

This snippet shows how to make an HTTP GET request using Zig's `std.net.http.Client.fetch`. It configures a fixed-size buffer for the response body and custom headers. The response is then parsed into a predefined struct using `std.json.parseFromSlice`. Finally, it prints specific fields from the parsed JSON.

```zig
const std = @import("std");

// Assume 'client' is an initialized http.Client and 'allocator' is a valid Allocator.
// Assume 'url' is the target URL string.

// Allocate buffer to receive the HTTP response body
var response_buffer: [512]u8 = undefined;
// Create a fixed-size writer that will capture the response
var response_writer = std.io.Writer.fixed(response_buffer[0..]);

// Perform the HTTP GET request with custom User-Agent header
const fetch_result = try client.fetch(.{
    .location = .{ .url = url },
    .response_writer = &response_writer, // Where to write response body
    .headers = .{
        .user_agent = .{ .override = "zigbook-demo/0.15.2" },
    },
});

// Get the slice containing the actual response body bytes
const body = std.io.Writer.buffered(&response_writer);

// Define the expected structure of the JSON response
const ResponseShape = struct {
    service: []const u8,
    message: []const u8,
    method: []const u8,
    path: []const u8,
    sequence: u32,
};

// Parse the JSON response into a typed struct
var parsed = try std.json.parseFromSlice(ResponseShape, allocator, body, .{});
// Free the memory allocated during JSON parsing
defer parsed.deinit();

// Set up a buffered writer for stdout to efficiently output results
var stdout_storage: [256]u8 = undefined;
var stdout_state = std.fs.File.stdout().writer(&stdout_storage);
const out = &stdout_state.interface;
// Display the HTTP response status code
try out.print("status: {d}\n", .{@intFromEnum(fetch_result.status)});
// Display the parsed JSON fields
try out.print("service: {s}\n", .{parsed.value.service});
try out.print("method: {s}\n", .{parsed.value.method});
try out.print("path: {s}\n", .{parsed.value.path});
try out.print("message: {s}\n", .{parsed.value.message});
// Ensure all output is visible before program exits
try out.flush();

```

--------------------------------

### Complete Zig Build Example with Standard Options

Source: https://www.zigbook.net/chapters/22__build-system-deep-dive

Demonstrates a complete `build.zig` file using `standardTargetOptions` and `standardOptimizeOption` to configure an executable. This allows users to specify target and optimization via command-line flags.

```zig
const std = @import("std");

// Demonstrating standardTargetOptions and standardOptimizeOption
pub fn build(b: *std.Build) void {
    // Allows user to choose target: zig build -Dtarget=x86_64-linux
    const target = b.standardTargetOptions(.{});
    
    // Allows user to choose optimization: zig build -Doptimize=ReleaseFast
    const optimize = b.standardOptimizeOption(.{});
    
    const exe = b.addExecutable(.{
        .name = "configurable",
        .root_module = b.createModule(.{
            .root_source_file = b.path("main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    
    b.installArtifact(exe);
    
    // Add run step
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    
    const run_step = b.step("run", "Run the application");
    run_step.dependOn(&run_cmd.step);
}
```

--------------------------------

### Zig Dependency Resolution Pipeline Example

Source: https://www.zigbook.net/chapters/24__zig-package-manager-deep

This Zig code demonstrates the logical steps involved in resolving project dependencies. It covers parsing the build configuration, handling eager and lazy dependencies, and showing where cached dependencies are stored. This example is useful for understanding the internals of Zig's package management.

```Zig
// Conceptual example showing the dependency resolution pipeline
const std = @import("std");

const DependencyState = enum {
    declared, // Listed in build.zig.zon
    downloading, // URL being fetched
    verifying, // Hash being checked
    cached, // Stored in global cache
    available, // Ready for use
};

const Dependency = struct {
    name: []const u8,
    url: ?[]const u8,
    path: ?[]const u8,
    hash: ?[]const u8,
    lazy: bool,
    state: DependencyState,
};

pub fn main() !void {
    std.debug.print("--- Zig Package Manager Resolution Pipeline ---\\n\\n", .{
    });

    // Stage 1: Parse build.zig.zon
    std.debug.print("1. Parse build.zig.zon dependencies\\n", .{
    });
    var deps = [_]Dependency{
        .{ .name = "core", .path = "../core", .url = null, .hash = null, .lazy = false, .state = .declared },
        .{ .name = "utils", .url = "https://example.com/utils.tar.gz", .path = null, .hash = "1220abcd...", .lazy = false, .state = .declared },
        .{ .name = "optional_viz", .url = "https://example.com/viz.tar.gz", .path = null, .hash = "1220ef01...", .lazy = true, .state = .declared },
    };

    // Stage 2: Resolve eager dependencies
    std.debug.print("\\n2. Resolve eager dependencies\\n", .{
    });
    for (&deps) |*dep|
 {
        if (!dep.lazy) {
            std.debug.print("   - {s}: ", .{
                dep.name,
            });
            if (dep.path) |p|
 {
                std.debug.print("local path '{s}' → available\\n", .{
                    p,
                });
                dep.state = .available;
            } else if (dep.url) |_|
 {
                std.debug.print("fetching → verifying → cached → available\\n", .{
                });
                dep.state = .available;
            }
        }
    }

    // Stage 3: Lazy dependencies deferred
    std.debug.print("\\n3. Lazy dependencies (deferred until used)\\n", .{
    });
    for (deps) |dep|
 {
        if (dep.lazy)
 {
            std.debug.print("   - {s}: waiting for lazyDependency() call\\n", .{
                dep.name,
            });
        }
    }

    // Stage 4: Build script execution triggers lazy fetch
    std.debug.print("\\n4. Build script requests lazy dependency\\n", .{
    });
    std.debug.print("   - optional_viz requested → fetching now\\n", .{
    });

    // Stage 5: Cache lookup
    std.debug.print("\\n5. Cache locations\\n", .{
    });
    std.debug.print("   - Global: ~/.cache/zig/p/<hash>/\\n", .{
    });
    std.debug.print("   - Project: .zig-cache/\\n", .{
    });

    std.debug.print("\\n=== Resolution Complete ===\\n", .{
    });
}

```

--------------------------------

### Zig ZON Field Introspection Example

Source: https://www.zigbook.net/chapters/21__zig-init-and-package-metadata

Demonstrates parsing and introspecting fields within a `build.zig.zon` structure using Zig code. This example showcases how to represent and print information about fields like `.name`, `.version`, `.minimum_zig_version`, `.fingerprint`, `.paths`, and `.dependencies`. Note that in practice, the build runner handles this introspection automatically.

```zig
const std = @import("std");

pub fn main() !void {
    // Demonstrate parsing and introspecting build.zig.zon fields
    // In practice, the build runner handles this automatically
    const zon_example =
        \.{
        \    .name = .demo,
    .version = "0.1.0",
    .minimum_zig_version = "0.15.2",
    .fingerprint = 0x1234567890abcdef,
    .paths = .{"build.zig", "src"},
    .dependencies = .{},
}
    ;

    std.debug.print("--- build.zig.zon Field Demo ---\n", .{});
    std.debug.print("Sample ZON structure:\n{s}\n\n", .{zon_example});

    std.debug.print("Field explanations:\n", .{});
    std.debug.print("  .name: Package identifier (symbol literal)\n", .{});
    std.debug.print("  .version: Semantic version string\n", .{});
    std.debug.print("  .minimum_zig_version: Minimum supported Zig\n", .{});
    std.debug.print("  .fingerprint: Unique package ID (hex integer)\n", .{});
    std.debug.print("  .paths: Files included in package distribution\n", .{});
    std.debug.print("  .dependencies: External packages required\n", .{});

    std.debug.print("\nNote: Zig 0.15.2 uses .fingerprint for unique identity\n", .{});
    std.debug.print("      (Previously used UUID-style identifiers)\n", .{});
}

```

--------------------------------

### Zig Project Initialization and Build Workflow

Source: https://www.zigbook.net/chapters/21__zig-init-and-package-metadata

Demonstrates the typical command-line sequence for initializing a new Zig project, building it, running tests, and executing the application. It also highlights the artifacts created during initialization, such as build files and source modules.

```shell
# Create a new directory for the project and navigate into it
$ mkdir mylib && cd mylib

# Initialize a new Zig project
$ zig init
info: created build.zig
info: created build.zig.zon
info: created src/main.zig
info: created src/root.zig

# Build the project
$ zig build

# Build and run tests
$ zig build test
All 3 tests passed.

# Build and run the application
$ zig build run
All your codebase are belong to us.
Run `zig build test` to run the tests.

```

--------------------------------

### Zig Switch Statement Examples: Literals, Ranges, and Enums

Source: https://www.zigbook.net/chapters/02__control-flow-essentials

Demonstrates Zig's switch statement with various matching patterns including exact literals, ranges, multiple discrete values, and a catch-all 'else' branch. It also shows how to use switch with enums for exhaustive matching. This example requires the standard library for printing.

```Zig
// File: chapters-data/code/02__control-flow-essentials/switch_examples.zig

// Import the standard library for I/O operations
const std = @import("std");

// Define an enum representing different compilation modes
const Mode = enum {
    fast,
    safe,
    tiny,
};

/// Converts a numeric score into a descriptive text message.
/// Demonstrates switch expressions with ranges, multiple values, and catch-all cases.
/// Returns a string literal describing the score's progress level.
fn describeScore(score: u8) []const u8 {
    return switch (score) {
        0 => "no progress",           // Exact match for zero
        1...3 => "warming up",         // Range syntax: matches 1, 2, or 3
        4, 5 => "halfway there",       // Multiple discrete values
        6...9 => "almost done",        // Range: matches 6 through 9
        10 => "perfect run",           // Maximum valid score
        else => "out of range",        // Catch-all for any other value
    };
}

pub fn main() !void {
    // Array of test scores to demonstrate switch behavior
    const samples = [_]u8{ 0, 2, 5, 8, 10, 12 };
    
    // Iterate through each score and print its description
    for (samples) |score| {
        std.debug.print("{d}: {s}\n", .{ score, describeScore(score) });
    }

    // Demonstrate switch with enum values
    const mode: Mode = .safe;
    
    // Switch on enum to assign different numeric factors based on mode
    // All enum cases must be handled (exhaustive matching)
    const factor = switch (mode) {
        .fast => 32,  // Optimization for speed
        .safe => 16,  // Balanced mode
        .tiny => 4,   // Optimization for size
    };
    
    // Print the selected mode and its corresponding factor
    std.debug.print("mode {s} -> factor {d}\n", .{ @tagName(mode), factor });
}

```
Tokens:
Raw