构建系统深入探讨

const std = @import("std");

// Minimal build.zig: single executable, no options
// 演示Zig构建系统最简单的构建脚本
// Demonstrates the simplest possible build script for the Zig build system.
pub fn build(b: *std.Build) void {
    // Create an executable compilation step with minimal configuration.
    // 创建最小配置的可执行文件编译步骤
    // This represents the fundamental pattern for producing a binary artifact.
    const exe = b.addExecutable(.{
        // The output binary name (becomes "hello" or "hello.exe")
        // 输出二进制文件名（成为"hello"或"hello.exe"）
        .name = "hello",
        // Configure the root module with source file and compilation settings
        // 使用源文件和编译设置配置根模块
        .root_module = b.createModule(.{
            // Specify the entry point source file relative to build.zig
            // 指定相对于build.zig的入口源文件
            .root_source_file = b.path("main.zig"),
            // Target the host machine (the system running the build)
            // 目标主机（运行构建的系统）
            .target = b.graph.host,
            // Use Debug optimization level (no optimizations, debug symbols included)
            // 使用Debug优化级别（无优化，包含调试符号）
            .optimize = .Debug,
        }),
    });

    // Register the executable to be installed to the output directory.
    // 注册要安装到输出目录的可执行文件
    // When `zig build` runs, this artifact will be copied to zig-out/bin/
    b.installArtifact(exe);
}

// Entry point for a minimal Zig build system example.
// 最小Zig构建系统示例的入口点
// This demonstrates the simplest possible Zig program structure that can be built
// 展示了可以使用Zig构建系统构建的最简单的Zig程序结构
// using the Zig build system, showing the basic main function and standard library import.
const std = @import("std");

pub fn main() !void {
    std.debug.print("Hello from minimal build!\n", .{});
}

$ zig build -Dtarget=x86_64-linux       # Linux x86_64
$ zig build -Dtarget=aarch64-macos      # macOS ARM64
$ zig build -Dtarget=wasm32-wasi        # WebAssembly WASI

const target = b.standardTargetOptions(.{
    .default_target = .{ .cpu_arch = .x86_64, .os_tag = .linux },
});

$ zig build                             # Debug (默认)
$ zig build -Doptimize=ReleaseFast      # 最大速度
$ zig build -Doptimize=ReleaseSmall     # 最小大小

const std = @import("std");

// Demonstrating standardTargetOptions and standardOptimizeOption
// 演示standardTargetOptions和standardOptimizeOption
pub fn build(b: *std.Build) void {
    // Allows user to choose target: zig build -Dtarget=x86_64-linux
    // 允许用户选择目标：zig build -Dtarget=x86_64-linux
    const target = b.standardTargetOptions(.{});

    // Allows user to choose optimization: zig build -Doptimize=ReleaseFast
    // 允许用户选择优化：zig build -Doptimize=ReleaseFast
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "configurable",
        .root_module = b.createModule(.{
            .root_source_file = b.path("main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });

    b.installArtifact(exe);

    // Add run step
    // 添加运行步骤
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());

    const run_step = b.step("run", "Run the application");
    run_step.dependOn(&run_cmd.step);
}

// This program demonstrates how to access and display Zig's built-in compilation
// 该程序演示如何通过`builtin`模块访问和显示Zig的内置编译信息
// information through the `builtin` module. It's used in the zigbook to teach
// 它在zigbook中用于教读者了解构建系统内省和标准选项
// readers about build system introspection and standard options.

// Import the standard library for debug printing capabilities
// 导入标准库以获取调试打印功能
const std = @import("std");
// Import builtin module to access compile-time information about the target
// 导入builtin模块以访问关于目标平台的编译时信息
// platform, CPU architecture, and optimization mode
const builtin = @import("builtin");

// Main entry point that prints compilation target information
// 打印编译目标信息的主入口点
// Returns an error union to handle potential I/O failures from debug.print
pub fn main() !void {
    // Print the target architecture (e.g., x86_64, aarch64) and operating system
    // 打印目标架构（例如x86_64, aarch64）和操作系统（例如linux, windows）
    // (e.g., linux, windows) by extracting tag names from the builtin constants
    std.debug.print("Target: {s}-{s}\n", .{
        @tagName(builtin.cpu.arch),
        @tagName(builtin.os.tag),
    });
    // Print the optimization mode (Debug, ReleaseSafe, ReleaseFast, or ReleaseSmall)
    // 打印在编译期间指定的优化模式（Debug, ReleaseSafe, ReleaseFast, 或ReleaseSmall）
    // that was specified during compilation
    std.debug.print("Optimize: {s}\n", .{@tagName(builtin.mode)});
}

const std = @import("std");

// Demonstrating module creation and imports
// 演示模块创建和导入
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Create a reusable module (public)
    // 创建一个可重用的模块（公开）
    const math_mod = b.addModule("math", .{
        .root_source_file = b.path("math.zig"),
        .target = target,
    });

    // Create the executable with import of the module
    // 创建包含模块导入的可执行文件
    const exe = b.addExecutable(.{
        .name = "calculator",
        .root_module = b.createModule(.{
            .root_source_file = b.path("main.zig"),
            .target = target,
            .optimize = optimize,
            .imports = &.{
                .{ .name = "math", .module = math_mod },
            },
        }),
    });

    b.installArtifact(exe);

    const run_step = b.step("run", "Run the calculator");
    const run_cmd = b.addRunArtifact(exe);
    run_step.dependOn(&run_cmd.step);
}

// \1\n    // 该模块为zigbook构建系统示例提供基本算术运算

/// Adds two 32-bit signed integers and returns their sum.
/// This function is marked pub to be accessible from other modules that import this file.
pub fn add(a: i32, b: i32) i32 {
    return a + b;
}

/// Multiplies two 32-bit signed integers and returns their product.
/// This function is marked pub to be accessible from other modules that import this file.
pub fn multiply(a: i32, b: i32) i32 {
    return a * b;
}

// This program demonstrates how to use custom modules in Zig's build system.
// It imports a local "math" module and uses its functions to perform basic arithmetic operations.

// Import the standard library for debug printing capabilities
const std = @import("std");
// Import the custom math module which provides arithmetic operations
const math = @import("math");

// Main entry point demonstrating module usage with basic arithmetic
pub fn main() !void {
    // Define two constant operands for demonstration
    const a = 10;
    const b = 20;
    
    // Print the result of addition using the imported math module
    std.debug.print("{d} + {d} = {d}\n", .{ a, b, math.add(a, b) });
    
    // Print the result of multiplication using the imported math module
    std.debug.print("{d} * {d} = {d}\n", .{ a, b, math.multiply(a, b) });
}

const exe = b.addExecutable(.{
    .name = "myapp",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    }),
});
b.installArtifact(exe);

