模块与导入

// 导入标准库以获取I/O和基本功能
const std = @import("std");
// 导入内置模块以访问编译时构建信息
const builtin = @import("builtin");

// 在编译时计算关于当前优化模式的人类可读提示。
// 此块在编译期间评估一次并将结果嵌入为常量字符串。
const optimize_hint = blk: {
    break :blk switch (builtin.mode) {
        .Debug => "调试符号和运行时安全检查已启用",
        .ReleaseSafe => "运行时检查已启用，优化以确保安全",
        .ReleaseFast => "优化优先考虑速度",
        .ReleaseSmall => "优化优先考虑大小",
    };
};

/// 内置探测器工具函数的入口点。
/// 演示如何查询和显示来自`builtin`模块的编译时构建配置，
/// 包括Zig版本、优化模式、目标平台详细信息和链接选项。
pub fn main() !void {
    // 为stdout分配缓冲区以减少系统调用
    var stdout_buffer: [1024]u8 = undefined;
    // 为stdout创建缓冲写入器以提高I/O性能
    var file_writer = std.fs.File.stdout().writer(&stdout_buffer);
    // 获取通用写入器接口用于格式化输出
    const out = &file_writer.interface;

    // 打印嵌入在编译时的Zig编译器版本字符串
    try out.print("zig version (compiler): {s}\n", .{builtin.zig_version_string});

    // 打印优化模式及其对应的描述
    try out.print("optimize mode: {s} — {s}\n", .{ @tagName(builtin.mode), optimize_hint });

    // 打印目标三元组：架构、操作系统和ABI
    // 这些值反映编译二进制文件的平台
    try out.print(
        "target triple: {s}-{s}-{s}\n",
        .{
            @tagName(builtin.target.cpu.arch),
            @tagName(builtin.target.os.tag),
            @tagName(builtin.target.abi),
        },
    );

    // 指示二进制是否以单线程模式构建
    try out.print("single-threaded build: {}\n", .{builtin.single_threaded});

    // 指示是否链接标准C库（libc）
    try out.print("linking libc: {}\n", .{builtin.link_libc});

    // 编译时块，用于在运行测试时有条件地导入测试辅助函数。
    // 这演示了使用`builtin.is_test`启用仅测试代码路径。
    comptime {
        if (builtin.is_test) {
            // 根模块可以使用此钩子启用仅测试辅助函数。
            _ = @import("test_helpers.zig");
        }
    }

    // 刷新缓冲写入器以确保所有输出写入stdout
    try out.flush();
}

// ! 发现探测器工具函数，演示条件导入和运行时内省。
// ! 此模块展示了如何使用编译时条件来可选加载
// ! 开发工具并使用反射在运行时查询其能力。

const std = @import("std");
const builtin = @import("builtin");

/// 基于构建模式有条件地导入开发钩子。
/// 在调试模式下，导入带有诊断功能的完整dev_probe模块。
/// 在其他模式下（ReleaseSafe、ReleaseFast、ReleaseSmall），提供最小化
/// 存根实现以避免加载不必要的开发工具。
///
/// 此模式实现了零成本抽象，其中开发功能在发布构建中完全省略，
/// 同时保持一致的API。
pub const DevHooks = if (builtin.mode == .Debug)
    @import("tools/dev_probe.zig")
else
    struct {
        /// 非调试构建的最小存根实现。
        /// 返回静态消息，指示开发钩子已禁用。
        pub fn banner() []const u8 {
            return "dev hooks disabled";
        }
    };

/// 入口点，演示模块发现和条件特征检测。
/// 此函数展示：
/// 1. 新的Zig 0.15.2缓冲写入器API用于stdout
/// 2. 编译时条件导入（DevHooks）
/// 3. 使用@hasDecl探测可选函数的运行时内省
pub fn main() !void {
    // 为stdout操作创建栈分配的缓冲区
    var stdout_buffer: [512]u8 = undefined;

    // 使用我们的缓冲区初始化文件写入器。这是Zig 0.15.2
    // I/O改造的一部分，其中写入器现在需要显式缓冲区管理。
    var file_writer = std.fs.File.stdout().writer(&stdout_buffer);

    // 获取通用写入器接口用于格式化输出
    const stdout = &file_writer.interface;

    // 报告当前构建模式（Debug、ReleaseSafe、ReleaseFast、ReleaseSmall）
    try stdout.print("discovery mode: {s}\n", .{@tagName(builtin.mode)});

    // 调用DevHooks中始终可用的banner()函数。
    // 实现根据我们是否处于调试模式而有所不同。
    try stdout.print("dev hooks: {s}\n", .{DevHooks.banner()});

    // 使用@hasDecl检查buildSession()函数是否存在于DevHooks中。
    // 这演示了可选功能的运行时发现，而不需要
    // 所有实现都提供每个函数。
    if (@hasDecl(DevHooks, "buildSession")) {
        // buildSession()仅在完整的dev_probe模块中可用（调试构建）
        try stdout.print("built with zig {s}\n", .{DevHooks.buildSession()});
    } else {
        // 在发布构建中，存根DevHooks不提供buildSession()
        try stdout.print("no buildSession() exported\n", .{});
    }

    // 刷新缓冲输出以确保所有内容写入stdout
    try stdout.flush();
}