启动与基础

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

// Import the standard library for I/O, memory management, and core utilities
// 导入标准库用于I/O、内存管理和核心工具
const std = @import("std");
// Import builtin to access compile-time information about the build environment
// 导入builtin以访问有关构建环境的编译时信息
const builtin = @import("builtin");
// Import root to access declarations from the root source file
// 导入root以访问根源文件中的声明
// In this case, we reference app_name which is defined in this file
// 在这种情况下，我们引用在此文件中定义的app_name
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
// 返回错误联合类型以在执行期间传播任何I/O错误
pub fn main() !void {
    // Allocate a fixed-size buffer on the stack for stdout operations
    // 在栈上为stdout操作分配固定大小的缓冲区
    // This buffer batches write operations to reduce syscalls
    // 该缓冲区批量处理写入操作以减少系统调用
    var stdout_buffer: [256]u8 = undefined;
    // Create a buffered writer wrapping stdout
    // 创建包装stdout的缓冲写入器
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    // Get the generic writer interface for polymorphic I/O operations
    // 获取用于多态I/O操作的通用写入器接口
    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
    // 演示@import("root")如何允许访问入口文件的公共声明
    try stdout.print("app: {s}\n", .{root.app_name});

    // Print the optimization mode (Debug, ReleaseSafe, ReleaseFast, or ReleaseSmall)
    // 打印优化模式（Debug、ReleaseSafe、ReleaseFast或ReleaseSmall）
    // @tagName converts the enum value to its string representation
    // @tagName将枚举值转换为其字符串表示
    try stdout.print("optimize mode: {s}\n", .{@tagName(builtin.mode)});

    // Print the target triple showing CPU architecture, OS, and ABI
    // 打印显示CPU架构、操作系统和ABI的目标三元组
    // Each component is extracted from builtin.target and converted to a string
    // 每个组件从builtin.target中提取并转换为字符串
    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
    // 刷新缓冲区以确保所有累积的输出都写入stdout
    try stdout.flush();
}

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

// Import the standard library for I/O and utility functions
// 导入标准库用于I/O和工具函数
const std = @import("std");
// Import builtin to access compile-time information like build mode
// 导入builtin以访问像构建模式这样的编译时信息
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
    // 打印启动消息到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
// 演示Zig中的缓冲I/O操作
fn announceStartup() !void {
    // Allocate a fixed-size buffer on the stack for stdout operations
    // 在栈上为stdout操作分配固定大小的缓冲区
    var stdout_buffer: [128]u8 = undefined;
    // Create a buffered writer wrapping stdout
    // 创建包装stdout的缓冲写入器
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    // Get the generic writer interface for polymorphic I/O
    // 获取用于多态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
    // 刷新缓冲区以确保消息写入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
    // u32是一个无符号32位整数，初始化为1
    var counter: u32 = 1;

    // Declare an immutable constant with inferred type (comptime_int)
    // 声明具有推断类型的不可变常量（comptime_int）
    // The compiler infers the type from the literal value 2
    // 编译器从字面量值2推断类型
    const increment = 2;

    // Declare a constant with explicit floating-point type
    // 声明具有显式浮点类型的常量
    // f64 is a 64-bit floating-point number
    // f64是64位浮点数
    const ratio: f64 = 0.5;

    // Boolean constant with inferred type
    // 具有推断类型的布尔常量
    // Demonstrates Zig's type inference for simple literals
    // 演示Zig对简单字面量的类型推断
    const flag = true;

    // Character literal representing a newline
    // 表示换行的字符字面量
    // Single-byte characters are u8 values in Zig
    // 单字节字符在Zig中是u8值
    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
    // 只有var声明可以被修改
    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
    // 将换行字节强制转换为u32以显示其ASCII十进制值
    // @as performs explicit type coercion
    // @as执行显式类型强制转换
    std.debug.print("newline byte={} (ASCII)\n", .{@as(u32, newline)});

    // Use compile-time reflection to print the type name of unit_value
    // 使用编译时反射打印unit_value的类型名称
    // @TypeOf gets the type, @typeName converts it to a string
    // @TypeOf获取类型，@typeName将其转换为字符串
    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
    // 在栈上分配256字节的缓冲区用于输出批处理
    // This buffer accumulates write operations to minimize syscalls
    // 该缓冲区累积写入操作以最小化系统调用
    var stdout_buffer: [256]u8 = undefined;

    // Create a buffered writer wrapping stdout
    // 创建包装stdout的缓冲写入器
    // The writer batches output into stdout_buffer before making syscalls
    // 写入器在执行系统调用前将输出批处理到stdout_buffer
    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
    // 尚未发生系统调用—数据在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();
}