跳转到内容

std.Build.Module

标准库Zig 0.17.1官方原文
源码std/Build/Module.zig

第 1 行

字段

owner: *std.Build

负责创建此模块的对象。

root_source_file: ?LazyPath
import_table: std.array_hash_map.String(*Module)

映射到此模块导入表中的模块。 请使用 addImport 修改,而不要直接修改此字段, 以保持步骤依赖边。

resolved_target: ?std.Build.ResolvedTarget = null
optimize: ?std.builtin.Optimize = null
dwarf_format: ?std.dwarf.Format
c_macros: ArrayList([]const u8)
include_dirs: ArrayList(IncludeDir)
lib_paths: ArrayList(LazyPath)
rpaths: ArrayList(RPath)
frameworks: std.array_hash_map.String(LinkFrameworkOptions)
link_objects: ArrayList(LinkObject)
strip: ?bool
unwind_tables: ?std.builtin.UnwindTables
single_threaded: ?bool
stack_protector: ?bool
stack_check: ?bool
sanitize_c: ?std.zig.SanitizeC
sanitize_thread: ?bool
fuzz: ?bool
code_model: std.builtin.CodeModel
valgrind: ?bool
pic: ?bool
red_zone: ?bool
omit_frame_pointer: ?bool
error_tracing: ?bool
link_libc: ?bool
link_libcpp: ?bool
no_builtin: ?bool
patchable_function_entry: u16
export_symbol_names: []const []const u8 = &.{}

编译为 WebAssembly 时要导出的符号。

cached_graph: Graph = .{ .modules = &.{}, .names = &.{} }

缓存多次调用 getGraph 时的结果。 请使用 getGraph,不要直接访问此字段。

std.Build.Module.addAfterIncludePath

函数

第 464 行

pub fn addAfterIncludePath(m: *Module, lazy_path: LazyPath) void

参数

m: *Module
lazy_path: LazyPath

std.Build.Module.addAnonymousImport

函数

第 313 行

创建新模块,并将其添加为可通过 @import 使用的模块。

pub fn addAnonymousImport(m: *Module, name: []const u8, options: CreateOptions) void

参数

m: *Module
name: []const u8
options: CreateOptions

std.Build.Module.addAssemblyFile

函数

第 442 行

pub fn addAssemblyFile(m: *Module, source: LazyPath) void

参数

m: *Module
source: LazyPath

std.Build.Module.addCMacro

函数

第 530 行

等同于对属于此 Module 的所有 C 源码文件 应用以下 C 代码:

#define name value

name 和 value 的生命周期无需超过函数调用。

pub fn addCMacro(m: *Module, name: []const u8, value: []const u8) void

参数

m: *Module
name: []const u8
value: []const u8

std.Build.Module.addConfigHeader

函数

第 482 行

pub fn addConfigHeader(m: *Module, config_header: *Step.ConfigHeader) void

参数

m: *Module
config_header: *Step.ConfigHeader

std.Build.Module.addCSourceFile

函数

第 415 行

pub fn addCSourceFile(m: *Module, source: CSourceFile) void

参数

m: *Module
source: CSourceFile

std.Build.Module.addCSourceFiles

函数

第 391 行

当存在许多非 Zig 源文件且希望它们使用相同标志时很有用。

pub fn addCSourceFiles(m: *Module, options: AddCSourceFilesOptions) void

参数

std.Build.Module.AddCSourceFilesOptions

容器

第 380 行

字段

root: ?LazyPath = null

若提供 root,则 files 相对于它,而非 拥有 Compile 步骤的程序包。

files: []const []const u8
flags: []const []const u8 = &.{}
language: ?CSourceLanguage = null

默认根据各文件的扩展名,分别确定其语言

std.Build.Module.addEmbedPath

函数

第 500 行

pub fn addEmbedPath(m: *Module, lazy_path: LazyPath) void

参数

m: *Module
lazy_path: LazyPath

std.Build.Module.addFrameworkPath

函数

第 494 行

pub fn addFrameworkPath(m: *Module, directory_path: LazyPath) void

参数

m: *Module
directory_path: LazyPath

std.Build.Module.addImport

函数

第 306 行

添加一个现有模块,以供 @import 使用。

pub fn addImport(m: *Module, name: []const u8, module: *Module) void

参数

m: *Module
name: []const u8
module: *Module

std.Build.Module.addIncludePath

函数

第 476 行

pub fn addIncludePath(m: *Module, lazy_path: LazyPath) void

参数

