Modules & Imports

// Import the standard library for I/O and basic functionality
const std = @import("std");
// Import the builtin module to access compile-time build information
const builtin = @import("builtin");

// Compute a human-readable hint about the current optimization mode at compile time.
// This block evaluates once during compilation and embeds the result as a constant string.
const optimize_hint = blk: {
    break :blk switch (builtin.mode) {
        .Debug => "debug symbols and runtime safety checks enabled",
        .ReleaseSafe => "runtime checks on, optimized for safety",
        .ReleaseFast => "optimizations prioritized for speed",
        .ReleaseSmall => "optimizations prioritized for size",
    };
};

/// Entry point for the builtin probe utility.
/// Demonstrates how to query and display compile-time build configuration
/// from the `builtin` module, including Zig version, optimization mode,
/// target platform details, and linking options.
pub fn main() !void {
    // Allocate a buffer for stdout buffering to reduce system calls
    var stdout_buffer: [1024]u8 = undefined;
    // Create a buffered writer for stdout to improve I/O performance
    var file_writer = std.fs.File.stdout().writer(&stdout_buffer);
    // Obtain the generic writer interface for formatted output
    const out = &file_writer.interface;

    // Print the Zig compiler version string embedded at compile time
    try out.print("zig version (compiler): {s}\n", .{builtin.zig_version_string});
    
    // Print the optimization mode and its corresponding description
    try out.print("optimize mode: {s} — {s}\n", .{ @tagName(builtin.mode), optimize_hint });
    
    // Print the target triple: architecture, OS, and ABI
    // These values reflect the platform for which the binary was compiled
    try out.print(
        "target triple: {s}-{s}-{s}\n",
        .{
            @tagName(builtin.target.cpu.arch),
            @tagName(builtin.target.os.tag),
            @tagName(builtin.target.abi),
        },
    );
    
    // Indicate whether the binary was built in single-threaded mode
    try out.print("single-threaded build: {}\n", .{builtin.single_threaded});
    
    // Indicate whether the standard C library (libc) is linked
    try out.print("linking libc: {}\n", .{builtin.link_libc});

    // Compile-time block to conditionally import test helpers when running tests.
    // This demonstrates using `builtin.is_test` to enable test-only code paths.
    comptime {
        if (builtin.is_test) {
            // The root module could enable test-only helpers using this hook.
            _ = @import("test_helpers.zig");
        }
    }

    // Flush the buffered writer to ensure all output is written to stdout
    try out.flush();
}

//! Discovery probe utility demonstrating conditional imports and runtime introspection.
//! This module showcases how to use compile-time conditionals to optionally load
//! development tools and query their capabilities at runtime using reflection.

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

/// Conditionally import development hooks based on build mode.
/// In Debug mode, imports the full dev_probe module with diagnostic capabilities.
/// In other modes (ReleaseSafe, ReleaseFast, ReleaseSmall), provides a minimal
/// stub implementation to avoid loading unnecessary development tooling.
///
/// This pattern enables zero-cost abstractions where development features are
/// completely elided from release builds while maintaining a consistent API.
pub const DevHooks = if (builtin.mode == .Debug)
    @import("tools/dev_probe.zig")
else
    struct {
        /// Minimal stub implementation for non-debug builds.
        /// Returns a static message indicating development hooks are disabled.
        pub fn banner() []const u8 {
            return "dev hooks disabled";
        }
    };

/// Entry point demonstrating module discovery and conditional feature detection.
/// This function showcases:
/// 1. The new Zig 0.15.2 buffered writer API for stdout
/// 2. Compile-time conditional imports (DevHooks)
/// 3. Runtime introspection using @hasDecl to probe for optional functions
pub fn main() !void {
    // Create a stack-allocated buffer for stdout operations
    var stdout_buffer: [512]u8 = undefined;
    
    // Initialize a file writer with our buffer. This is part of the Zig 0.15.2
    // I/O revamp where writers now require explicit buffer management.
    var file_writer = std.fs.File.stdout().writer(&stdout_buffer);
    
    // Obtain the generic writer interface for formatted output
    const stdout = &file_writer.interface;

    // Report the current build mode (Debug, ReleaseSafe, ReleaseFast, ReleaseSmall)
    try stdout.print("discovery mode: {s}\n", .{@tagName(builtin.mode)});
    
    // Call the always-available banner() function from DevHooks.
    // The implementation varies based on whether we're in Debug mode or not.
    try stdout.print("dev hooks: {s}\n", .{DevHooks.banner()});

    // Use @hasDecl to check if the buildSession() function exists in DevHooks.
    // This demonstrates runtime discovery of optional capabilities without
    // requiring all implementations to provide every function.
    if (@hasDecl(DevHooks, "buildSession")) {
        // buildSession() is only available in the full dev_probe module (Debug builds)
        try stdout.print("built with zig {s}\n", .{DevHooks.buildSession()});
    } else {
        // In release builds, the stub DevHooks doesn't provide buildSession()
        try stdout.print("no buildSession() exported\n", .{});
    }

    // Flush the buffered output to ensure all content is written to stdout
    try stdout.flush();
}