const lib = b.addLibrary(.{
    .name = "utils",
    .root_module = b.createModule(.{
        .root_source_file = b.path("utils.zig"),
        .target = target,
        .optimize = optimize,
    }),
    . linkage = .static, // or .dynamic
    .version = .{ .major = 1, .minor = 0, .patch = 0 },
});
b.installArtifact(lib);

const std = @import("std");

// 演示库创建
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Create a static library
    const lib = b.addLibrary(.{
        .name = "utils",
        .root_module = b.createModule(.{
            .root_source_file = b.path("utils.zig"),
            .target = target,
            .optimize = optimize,
        }),
        .linkage = .static,
        .version = .{ .major = 1, .minor = 0, .patch = 0 },
    });

    b.installArtifact(lib);

    // Create an executable that links the library
    const exe = b.addExecutable(.{
        .name = "demo",
        .root_module = b.createModule(.{
            .root_source_file = b.path("main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });

    exe.linkLibrary(lib);
    b.installArtifact(exe);

    const run_step = b.step("run", "Run the demo");
    const run_cmd = b.addRunArtifact(exe);
    run_step.dependOn(&run_cmd.step);
}

//! Utility module demonstrating exported functions and formatted output.
//! This module is part of the build system deep dive chapter, showing how to create
//! library functions that can be exported and used across different build artifacts.

const std = @import("std");

/// Doubles the input integer value.
/// This function is exported and can be called from C or other languages.
/// Uses the `export` keyword to make it available in the compiled library.
export fn util_double(x: i32) i32 {
    return x * 2;
}

/// Squares the input integer value.
/// This function is exported and can be called from C or other languages.
/// Uses the `export` keyword to make it available in the compiled library.
export fn util_square(x: i32) i32 {
    return x * x;
}

/// Formats a message with an integer value into the provided buffer.
/// This is a public Zig function (not exported) that demonstrates buffer-based formatting.
/// 
/// Returns a slice of the buffer containing the formatted message, or an error if
/// the buffer is too small to hold the formatted output.
pub fn formatMessage(buf: []u8, value: i32) ![]const u8 {
    return std.fmt.bufPrint(buf, "Value: {d}", .{value});
}

// Import the standard library for printing capabilities
const std = @import("std");

// External function declaration: doubles the input integer
// This function is defined in a separate library/object file
extern fn util_double(x: i32) i32;

// External function declaration: squares the input integer
// This function is defined in a separate library/object file
extern fn util_square(x: i32) i32;

// Main entry point demonstrating library linking
// Calls external utility functions to show build system integration
pub fn main() !void {
    // Test value for demonstrating the external functions
    const x: i32 = 7;
    
    // Print the result of doubling x using the external function
    std.debug.print("double({d}) = {d}\n", .{ x, util_double(x) });
    
    // Print the result of squaring x using the external function
    std.debug.print("square({d}) = {d}\n", .{ x, util_square(x) });
}

const lib_tests = b.addTest(.{
    .root_module = lib_mod,
});

const run_lib_tests = b.addRunArtifact(lib_tests);

const test_step = b.step("test", "Run library tests");
test_step.dependOn(&run_lib_tests.step);

const std = @import("std");

// 演示测试集成
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});
    
    const lib_mod = b.addModule("mylib", .{
        .root_source_file = b.path("lib.zig"),
        .target = target,
    });
    
    // Create tests for the library module
    const lib_tests = b.addTest(.{
        .root_module = lib_mod,
    });
    
    const run_lib_tests = b.addRunArtifact(lib_tests);
    
    // Create a test step
    const test_step = b.step("test", "Run library tests");
    test_step.dependOn(&run_lib_tests.step);
    
    // Also create an executable that uses the library
    const exe = b.addExecutable(.{
        .name = "app",
        .root_module = b.createModule(.{
            .root_source_file = b.path("main.zig"),
            .target = target,
            .optimize = optimize,
            .imports = &.{
                .{ .name = "mylib", .module = lib_mod },
            },
        }),
    });
    
    b.installArtifact(exe);
}

/// Computes the factorial of a non-negative integer using recursion.
/// The factorial of n (denoted as n!) is the product of all positive integers less than or equal to n.
/// Base case: factorial(0) = factorial(1) = 1
/// Recursive case: factorial(n) = n * factorial(n-1)
pub fn factorial(n: u32) u32 {
    // Base case: 0! and 1! both equal 1
    if (n <= 1) return 1;
    // Recursive case: multiply n by factorial of (n-1)
    return n * factorial(n - 1);
}

// Test: Verify that the factorial of 0 returns 1 (base case)
test "factorial of 0 is 1" {
    const std = @import("std");
    try std.testing.expectEqual(@as(u32, 1), factorial(0));
}

// Test: Verify that the factorial of 5 returns 120 (5! = 5*4*3*2*1 = 120)
test "factorial of 5 is 120" {
    const std = @import("std");
    try std.testing.expectEqual(@as(u32, 120), factorial(5));
}

// Test: Verify that the factorial of 1 returns 1 (base case)
test "factorial of 1 is 1" {
    const std = @import("std");
    try std.testing.expectEqual(@as(u32, 1), factorial(1));
}

// \1\n    // 演示模块使用和基本算术的主入口点
// This example shows how to:
// - Import and use custom library modules
// - Call library functions with different input values
// - Display computed results using debug printing
const std = @import("std");
const mylib = @import("mylib");

pub fn main() !void {
    std.debug.print("5! = {d}\n", .{mylib.factorial(5)});
    std.debug.print("10! = {d}\n", .{mylib.factorial(10)});
}

const run_step = b.step("run", "Run the application");
const run_cmd = b.addRunArtifact(exe);
run_cmd.step.dependOn(b.getInstallStep());
run_step.dependOn(&run_cmd.step);

const enable_logging = b.option(bool, "enable-logging", "Enable debug logging") orelse false;
const app_name = b.option([]const u8, "app-name", "Application name") orelse "MyApp";

$ zig build -Denable-logging -Dapp-name=CustomName run

const std = @import("std");

// Demonstrating custom build options
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Custom boolean option
    const enable_logging = b.option(
        bool,
        "enable-logging",
        "Enable debug logging",
    ) orelse false;

    // Custom string option
    const app_name = b.option(
        []const u8,
        "app-name",
        "Application name",
    ) orelse "MyApp";

    // Create options module to pass config to code
    const config = b.addOptions();
    config.addOption(bool, "enable_logging", enable_logging);
    config.addOption([]const u8, "app_name", app_name);

    const config_module = config.createModule();

    const exe = b.addExecutable(.{
        .name = "configapp",
        .root_module = b.createModule(.{
            .root_source_file = b.path("main.zig"),
            .target = target,
            .optimize = optimize,
            .imports = &.{
                .{ .name = "config", .module = config_module },
            },
        }),
    });

    b.installArtifact(exe);

    const run_step = b.step("run", "Run the app");
    const run_cmd = b.addRunArtifact(exe);
    run_step.dependOn(&run_cmd.step);
}

// Import standard library for debug printing functionality
const std = @import("std");
// \1\n    // 导入在build.zig中定义的构建时配置选项
const config = @import("config");

/// Entry point of the application demonstrating the use of build options.
/// This function showcases how to access and use configuration values that
/// are set during the build process through the Zig build system.
pub fn main() !void {
    // Display the application name from build configuration
    std.debug.print("Application: {s}\n", .{config.app_name});
    // Display the logging toggle status from build configuration
    std.debug.print("Logging enabled: {}\n", .{config.enable_logging});

    // Conditionally execute debug logging based on build-time configuration
    // This demonstrates compile-time branching using build options
    if (config.enable_logging) {
        std.debug.print("[DEBUG] This is a debug message\n", .{});
    }
}

$ zig build -v
zig build-exe /path/to/main.zig -target x86_64-linux -O Debug -femit-bin=zig-cache/...
zig build-lib /path/to/lib.zig -target x86_64-linux -O Debug -femit-bin=zig-cache/...
...