m: *Module
lazy_path: LazyPath

std.Build.Module.addLibraryPath

函数

第 506 行

pub fn addLibraryPath(m: *Module, directory_path: LazyPath) void

参数

m: *Module
directory_path: LazyPath

std.Build.Module.addObject

函数

第 454 行

pub fn addObject(m: *Module, object: *Step.Compile) void

参数

m: *Module
object: *Step.Compile

std.Build.Module.addObjectFile

函数

第 448 行

pub fn addObjectFile(m: *Module, object: LazyPath) void

参数

m: *Module
object: LazyPath

std.Build.Module.addOptions

函数

第 321 行

将一组键值对转换为 Zig 源码文件,然后以指定名称加入 Module 的导入表。这样即可通过 @import("module_name") 导入这些选项。

pub fn addOptions(m: *Module, module_name: []const u8, options: *Step.Options) void

参数

m: *Module
module_name: []const u8
options: *Step.Options

std.Build.Module.addRPath

函数

第 512 行

pub fn addRPath(m: *Module, directory_path: LazyPath) void

参数

m: *Module
directory_path: LazyPath

std.Build.Module.addRPathSpecial

函数

第 518 行

pub fn addRPathSpecial(m: *Module, bytes: []const u8) void

参数

m: *Module
bytes: []const u8

std.Build.Module.addSystemFrameworkPath

函数

第 488 行

pub fn addSystemFrameworkPath(m: *Module, directory_path: LazyPath) void

参数

m: *Module
directory_path: LazyPath

std.Build.Module.addSystemIncludePath

函数

第 470 行

pub fn addSystemIncludePath(m: *Module, lazy_path: LazyPath) void

参数

m: *Module
lazy_path: LazyPath

std.Build.Module.addWin32ResourceFile

函数

第 429 行

已弃用。此功能将移至外部软件包: https://codeberg.org/ziglang/rc

资源文件必须使用扩展名 .rc。 可针对任意目标调用。如果目标文件格式不支持嵌入资源, 则忽略 .rc 文件。

pub fn addWin32ResourceFile(m: *Module, source: RcSourceFile) void

参数

m: *Module
source: RcSourceFile

std.Build.Module.ArrayList

别名

第 7 行

别名目标 std.ArrayList

std.Build.Module.assert

别名

第 4 行

别名目标 std.debug.assert

std.Build.Module.create

函数

第 297 行

pub fn create(owner: *std.Build, options: CreateOptions) *Module

参数

owner: *std.Build
options: CreateOptions

std.Build.Module.CreateOptions

容器

第 191 行

插入导入表时,此处未指定的选项 将从父级 Module 继承。

字段

root_source_file: ?LazyPath = null

可以是生成文件,此时模块恰好包含一个文件; 也可以是组成该模块的文件目录中 根源文件的路径。 若为 null,表示此模块仅由 link_objects 构成。

imports: []const Import = &.{}

此模块可通过 @import 访问的其他模块的映射表。 允许循环导入,因此在创建 Module 后, 仍可通过 addImport 向此表添加条目。

target: ?std.Build.ResolvedTarget = null
optimize: ?std.builtin.Optimize = null
link_libc: ?bool = null

true 要求包含此 Module 的编译链接 libc。 false 会在包含此 Module 的编译将链接 libc 时导致构建失败。 null 既不要求也不阻止链接 libc。

link_libcpp: ?bool = null

true 要求包含此 Module 的编译链接 libc++。 false 使包含此 Module 且会链接 libc++ 的编译构建失败。 null 既不要求也不阻止链接 libc++。

single_threaded: ?bool = null
strip: ?bool = null
unwind_tables: ?std.builtin.UnwindTables = null
dwarf_format: ?std.dwarf.Format = null
code_model: std.builtin.CodeModel = .default
stack_protector: ?bool = null
stack_check: ?bool = null
sanitize_c: ?std.zig.SanitizeC = null
sanitize_thread: ?bool = null
fuzz: ?bool = null
valgrind: ?bool = null

是否生成与 Valgrind 集成的机器码。

pic: ?bool = null

位置无关代码

red_zone: ?bool = null
omit_frame_pointer: ?bool = null

是否省略栈帧指针。可以释放一个寄存器,但更难获取栈轨迹。 效果取决于目标。

error_tracing: ?bool = null
no_builtin: ?bool = null
patchable_function_entry: u16 = 0

std.Build.Module.CSourceFile

容器

第 118 行

字段

