模块与导入

// Import the standard library for I/O and basic functionality
const std = @import("std");
// Import a custom module from the project to access build configuration utilities
const config = @import("build_config.zig");
// Import a nested module demonstrating hierarchical module organization
// This path uses a directory structure: service/metrics.zig
const metrics = @import("service/metrics.zig");

/// Version string exported by the root module.
/// This demonstrates how the root module can expose public constants
/// that are accessible to other modules via @import("root").
pub const Version = "0.15.2";

/// Feature flags exported by the root module.
/// This array of string literals showcases a typical pattern for documenting
/// and advertising capabilities or experimental features in a Zig project.
pub const Features = [_][]const u8{
    "root-module-export",
    "builtin-introspection",
    "module-catalogue",
};

/// Entry point for the module graph report utility.
/// Demonstrates a practical use case for @import: composing functionality
/// from multiple modules (std, custom build_config, nested service/metrics)
/// and orchestrating their output to produce a unified report.
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 stdout = &file_writer.interface;

    // Print a header to introduce the report
    try stdout.print("== Module graph walkthrough ==\n", .{});

    // Display the version constant defined in this root module
    // This shows how modules can export and reference their own public declarations
    try stdout.print("root.Version -> {s}\n", .{Version});

    // Invoke a function from the imported build_config module
    // This demonstrates cross-module function calls and how modules
    // encapsulate and expose behavior through their public API
    try config.printSummary(stdout);

    // Invoke a function from the nested metrics module
    // This illustrates hierarchical module organization and the ability
    // to compose deeply nested modules into a coherent application
    try metrics.printCatalog(stdout);

    // Flush the buffered writer to ensure all output is written to stdout
    try stdout.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();
}