构建系统深度解析

const std = @import("std");

// 最小化的 build.zig：单个可执行文件，无选项
// 演示 Zig 构建系统中最简单的构建脚本。
pub fn build(b: *std.Build) void {
    // 使用最简配置创建一个可执行文件编译步骤。
    // 这代表了生成二进制产物的基本模式。
    const exe = b.addExecutable(.{
        // 输出的二进制文件名（将变为 "hello" 或 "hello.exe"）
        .name = "hello",
        // 配置根模块的源文件和编译设置
        .root_module = b.createModule(.{
            // 指定相对于 build.zig 的入口点源文件
            .root_source_file = b.path("main.zig"),
            // 目标为宿主机（运行构建的系统）
            .target = b.graph.host,
            // 使用Debug优化级别（无优化，包含调试符号）
            .optimize = .Debug,
        }),
    });
    
    // 注册可执行文件以安装到输出目录。
    // 运行 `zig build` 时，此产物将被复制到 zig-out/bin/。
    b.installArtifact(exe);
}

// Entry point for a minimal Zig build system example.
// This demonstrates the simplest possible Zig program structure that can be built
// 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");

// 演示标准目标选项和标准优化选项
pub fn build(b: *std.Build) void {
    // 允许用户选择目标：zig build -Dtarget=x86_64-linux
    const target = b.standardTargetOptions(.{});
    
    // 允许用户选择优化：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
// information through the `builtin` module. It's used in the zigbook to teach
// 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
// 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
    // (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)
    // that was specified during compilation
    std.debug.print("Optimize: {s}\n", .{@tagName(builtin.mode)});
}

const std = @import("std");

// 演示模块创建和导入
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});
    
    // 创建一个可重用模块（public）
    const math_mod = b.addModule("math", .{
        .root_source_file = b.path("math.zig"),
        .target = target,
    });
    
    // 使用导入的模块创建可执行文件
    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);
}

// This module provides basic arithmetic operations for the zigbook build system examples.
// It demonstrates how to create a reusable module that can be imported by other Zig files.

// / 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;
}

// 此程序演示如何在Zig的构建系统中使用自定义模块。
// 它导入本地"math"模块并使用其函数执行基本算术运算。

// 导入标准库以获取调试打印功能
const std = @import("std");
// 导入提供算术运算的自定义数学模块
const math = @import("math");

// 主入口点，演示使用基本算术的模块用法
pub fn main() !void {
    // 定义两个常量操作数用于演示
    const a = 10;
    const b = 20;

    // 使用导入的数学模块打印加法结果
    std.debug.print("{d} + {d} = {d}\n", .{ a, b, math.add(a, b) });

    // 使用导入的数学模块打印乘法结果
    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(.{});

    // 创建一个静态库
    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);

    // 创建链接库的可执行文件
    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);
}

// ! 实用工具模块，演示导出函数和格式化输出。
// ! 此模块是构建系统深入研究章节的一部分，展示如何创建
// ! 可以导出并在不同构建工件中使用的库函数。

const std = @import("std");

/// 将输入整数值翻倍。
/// 此函数被导出，可以从C或其他语言调用。
/// 使用`export`关键字使其在编译的库中可用。
export fn util_double(x: i32) i32 {
    return x * 2;
}

/// 将输入整数值平方。
/// 此函数被导出，可以从C或其他语言调用。
/// 使用`export`关键字使其在编译的库中可用。
export fn util_square(x: i32) i32 {
    return x * x;
}

/// 使用整数值将消息格式化到提供的缓冲区中。
/// 这是一个公共Zig函数（未导出），演示基于缓冲区的格式化。
///
/// 返回包含格式化消息的缓冲区切片，或如果缓冲区太小而无法容纳格式化输出，则返回错误。
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");

// 外部函数声明：将输入整数翻倍
// 此函数在单独的库/对象文件中定义
extern fn util_double(x: i32) i32;

// 外部函数声明：将输入整数平方
// 此函数在单独的库/对象文件中定义
extern fn util_square(x: i32) i32;

// 演示库链接的主入口点
// 调用外部工具函数以展示构建系统集成
pub fn main() !void {
    // 用于演示外部函数的测试值
    const x: i32 = 7;

    // 使用外部函数打印 x 翻倍的结果
    std.debug.print("double({d}) = {d}\n", .{ x, util_double(x) });

    // 使用外部函数打印 x 平方 Results
    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,
    });
    
    // 为库模块创建测试
    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 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.
//  n 的阶乘（表示为 n!）是所有小于或等于 n 的正整数的乘积。
//  Base case: factorial(0) = factorial(1) = 1
//  基本情况：阶乘(0) = 阶乘(1) = 1
//  Recursive case: factorial(n) = n * factorial(n-1)
//  递归情况：阶乘(n) = n * 阶乘(n-1)
pub fn factorial(n: u32) u32 {
    // Base case: 0! and 1! both equal 1
    // 基本情况：0! 和 1! 都等于 1
    if (n <= 1) return 1;
    // Recursive case: multiply n by factorial of (n-1)
    // 递归情况：将 n 乘以 (n-1) 的阶乘
    return n * factorial(n - 1);
}

// Test: Verify that the factorial of 0 returns 1 (base case)
// 测试：验证 0 的阶乘返回 1（基本情况）
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)
// 测试：验证 5 的阶乘返回 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)
// 测试：验证 1 的阶乘返回 1（基本情况）
test "factorial of 1 is 1" {
    const std = @import("std");
    try std.testing.expectEqual(@as(u32, 1), factorial(1));
}

// Main entry point demonstrating the factorial function from mylib.
// 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");

// 演示自定义构建选项
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // 自定义布尔选项
    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";

    // 创建选项模块以将配置传递给代码
    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");
// Import build-time configuration options defined in build.zig
// 从 build.zig 导入构建时配置选项
const config = @import("config");

// / 应用程序的入口点，演示构建选项的使用。
// / 此函数展示了如何通过 Zig 构建系统访问和使用在构建过程中设置的配置值。
pub fn main() !void {
    // 显示构建配置中的应用程序名称
    std.debug.print("Application: {s}\n", .{config.app_name});
    // 显示构建配置中的日志开关状态
    std.debug.print("Logging enabled: {}\n", .{config.enable_logging});

    // 根据构建时配置有条件地执行调试日志记录
    // 这演示了使用构建选项的编译时分支
    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/...
...