file: LazyPath
flags: []const []const u8 = &.{}
language: ?CSourceLanguage = null

默认根据各文件的扩展名,分别确定其语言

std.Build.Module.CSourceFile.dupe

函数

第 124 行

pub fn dupe(file: CSourceFile, graph: *const std.Build.Graph) CSourceFile

参数

file: CSourceFile
graph: *const std.Build.Graph

std.Build.Module.CSourceFiles

容器

第 108 行

字段

root: LazyPath
files: []const []const u8

files 相对于 root, 后者默认为构建根目录。

flags: []const []const u8
language: ?CSourceLanguage

默认根据各文件的扩展名,分别确定其语言

std.Build.Module.CSourceLanguage

容器

第 83 行

字段

c
cpp
objective_c
objective_cpp
assembly

标准汇编

assembly_with_preprocessor

使用 C 预处理器的汇编

std.Build.Module.CSourceLanguage.clangIdentifier

函数

第 96 行

传递给 Clang 命令行选项 "-x" 的值。

pub fn clangIdentifier(self: CSourceLanguage) [:0]const u8

参数

std.Build.Module.getGraph

函数

第 566 行

给定编译的根 Module 为 root,返回模块图中的 全部 Module,包括 root 本身。保证 root 为返回切片中的首个模块。

pub fn getGraph(root: *Module) Graph

参数

root: *Module

std.Build.Module.Graph

容器

第 558 行

modules 与 names 的元素一一对应。

字段

modules: []const *Module
names: []const []const u8

std.Build.Module.Import

容器

第 237 行

字段

name: []const u8
module: *Module

std.Build.Module.IncludeDir

容器

第 162 行

字段

path: LazyPath
path_system: LazyPath
path_after: LazyPath
framework_path: LazyPath
framework_path_system: LazyPath
other_step: *Step.Compile
config_header_step: *Step.ConfigHeader
embed_path: LazyPath

std.Build.Module.init

函数

第 242 行

pub fn init( m: *Module, owner: *std.Build, value: union(enum) { options: CreateOptions, existing: *const Module }, ) void

参数

m: *Module
owner: *std.Build
value: union(enum) { options: CreateOptions, existing: *const Module }

std.Build.Module.LazyPath

别名

第 5 行

别名目标 std.Build.LazyPath

std.Build.Module.linkFramework

函数

第 374 行

pub fn linkFramework(m: *Module, name: []const u8, options: LinkFrameworkOptions) void

参数

m: *Module
name: []const u8
options: LinkFrameworkOptions

std.Build.Module.LinkFrameworkOptions

容器

第 173 行

字段

needed: bool = false

无论是否实际依赖动态库,都链接它们。 为 false 时,链接器会省略那些 没有任何符号被引用的动态库。

weak: bool = false

将此库中所有被引用的符号标记为弱符号。这意味着,若另一个编译单元提供同名符号,链接器不会报告“符号重复”错误,而会将所有对该符号的引用解析到强符号版本。

链接器遇到两个弱符号时,根据编译单元传给链接器的顺序选择,后提供的优先。

std.Build.Module.linkLibrary

函数

第 459 行

pub fn linkLibrary(m: *Module, library: *Step.Compile) void

参数

m: *Module
library: *Step.Compile

std.Build.Module.linkLibraryOrObject

函数

第 537 行

fn linkLibraryOrObject(m: *Module, other: *Step.Compile) void

参数

m: *Module
other: *Step.Compile

std.Build.Module.LinkObject

容器

第 59 行

字段

static_path: LazyPath
other_step: *Step.Compile
system_lib: SystemLib
assembly_file: LazyPath
c_source_file: *CSourceFile
c_source_files: *CSourceFiles
win32_resource_file: *RcSourceFile

已弃用。此功能将移至外部包: https://codeberg.org/ziglang/rc

std.Build.Module.linkSystemLibrary

函数

第 344 行

pub fn linkSystemLibrary( m: *Module, name: []const u8, options: LinkSystemLibraryOptions, ) void

参数

m: *Module
name: []const u8
options: LinkSystemLibraryOptions

std.Build.Module.LinkSystemLibraryOptions

容器

第 325 行

字段

needed: bool = false

无论是否实际依赖动态库,都链接它们。 为 false 时,链接器会省略那些 没有任何符号被引用的动态库。

weak: bool = false

将此库中所有被引用的符号标记为弱符号。这意味着,若另一个编译单元提供同名符号,链接器不会报告“符号重复”错误,而会将所有对该符号的引用解析到强符号版本。

