Boot & Basics

// 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();
}

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

// Import the standard library for I/O and utility functions
const std = @import("std");
// Import builtin to access compile-time information like build mode
const builtin = @import("builtin");

// Define a custom error type for build mode violations
const ModeError = error{ReleaseOnly};

// Main entry point of the program
// Returns an error union to propagate any errors that occur during execution
pub fn main() !void {
    // Attempt to enforce debug mode requirement
    // If it fails, catch the error and print a warning instead of terminating
    requireDebugSafety() catch |err| {
        std.debug.print("warning: {s}\n", .{@errorName(err)});
    };

    // Print startup message to stdout
    try announceStartup();
}

// Validates that the program is running in Debug mode
// Returns an error if compiled in Release mode to demonstrate error handling
fn requireDebugSafety() ModeError!void {
    // Check compile-time build mode
    if (builtin.mode == .Debug) return;
    // Return error if not in Debug mode
    return ModeError.ReleaseOnly;
}

// Writes a startup announcement message to standard output
// Demonstrates buffered I/O operations in Zig
fn announceStartup() !void {
    // Allocate a fixed-size buffer on the stack for stdout operations
    var stdout_buffer: [128]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
    const stdout = &stdout_writer.interface;
    // Write formatted message to the buffer
    try stdout.print("Zig entry point reporting in.\n", .{});
    // Flush the buffer to ensure message is written to stdout
    try stdout.flush();
}

// File: chapters-data/code/01__boot-basics/values_and_literals.zig
const std = @import("std");

pub fn main() !void {
    // Declare a mutable variable with explicit type annotation
    // u32 is an unsigned 32-bit integer, initialized to 1
    var counter: u32 = 1;
    
    // Declare an immutable constant with inferred type (comptime_int)
    // The compiler infers the type from the literal value 2
    const increment = 2;
    
    // Declare a constant with explicit floating-point type
    // f64 is a 64-bit floating-point number
    const ratio: f64 = 0.5;
    
    // Boolean constant with inferred type
    // Demonstrates Zig's type inference for simple literals
    const flag = true;
    
    // Character literal representing a newline
    // Single-byte characters are u8 values in Zig
    const newline: u8 = '\n';
    
    // The unit type value, analogous to () in other languages
    // Represents "no value" or "nothing" explicitly
    const unit_value = void{};

    // Mutate the counter by adding the increment
    // Only var declarations can be modified
    counter += increment;

    // Print formatted output showing different value types
    // {} is a generic format specifier that works with any type
    std.debug.print("counter={} ratio={} safety={}\n", .{ counter, ratio, flag });
    
    // Cast the newline byte to u32 for display as its ASCII decimal value
    // @as performs explicit type coercion
    std.debug.print("newline byte={} (ASCII)\n", .{@as(u32, newline)});
    
    // Use compile-time reflection to print the type name of unit_value
    // @TypeOf gets the type, @typeName converts it to a string
    std.debug.print("unit literal has type {s}\n", .{@typeName(@TypeOf(unit_value))});
}

// File: chapters-data/code/01__boot-basics/buffered_stdout.zig
const std = @import("std");

pub fn main() !void {
    // Allocate a 256-byte buffer on the stack for output batching
    // This buffer accumulates write operations to minimize syscalls
    var stdout_buffer: [256]u8 = undefined;
    
    // Create a buffered writer wrapping stdout
    // The writer batches output into stdout_buffer before making syscalls
    var writer_state = std.fs.File.stdout().writer(&stdout_buffer);
    const stdout = &writer_state.interface;

    // These print calls write to the buffer, not directly to the terminal
    // No syscalls occur yet—data accumulates in stdout_buffer
    try stdout.print("Buffering saves syscalls.\n", .{});
    try stdout.print("Flush once at the end.\n", .{});
    
    // Explicitly flush the buffer to write all accumulated data at once
    // This triggers a single syscall instead of one per print operation
    try stdout.flush();
}