启动与基础

// 文件路径: chapters-data/code/01__boot-basics/imports.zig

// 导入标准库用于I/O、内存管理和核心工具
const std = @import("std");
// 导入内置模块以访问构建环境的编译时信息
const builtin = @import("builtin");
// 导入根模块以访问根源文件中的声明
// 此处我们引用app_name，它定义在当前文件中
const root = @import("root");

// 可被其他导入此文件的模块访问的公开常量
pub const app_name = "Boot Basics Tour";

// 程序的主入口点
// 返回错误联合类型以传播执行过程中产生的任何I/O错误
pub fn main() !void {
    // 在栈上分配固定大小的缓冲区用于标准输出操作
    // 此缓冲区批量处理写入操作以减少系统调用
    var stdout_buffer: [256]u8 = undefined;
    // 创建包装标准输出的缓冲写入器
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    // 获取用于多态I/O操作的通用写入器接口
    const stdout = &stdout_writer.interface;

    // 通过引用根模块的声明来打印应用程序名称
    // 演示@import("root")如何允许访问入口文件的公开声明
    try stdout.print("app: {s}\n", .{root.app_name});

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

    // 打印目标三元组，显示CPU架构、操作系统和ABI
    // 每个组件从builtin.target提取并转换为字符串
    try stdout.print(
        "target: {s}-{s}-{s}\n",
        .{
            @tagName(builtin.target.cpu.arch),
            @tagName(builtin.target.os.tag),
            @tagName(builtin.target.abi),
        },
    );

    // 刷新缓冲区以确保所有累积的输出写入标准输出
    try stdout.flush();
}

// 文件路径: chapters-data/code/01__boot-basics/entry_point.zig

// 导入标准库用于I/O和工具函数
const std = @import("std");
// 导入内置模块以访问编译时信息（如构建模式）
const builtin = @import("builtin");

// 定义用于表示构建模式违规的自定义错误类型
const ModeError = error{ReleaseOnly};

// 程序的主入口点
// 返回错误联合类型以传播执行过程中产生的所有错误
pub fn main() !void {
    // 尝试强制执行调试模式要求
    // 失败时捕获错误并打印警告，而非终止程序
    requireDebugSafety() catch |err| {
        std.debug.print("warning: {s}\n", .{@errorName(err)});
    };

    // 向标准输出打印启动消息
    try announceStartup();
}

// 验证程序是否在调试模式下运行
// 如果以发布模式编译则返回错误（用于演示错误处理）
fn requireDebugSafety() ModeError!void {
    // 检查编译时的构建模式
    if (builtin.mode == .Debug) return;
    // 如果不在调试模式下则返回错误
    return ModeError.ReleaseOnly;
}

// 向标准输出写入启动公告消息
// 演示Zig中的缓冲I/O操作
fn announceStartup() !void {
    // 在栈上分配固定大小的缓冲区用于标准输出操作
    var stdout_buffer: [128]u8 = undefined;
    // 创建包装标准输出的缓冲写入器
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    // 获取用于多态I/O的通用写入器接口
    const stdout = &stdout_writer.interface;
    // 向缓冲区写入格式化消息
    try stdout.print("Zig entry point reporting in.\n", .{});
    // 刷新缓冲区以确保消息写入标准输出
    try stdout.flush();
}

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

pub fn main() !void {
    // 声明带显式类型标注的可变变量
    // u32为无符号32位整数，初始化为1
    var counter: u32 = 1;

    // 声明带推断类型的不可变常量（comptime_int）
    // 编译器从字面值2推断出类型
    const increment = 2;

    // 声明带显式浮点类型的常量
    // f64为64位浮点数
    const ratio: f64 = 0.5;

    // 布尔常量，带推断类型
    // 演示Zig对简单字面值的类型推断
    const flag = true;

    // 表示换行的字符字面值
    // 单字节字符在Zig中是u8值
    const newline: u8 = '\n';

    // 单元类型值，类似于其他语言中的()
    // 显式表示"无值"或"空"
    const unit_value = void{};

    // 通过增加值来修改计数器
    // 只有var声明可以被修改
    counter += increment;

    // 打印显示不同值类型的格式化输出
    // {}是适用于任何类型的通用格式说明符
    std.debug.print("counter={} ratio={} safety={}\n", .{ counter, ratio, flag });

    // 将换行符字节强制转换为u32以显示其ASCII十进制值
    // @as执行显式类型转换
    std.debug.print("newline byte={} (ASCII)\n", .{@as(u32, newline)});

    // 使用编译时反射来打印unit_value的类型名称
    // @TypeOf获取类型，@typeName将其转换为字符串
    std.debug.print("unit literal has type {s}\n", .{@typeName(@TypeOf(unit_value))});
}

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

pub fn main() !void {
    // 在栈上分配256字节的缓冲区用于批量输出
    // 此缓冲区聚合写入操作以减少系统调用次数
    var stdout_buffer: [256]u8 = undefined;

    // 创建包装stdout的缓冲写入器
    // 写入器在发起系统调用前将输出批量处理到stdout_buffer
    var writer_state = std.fs.File.stdout().writer(&stdout_buffer);
    const stdout = &writer_state.interface;

    // 这些打印调用写入缓冲区，而非直接写入终端
    // 此时尚未发生系统调用——数据累积在stdout_buffer中
    try stdout.print("Buffering saves syscalls.\n", .{});
    try stdout.print("Flush once at the end.\n", .{});

    // 显式刷新缓冲区，一次性写入所有累积的数据
    // 这将触发单个系统调用，而非每次打印操作一次
    try stdout.flush();
}