链接器遇到两个弱符号时,根据编译单元传给链接器的顺序选择,后提供的优先。

use_pkg_config: SystemLib.UsePkgConfig = .yes
preferred_link_mode: std.builtin.LinkMode = .dynamic
search_strategy: SystemLib.SearchStrategy = .paths_first

std.Build.Module.Module

别名

第 1 行

别名目标 std.Build.Module

std.Build.Module.RcSourceFile

容器

第 135 行

已弃用。此功能将移至外部包: https://codeberg.org/ziglang/rc

字段

file: LazyPath
flags: []const []const u8 = &.{}

rc.exe 接受的选项均可用于此处,但以下选项除外:

隐式定义的选项: /x,忽略 INCLUDE 环境变量 根据优化模式选择 /D_DEBUG 或 /DNDEBUG

include_paths: []const LazyPath = &.{}

可能尚未存在的头文件路径,因此需指定为 LazyPath。 每个路径将以 /I <resolved path> 的形式追加到标志中。

std.Build.Module.RcSourceFile.dupe

函数

第 153 行

pub fn dupe(file: RcSourceFile, graph: *const std.Build.Graph) RcSourceFile

参数

file: RcSourceFile
graph: *const std.Build.Graph

std.Build.Module.requireKnownTarget

函数

第 551 行

fn requireKnownTarget(m: *Module) *const std.Target

参数

m: *Module

std.Build.Module.RPath

容器

第 54 行

字段

lazy_path: LazyPath
special: []const u8

std.Build.Module.std

别名

第 3 行

别名目标 std

std.Build.Module.Step

别名

第 6 行

别名目标 std.Build.Step

std.Build.Module.SystemLib

容器

第 71 行

字段

name: []const u8
needed: bool
weak: bool
use_pkg_config: UsePkgConfig
preferred_link_mode: std.builtin.LinkMode
search_strategy: SystemLib.SearchStrategy

std.Build.Module.SystemLib.SearchStrategy

别名

第 80 行

别名目标 std.Build.Configuration.SystemLib.SearchStrategy

std.Build.Module.SystemLib.UsePkgConfig

别名

第 79 行

别名目标 std.Build.Configuration.SystemLib.UsePkgConfig

源码

std/Build/Module.zig

const Module = @This();

const std = @import("std");
const assert = std.debug.assert;
const LazyPath = std.Build.LazyPath;
const Step = std.Build.Step;
const ArrayList = std.ArrayList;

/// 负责创建此模块的对象。
owner: *std.Build,
root_source_file: ?LazyPath,
/// 映射到此模块导入表中的模块。
/// 请使用 `addImport` 修改,而不要直接修改此字段,
/// 以保持步骤依赖边。
import_table: std.array_hash_map.String(*Module),

resolved_target: ?std.Build.ResolvedTarget = null,
optimize: ?std.builtin.Optimize = null,
dwarf_format: ?std.dwarf.Format,

c_macros: ArrayList([]const u8),
include_dirs: ArrayList(IncludeDir),
lib_paths: ArrayList(LazyPath),
rpaths: ArrayList(RPath),
frameworks: std.array_hash_map.String(LinkFrameworkOptions),
link_objects: ArrayList(LinkObject),

strip: ?bool,
unwind_tables: ?std.builtin.UnwindTables,
single_threaded: ?bool,
stack_protector: ?bool,
stack_check: ?bool,
sanitize_c: ?std.zig.SanitizeC,
sanitize_thread: ?bool,
fuzz: ?bool,
code_model: std.builtin.CodeModel,
valgrind: ?bool,
pic: ?bool,
red_zone: ?bool,
omit_frame_pointer: ?bool,
error_tracing: ?bool,
link_libc: ?bool,
link_libcpp: ?bool,
no_builtin: ?bool,
patchable_function_entry: u16,

/// 编译为 WebAssembly 时要导出的符号。
export_symbol_names: []const []const u8 = &.{},

/// 缓存多次调用 `getGraph` 时的结果。
/// 请使用 `getGraph`,不要直接访问此字段。
cached_graph: Graph = .{ .modules = &.{}, .names = &.{} },

pub const RPath = union(enum) {
    lazy_path: LazyPath,
    special: []const u8,
};

pub const LinkObject = union(enum) {
    static_path: LazyPath,
    other_step: *Step.Compile,
    system_lib: SystemLib,
    assembly_file: LazyPath,
    c_source_file: *CSourceFile,
    c_source_files: *CSourceFiles,
    /// 已弃用。此功能将移至外部包:
    /// https://codeberg.org/ziglang/rc
    win32_resource_file: *RcSourceFile,
};

pub const SystemLib = struct {
    name: []const u8,
    needed: bool,
    weak: bool,
    use_pkg_config: UsePkgConfig,
    preferred_link_mode: std.builtin.LinkMode,
    search_strategy: SystemLib.SearchStrategy,

    pub const UsePkgConfig = std.Build.Configuration.SystemLib.UsePkgConfig;
    pub const SearchStrategy = std.Build.Configuration.SystemLib.SearchStrategy;
};

pub const CSourceLanguage = enum {
    c,
    cpp,

    objective_c,
    objective_cpp,

    /// 标准汇编
    assembly,
    /// 使用 C 预处理器的汇编
    assembly_with_preprocessor,

    /// 传递给 Clang 命令行选项 "-x" 的值。
    pub fn clangIdentifier(self: CSourceLanguage) [:0]const u8 {
        return switch (self) {
            .c => "c",
            .cpp => "c++",
            .objective_c => "objective-c",
            .objective_cpp => "objective-c++",
            .assembly => "assembler",
            .assembly_with_preprocessor => "assembler-with-cpp",
        };
    }
};

pub const CSourceFiles = struct {
    root: LazyPath,
    /// `files` 相对于 `root`,
    /// 后者默认为构建根目录。
    files: []const []const u8,
    flags: []const []const u8,
    /// 默认根据各文件的扩展名,分别确定其语言
    language: ?CSourceLanguage,
};

pub const CSourceFile = struct {
    file: LazyPath,
    flags: []const []const u8 = &.{},
    /// 默认根据各文件的扩展名,分别确定其语言
    language: ?CSourceLanguage = null,

    pub fn dupe(file: CSourceFile, graph: *const std.Build.Graph) CSourceFile {
        return .{
            .file = file.file.dupe(graph),
            .flags = graph.dupeStrings(file.flags),
            .language = file.language,
        };
    }
};

/// 已弃用。此功能将移至外部包:
/// https://codeberg.org/ziglang/rc
pub const RcSourceFile = struct {
    file: LazyPath,
    /// rc.exe 接受的选项均可用于此处,但以下选项除外:
    /// - `/fo`:输出文件名由构建系统设置
    /// - `/p`:此上下文不支持仅运行预处理器
    /// - `/:no-preprocess`,非标准选项:此上下文不支持
    /// - 任何与 MUI 相关的选项
    /// https://learn.microsoft.com/en-us/windows/win32/menurc/using-rc-the-rc-command-line-
    ///
    /// 隐式定义的选项:
    ///  /x,忽略 INCLUDE 环境变量
    ///  根据优化模式选择 /D_DEBUG 或 /DNDEBUG
    flags: []const []const u8 = &.{},
    /// 可能尚未存在的头文件路径,因此需指定为 LazyPath。
    /// 每个路径将以 `/I <resolved path>` 的形式追加到标志中。
    ///
    include_paths: []const LazyPath = &.{},

    pub fn dupe(file: RcSourceFile, graph: *const std.Build.Graph) RcSourceFile {
        return .{
            .file = file.file.dupe(graph),
            .flags = graph.dupeStrings(file.flags),
            .include_paths = LazyPath.dupeList(file.include_paths, graph),
        };
    }
};

pub const IncludeDir = union(enum) {
    path: LazyPath,
    path_system: LazyPath,
    path_after: LazyPath,
    framework_path: LazyPath,
    framework_path_system: LazyPath,
    other_step: *Step.Compile,
    config_header_step: *Step.ConfigHeader,
    embed_path: LazyPath,
};

pub const LinkFrameworkOptions = struct {
    /// 无论是否实际依赖动态库,都链接它们。
    /// 为 false 时,链接器会省略那些
    /// 没有任何符号被引用的动态库。
    needed: bool = false,
    /// 将此库中所有被引用的符号标记为弱符号。这意味着,若另一个编译单元提供同名符号,链接器不会报告“符号重复”错误,而会将所有对该符号的引用解析到强符号版本。
    ///
    /// 链接器遇到两个弱符号时,根据编译单元传给链接器的顺序选择,后提供的优先。
    ///
    ///
    ///
    ///
    ///
    weak: bool = false,
};

/// 插入导入表时,此处未指定的选项
/// 将从父级 `Module` 继承。
pub const CreateOptions = struct {
    /// 可以是生成文件,此时模块恰好包含一个文件;
    /// 也可以是组成该模块的文件目录中
    /// 根源文件的路径。
    /// 若为 `null`,表示此模块仅由 `link_objects` 构成。
    root_source_file: ?LazyPath = null,

    /// 此模块可通过 `@import` 访问的其他模块的映射表。
    /// 允许循环导入,因此在创建 `Module` 后,
    /// 仍可通过 `addImport` 向此表添加条目。
    imports: []const Import = &.{},

    target: ?std.Build.ResolvedTarget = null,
    optimize: ?std.builtin.Optimize = null,

    /// `true` 要求包含此 Module 的编译链接 libc。
    /// `false` 会在包含此 Module 的编译将链接 libc 时导致构建失败。
    /// `null` 既不要求也不阻止链接 libc。
    link_libc: ?bool = null,
    /// `true` 要求包含此 Module 的编译链接 libc++。
    /// `false` 使包含此 Module 且会链接 libc++ 的编译构建失败。
    /// `null` 既不要求也不阻止链接 libc++。
    link_libcpp: ?bool = null,
    single_threaded: ?bool = null,
    strip: ?bool = null,
    unwind_tables: ?std.builtin.UnwindTables = null,
    dwarf_format: ?std.dwarf.Format = null,
    code_model: std.builtin.CodeModel = .default,
    stack_protector: ?bool = null,
    stack_check: ?bool = null,
    sanitize_c: ?std.zig.SanitizeC = null,
    sanitize_thread: ?bool = null,
    fuzz: ?bool = null,
    /// 是否生成与 Valgrind 集成的机器码。
    valgrind: ?bool = null,
    /// 位置无关代码
    pic: ?bool = null,
    red_zone: ?bool = null,
    /// 是否省略栈帧指针。可以释放一个寄存器,但更难获取栈轨迹。
    /// 效果取决于目标。
    omit_frame_pointer: ?bool = null,
    error_tracing: ?bool = null,
    no_builtin: ?bool = null,
    patchable_function_entry: u16 = 0,
};

pub const Import = struct {
    name: []const u8,
    module: *Module,
};

pub fn init(
    m: *Module,
    owner: *std.Build,
    value: union(enum) { options: CreateOptions, existing: *const Module },
) void {
    const graph = owner.graph;
    const arena = graph.arena;

    switch (value) {
        .options => |options| {
            m.* = .{
                .owner = owner,
                .root_source_file = if (options.root_source_file) |lp| lp.dupe(graph) else null,
                .import_table = .empty,
                .resolved_target = options.target,
                .optimize = options.optimize,
                .link_libc = options.link_libc,
                .link_libcpp = options.link_libcpp,
                .dwarf_format = options.dwarf_format,
                .c_macros = .empty,
                .include_dirs = .empty,
                .lib_paths = .empty,
                .rpaths = .empty,
                .frameworks = .empty,
                .link_objects = .empty,
                .strip = options.strip,
                .unwind_tables = options.unwind_tables,
                .single_threaded = options.single_threaded,
                .stack_protector = options.stack_protector,
                .stack_check = options.stack_check,
                .sanitize_c = options.sanitize_c,
                .sanitize_thread = options.sanitize_thread,
                .fuzz = options.fuzz,
                .code_model = options.code_model,
                .valgrind = options.valgrind,
                .pic = options.pic,
                .red_zone = options.red_zone,
                .omit_frame_pointer = options.omit_frame_pointer,
                .error_tracing = options.error_tracing,
                .export_symbol_names = &.{},
                .no_builtin = options.no_builtin,
                .patchable_function_entry = options.patchable_function_entry,
            };

            m.import_table.ensureUnusedCapacity(arena, options.imports.len) catch @panic("OOM");
            for (options.imports) |dep| {
                m.import_table.putAssumeCapacity(dep.name, dep.module);
            }
        },
        .existing => |existing| {
            m.* = existing.*;
        },
    }
}

pub fn create(owner: *std.Build, options: CreateOptions) *Module {
    const graph = owner.graph;
    const arena = graph.arena;
    const m = arena.create(Module) catch @panic("OOM");
    m.init(owner, .{ .options = options });
    return m;
}

/// 添加一个现有模块,以供 `@import` 使用。
pub fn addImport(m: *Module, name: []const u8, module: *Module) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.import_table.put(arena, graph.dupeString(name), module) catch @panic("OOM");
}

/// 创建新模块,并将其添加为可通过 `@import` 使用的模块。
pub fn addAnonymousImport(m: *Module, name: []const u8, options: CreateOptions) void {
    const module = create(m.owner, options);
    return addImport(m, name, module);
}

/// 将一组键值对转换为 Zig 源码文件,然后以指定名称加入
/// Module 的导入表。这样即可通过
/// `@import("module_name")` 导入这些选项。
pub fn addOptions(m: *Module, module_name: []const u8, options: *Step.Options) void {
    addImport(m, module_name, options.createModule());
}

pub const LinkSystemLibraryOptions = struct {
    /// 无论是否实际依赖动态库,都链接它们。
    /// 为 false 时,链接器会省略那些
    /// 没有任何符号被引用的动态库。
    needed: bool = false,
    /// 将此库中所有被引用的符号标记为弱符号。这意味着,若另一个编译单元提供同名符号,链接器不会报告“符号重复”错误,而会将所有对该符号的引用解析到强符号版本。
    ///
    /// 链接器遇到两个弱符号时,根据编译单元传给链接器的顺序选择,后提供的优先。
    ///
    ///
    ///
    ///
    ///
    weak: bool = false,
    use_pkg_config: SystemLib.UsePkgConfig = .yes,
    preferred_link_mode: std.builtin.LinkMode = .dynamic,
    search_strategy: SystemLib.SearchStrategy = .paths_first,
};

pub fn linkSystemLibrary(
    m: *Module,
    name: []const u8,
    options: LinkSystemLibraryOptions,
) void {
    const graph = m.owner.graph;
    const arena = graph.arena;

    const target = m.requireKnownTarget();
    if (std.zig.target.isLibCLibName(target, name)) {
        m.link_libc = true;
        return;
    }
    if (std.zig.target.isLibCxxLibName(target, name)) {
        m.link_libcpp = true;
        return;
    }

    m.link_objects.append(arena, .{
        .system_lib = .{
            .name = graph.dupeString(name),
            .needed = options.needed,
            .weak = options.weak,
            .use_pkg_config = options.use_pkg_config,
            .preferred_link_mode = options.preferred_link_mode,
            .search_strategy = options.search_strategy,
        },
    }) catch @panic("OOM");
}

pub fn linkFramework(m: *Module, name: []const u8, options: LinkFrameworkOptions) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.frameworks.put(arena, graph.dupeString(name), options) catch @panic("OOM");
}

pub const AddCSourceFilesOptions = struct {
    /// 若提供 `root`,则 `files` 相对于它,而非
    /// 拥有 `Compile` 步骤的程序包。
    root: ?LazyPath = null,
    files: []const []const u8,
    flags: []const []const u8 = &.{},
    /// 默认根据各文件的扩展名,分别确定其语言
    language: ?CSourceLanguage = null,
};

/// 当存在许多非 Zig 源文件且希望它们使用相同标志时很有用。
pub fn addCSourceFiles(m: *Module, options: AddCSourceFilesOptions) void {
    const b = m.owner;
    const graph = m.owner.graph;
    const arena = graph.arena;

    for (options.files) |path| {
        if (std.fs.path.isAbsolute(path)) {
            std.debug.panic(
                "file paths added with 'addCSourceFiles' must be relative, found absolute path '{s}'",
                .{path},
            );
        }
    }

    const c_source_files = arena.create(CSourceFiles) catch @panic("OOM");
    c_source_files.* = .{
        .root = options.root orelse b.path(""),
        .files = b.graph.dupeStrings(options.files),
        .flags = b.graph.dupeStrings(options.flags),
        .language = options.language,
    };
    m.link_objects.append(arena, .{ .c_source_files = c_source_files }) catch @panic("OOM");
}

pub fn addCSourceFile(m: *Module, source: CSourceFile) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    const c_source_file = arena.create(CSourceFile) catch @panic("OOM");
    c_source_file.* = source.dupe(graph);
    m.link_objects.append(arena, .{ .c_source_file = c_source_file }) catch @panic("OOM");
}

/// 已弃用。此功能将移至外部软件包:
/// https://codeberg.org/ziglang/rc
///
/// 资源文件必须使用扩展名 `.rc`。
/// 可针对任意目标调用。如果目标文件格式不支持嵌入资源,
/// 则忽略 .rc 文件。
pub fn addWin32ResourceFile(m: *Module, source: RcSourceFile) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    const target = m.requireKnownTarget();
    // 只有 PE/COFF 格式具有资源表,因此对于其他目标
    // 会忽略资源文件。
    if (target.ofmt != .coff) return;

    const rc_source_file = arena.create(RcSourceFile) catch @panic("OOM");
    rc_source_file.* = source.dupe(graph);
    m.link_objects.append(arena, .{ .win32_resource_file = rc_source_file }) catch @panic("OOM");
}

pub fn addAssemblyFile(m: *Module, source: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.link_objects.append(arena, .{ .assembly_file = source.dupe(graph) }) catch @panic("OOM");
}

pub fn addObjectFile(m: *Module, object: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.link_objects.append(arena, .{ .static_path = object.dupe(graph) }) catch @panic("OOM");
}

pub fn addObject(m: *Module, object: *Step.Compile) void {
    assert(object.kind == .obj or object.kind == .test_obj);
    m.linkLibraryOrObject(object);
}

pub fn linkLibrary(m: *Module, library: *Step.Compile) void {
    assert(library.kind == .lib);
    m.linkLibraryOrObject(library);
}

pub fn addAfterIncludePath(m: *Module, lazy_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .path_after = lazy_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addSystemIncludePath(m: *Module, lazy_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .path_system = lazy_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addIncludePath(m: *Module, lazy_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .path = lazy_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addConfigHeader(m: *Module, config_header: *Step.ConfigHeader) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .config_header_step = config_header }) catch @panic("OOM");
}

pub fn addSystemFrameworkPath(m: *Module, directory_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .framework_path_system = directory_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addFrameworkPath(m: *Module, directory_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .framework_path = directory_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addEmbedPath(m: *Module, lazy_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .embed_path = lazy_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addLibraryPath(m: *Module, directory_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.lib_paths.append(arena, directory_path.dupe(graph)) catch @panic("OOM");
}

pub fn addRPath(m: *Module, directory_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.rpaths.append(arena, .{ .lazy_path = directory_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addRPathSpecial(m: *Module, bytes: []const u8) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.rpaths.append(arena, .{ .special = graph.dupeString(bytes) }) catch @panic("OOM");
}

/// 等同于对属于此 `Module` 的所有 C 源码文件
/// 应用以下 C 代码:
/// ```c
/// #define name value
/// ```
/// `name` 和 `value` 的生命周期无需超过函数调用。
pub fn addCMacro(m: *Module, name: []const u8, value: []const u8) void {
    const b = m.owner;
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.c_macros.append(arena, b.fmt("-D{s}={s}", .{ name, value })) catch @panic("OOM");
}

fn linkLibraryOrObject(m: *Module, other: *Step.Compile) void {
    const graph = m.owner.graph;
    const arena = graph.arena;

    _ = other.getEmittedBin(); // 表示依赖于输出的二进制文件。

    if (other.rootModuleTarget().os.tag == .windows and other.isDynamicLibrary()) {
        _ = other.getEmittedImplib(); // 表示依赖输出的 implib。
    }

    m.link_objects.append(arena, .{ .other_step = other }) catch @panic("OOM");
    m.include_dirs.append(arena, .{ .other_step = other }) catch @panic("OOM");
}

fn requireKnownTarget(m: *Module) *const std.Target {
    const resolved_target = &(m.resolved_target orelse
        @panic("this API requires the Module to be created with a known 'target' field"));
    return &resolved_target.result;
}

/// `modules` 与 `names` 的元素一一对应。
pub const Graph = struct {
    modules: []const *Module,
    names: []const []const u8,
};

/// 给定编译的根 `Module` 为 `root`,返回模块图中的
/// 全部 `Module`,包括 `root` 本身。保证 `root`
/// 为返回切片中的首个模块。
pub fn getGraph(root: *Module) Graph {
    if (root.cached_graph.modules.len != 0) {
        return root.cached_graph;
    }

    const arena = root.owner.graph.arena;

    var modules: std.array_hash_map.Auto(*std.Build.Module, []const u8) = .empty;
    var next_idx: usize = 0;

    modules.putNoClobber(arena, root, "root") catch @panic("OOM");

    while (next_idx < modules.count()) {
        const mod = modules.keys()[next_idx];
        next_idx += 1;
        modules.ensureUnusedCapacity(arena, mod.import_table.count()) catch @panic("OOM");
        for (mod.import_table.keys(), mod.import_table.values()) |import_name, other_mod| {
            modules.putAssumeCapacity(other_mod, import_name);
        }
    }

    const result: Graph = .{
        .modules = modules.keys(),
        .names = modules.values(),
    };
    root.cached_graph = result;
    return result;
}