跳转到内容

std.Build.Step.Compile

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

第 1 行

字段

step: Step
root_module: *Module
name: []const u8
linker_script: ?LazyPath = null
version_script: ?LazyPath = null
out_filename: []const u8

已弃用。

linkage: ?std.builtin.LinkMode = null
version: ?std.SemanticVersion
kind: Kind
formatted_panics: ?bool = null
compress_debug_sections: std.zig.CompressDebugSections = .none
verbose_link: bool
verbose_cc: bool
bundle_compiler_rt: ?bool = null
bundle_ubsan_rt: ?bool = null
rdynamic: bool
import_memory: bool = false
export_memory: bool = false
import_symbols: bool = false

对于 WebAssembly 目标,允许从宿主环境 导入未定义符号。

import_table: bool = false

(WebAssembly)从宿主环境导入函数表

export_table: bool = false
growable_table: bool = false
initial_memory: ?u64 = null
max_memory: ?u64 = null
shared_memory: bool = false
global_base: ?u64 = null
zig_lib_dir: ?LazyPath

通过选项设置;之后预期仅供读取。

filters: []const []const u8
test_runner: ?TestRunner
wasi_exec_model: ?std.builtin.WasiExecModel = null
installed_headers: std.ArrayList(HeaderInstallation)
installed_headers_include_tree: ?*Step.WriteFile = null

此步骤用于创建头文件树,依赖模块可将其添加到头文件搜索路径。 已安装的头文件会复制到此步骤。 仅当某模块首次与此产物链接时创建此步骤, 其他情况下不创建。

rc_includes: std.zig.RcIncludes = .any

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

编译 .rc 文件时自动检测包含目录的行为。 any:优先使用可用的 MSVC,否则回退到 MinGW。 msvc:使用 MSVC 包含路径,系统上必须已安装。 gnu:使用随 Zig 分发的 MinGW 包含路径。 none:不使用任何自动检测的包含路径。

win32_manifest: ?LazyPath = null

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

(Windows)要嵌入编译结果的 .manifest 文件。 通过选项设置;之后应仅供读取。

win32_module_definition: ?LazyPath = null

(Windows)要嵌入编译产物(dll)的 .def 文件。 通过选项设置,此后应视为只读。

image_base: ?u64 = null

可执行映像的基地址。

libc_file: ?LazyPath = null
each_lib_rpath: ?bool = null
build_id: ?std.zig.BuildId = null

ELF 目标上会生成名为 ".note.gnu.build-id" 的链接节, 用于将剥离符号后的二进制文件与其调试符号对应起来。

例如,bloaty 项目要求输入必须具有 构建标识,否则拒绝处理,以避免意外不匹配。

默认不包含此节,因为会降低链接速度。

此选项覆盖传给 zig build 的命令行参数。

link_eh_frame_hdr: bool = false

在 ELF 文件中创建 .eh_frame_hdr 节 及 PT.GNU_EH_FRAME 段。

link_emit_relocs: bool = false
link_function_sections: bool = false

将每个函数放在独立节中,使未使用的函数可在 链接阶段安全地回收。

link_data_sections: bool = false

将每份数据放入各自的节,使链接阶段 可以安全回收未使用的数据。

link_gc_sections: ?bool = null

移除从入口点或导出符号 不可达的函数和数据。

linker_dynamicbase: bool = true

(Windows)是否启用 ASLR。映射到 /DYNAMICBASE[:NO] 链接器参数。

linker_allow_shlib_undefined: ?bool = null
linker_allow_undefined_version: ?bool = null

允许版本脚本引用未定义符号。

linker_enable_new_dtags: ?bool = null
link_z_notext: bool = false

允许只读段中的只读重定位。默认不允许。

link_z_relro: bool = true

强制在处理后将所有重定位设为只读。

link_z_lazy: bool = false

允许在加载后延迟处理重定位。

link_z_common_page_size: ?u64 = null

常用页面大小

link_z_max_page_size: ?u64 = null

最大页大小

link_z_defs: bool = false

若仍存在任何未定义符号,则强制产生致命错误。

install_name: ?[]const u8 = null

(Darwin)dylib 的安装名称

entitlements: ?LazyPath = null

必须通过 Options 传入。

pagezero_size: ?u64 = null

(Darwin)pagezero 段的大小。

headerpad_size: ?u32 = null

(Darwin)设置加载命令末尾与 __TEXT,__text 节起始位置之间的填充大小。

headerpad_max_install_names: bool = false

(Darwin)自动设置加载命令末尾与 __TEXT,__text 节开头 之间的填充大小,使其足以容纳所有扩展到 MAXPATHLEN 的路径。

dead_strip_dylibs: bool = false

(Darwin)移除从入口点或导出符号不可达的动态库。

force_load_objc: bool = false

(Darwin)强制加载静态归档中实现 Objective-C 类或分类的所有成员。

discard_local_symbols: bool = false

是否从符号表中丢弃局部符号。

pie: ?bool = null

位置无关可执行文件

lto: ?std.zig.LtoMode = null

链接时优化模式

dll_export_fns: ?bool = null
subsystem: ?std.zig.Subsystem = null
mingw_unicode_entry_point: bool = false

(Windows)目标为 MinGW ABI 时,使用 Unicode 入口点(wmain/wWinMain)

entry: Entry = .default

链接器必须如何处理可执行文件的入口点。

force_undefined_symbols: std.array_hash_map.String(void)

在符号表中强制设为未定义的符号列表, 从而强制链接器解析这些符号。 ELF/MachO 对应 -u <symbol>,COFF/PE 对应 /include:<symbol>。

stack_size: ?u64 = null

覆盖默认栈大小

use_llvm: ?bool
use_lld: ?bool
use_new_linker: ?bool
allow_so_scripts: ?bool = null

对应 -fallow-so-scripts / -fno-allow-so-scripts 命令行 标志,覆盖传递给 zig build 命令的全局用户设置。

编译器默认关闭此选项,使系统共享库 全部为 ELF 文件的用户无需承担逐个检查 文件是否为文本文件的开销。

expect_errors: ?ExpectedCompileErrors = null

此高级设置可以改变本 Compile 步骤的用途。 若此值非 null,表示此 Compile 步骤用于 检查编译错误;若与预期匹配,则返回成功, 否则返回失败。

error_limit: ?u32 = null

单个编译步骤中不同错误的最大数量,默认为 std.math.maxInt(u16)。覆盖传给 zig build 的参数。

sanitize_coverage_trace_pc_guard: ?bool = null

启用一种覆盖率插桩,仅在使用依赖它的第三方模糊测试器时有用。否则只会增加不必要的函数调用,拖慢插桩后的二进制程序。

AFLplusplus v4.21c 使用此类覆盖率插桩;但包括 Zig 在内的现代模糊测试器已经改用“内联 8 位计数器”或“内联布尔标志”,覆盖率记录仅需一条指令,并结合“trace cmp”对比较操作插桩、报告其操作数。

若要使用 Zig 内置模糊测试器对一次编译启用模糊测试插桩,请参见 fuzz 标志,位于 Module 中。

incremental: ?bool = null

启用或禁用增量编译。

增量编译通过修改现有构建产物来减少编译时间。 非增量编译较慢,但会保留先前的构建产物。

emit_directory: Configuration.OptionalGeneratedFileIndex = .none
generated_docs: Configuration.OptionalGeneratedFileIndex = .none
generated_asm: Configuration.OptionalGeneratedFileIndex = .none
generated_bin: Configuration.OptionalGeneratedFileIndex = .none
generated_pdb: Configuration.OptionalGeneratedFileIndex = .none
generated_implib: Configuration.OptionalGeneratedFileIndex = .none
generated_llvm_bc: Configuration.OptionalGeneratedFileIndex = .none
generated_llvm_ir: Configuration.OptionalGeneratedFileIndex = .none
generated_h: Configuration.OptionalGeneratedFileIndex = .none

std.Build.Step.Compile.addHeaderInstallationToIncludeTree

函数

第 531 行

fn addHeaderInstallationToIncludeTree(cs: *Compile, installation: HeaderInstallation) void

参数

cs: *Compile
installation: HeaderInstallation

std.Build.Step.Compile.addObjCopy

函数

第 558 行

pub fn addObjCopy(cs: *Compile, options: Step.ObjCopy.Options) *Step.ObjCopy

参数

cs: *Compile
options: Step.ObjCopy.Options

std.Build.Step.Compile.Allocator

别名

第 12 行

别名目标 std.mem.Allocator

std.Build.Step.Compile.assert

别名

第 9 行

别名目标 std.debug.assert

std.Build.Step.Compile.base_tag

常量

第 20 行

Step.Tag

std.Build.Step.Compile.builtin

常量

第 3 行

std.Build.Step.Compile.Compile

别名

第 1 行

别名目标 std.Build.Step.Compile

std.Build.Step.Compile.Configuration

别名

第 18 行

别名目标 std.Build.Configuration

std.Build.Step.Compile.create

函数

第 370 行

pub fn create(owner: *std.Build, options: Options) *Compile

参数

owner: *std.Build
options: Options

std.Build.Step.Compile.dependsOnSystemLibrary

函数

第 591 行

返回库、可执行文件或对象是否依赖某个系统库。 包含传递依赖。

pub fn dependsOnSystemLibrary(compile: *Compile, name: []const u8) bool

参数

compile: *Compile
name: []const u8

std.Build.Step.Compile.Entry

容器

第 261 行

字段

default

让编译器决定是否创建入口点以及入口点的名称。

disabled

可执行文件将没有入口点。

enabled

可执行文件将具有采用默认符号名称的入口点。

symbol_name: []const u8

可执行文件的入口点将使用指定符号名。

std.Build.Step.Compile.ExpectedCompileErrors

容器

第 254 行

字段

contains: []const u8
exact: []const []const u8
starts_with: []const u8
stderr_contains: []const u8

std.Build.Step.Compile.forceUndefinedSymbol

函数

第 583 行

pub fn forceUndefinedSymbol(compile: *Compile, symbol_name: []const u8) void

参数

compile: *Compile
symbol_name: []const u8

std.Build.Step.Compile.fs

别名

第 8 行

别名目标 std.fs

std.Build.Step.Compile.getCompileDependencies

函数

第 751 行

返回 start 递归依赖的全部 Step.Compile。start 本身 始终作为首个元素返回。如果 chase_dynamic 为 false,不包括动态库, 也不考虑其依赖;如果 chase_dynamic 为 true,则将动态库 与其他链接的 Compile 一样处理。

pub fn getCompileDependencies(start: *Compile, chase_dynamic: bool) []const *Compile

参数

start: *Compile
chase_dynamic: bool

std.Build.Step.Compile.getEmittedAsm

函数

第 728 行

返回生成的汇编代码的路径。

pub fn getEmittedAsm(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.getEmittedBin

函数

第 696 行

返回生成的可执行文件、库或对象文件路径。 要运行由 zig build 构建的可执行文件,请使用 run,或创建安装步骤并调用它。

pub fn getEmittedBin(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.getEmittedBinDirectory

函数

第 689 行

返回包含所生成二进制文件的目录路径。

pub fn getEmittedBinDirectory(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.getEmittedDocs

函数

第 723 行

返回生成的文档目录的路径。

pub fn getEmittedDocs(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.getEmittedFileGeneric

函数

第 680 行

fn getEmittedFileGeneric(compile: *Compile, output_file: *Configuration.OptionalGeneratedFileIndex) LazyPath

参数

std.Build.Step.Compile.getEmittedH

函数

第 709 行

返回生成的头文件路径。 此函数只能针对库或目标文件调用。

pub fn getEmittedH(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.getEmittedImplib

函数

第 702 行

返回生成的导入库的路径。 此函数只能针对库调用。

pub fn getEmittedImplib(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.getEmittedIncludeTree

函数

第 545 行

pub fn getEmittedIncludeTree(cs: *Compile) LazyPath

参数

cs: *Compile

std.Build.Step.Compile.getEmittedLlvmBc

函数

第 738 行

返回生成的 LLVM BC 的路径。

pub fn getEmittedLlvmBc(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.getEmittedLlvmIr

函数

第 733 行

返回生成的 LLVM 中间表示的路径。

pub fn getEmittedLlvmIr(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.getEmittedPdb

函数

第 717 行

返回生成的 PDB 文件。 如果编译不产生 PDB 文件,则会在构建时 引发 FileNotFound 错误。

pub fn getEmittedPdb(compile: *Compile) LazyPath

参数

compile: *Compile

std.Build.Step.Compile.HeaderInstallation

容器

第 302 行

字段

file: File
directory: Directory

std.Build.Step.Compile.HeaderInstallation.Directory

容器

第 318 行

字段

source: LazyPath
dest_rel_path: []const u8
options: Directory.Options

std.Build.Step.Compile.HeaderInstallation.Directory.dupe

函数

第 339 行

pub fn dupe(dir: Directory, graph: *const std.Build.Graph) Directory

参数

dir: Directory
graph: *const std.Build.Graph

std.Build.Step.Compile.HeaderInstallation.Directory.Options

容器

第 323 行

字段

exclude_extensions: []const []const u8 = &.{}

以这些后缀中任意一个结尾的文件路径将被排除,不予安装。

include_extensions: ?[]const []const u8 = &.{".h"}

仅将以这些后缀之一结尾的文件路径纳入安装。 null 表示包含所有后缀。 exclude_extensions 优先于 include_extensions。

std.Build.Step.Compile.HeaderInstallation.Directory.Options.dupe

函数

第 331 行

pub fn dupe(opts: Directory.Options, graph: *const std.Build.Graph) Directory.Options

参数

opts: Directory.Options
graph: *const std.Build.Graph

std.Build.Step.Compile.HeaderInstallation.dupe

函数

第 354 行

pub fn dupe(installation: HeaderInstallation, graph: *const std.Build.Graph) HeaderInstallation

参数

installation: HeaderInstallation
graph: *const std.Build.Graph

std.Build.Step.Compile.HeaderInstallation.File

容器

第 306 行

字段

source: LazyPath
dest_rel_path: []const u8

std.Build.Step.Compile.HeaderInstallation.File.dupe

函数

第 310 行

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

参数

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

std.Build.Step.Compile.HeaderInstallation.getSource

函数

第 348 行

pub fn getSource(installation: HeaderInstallation) LazyPath

参数

installation: HeaderInstallation

std.Build.Step.Compile.installConfigHeader

函数

第 512 行

将指定配置头文件标记为与此产物一同安装。 模块链接此产物时,所有标记为安装的头文件都会加入该 模块的包含文件搜索路径。

pub fn installConfigHeader(cs: *Compile, config_header: *Step.ConfigHeader) void

参数

cs: *Compile
config_header: *Step.ConfigHeader

std.Build.Step.Compile.InstallDir

别名

第 16 行

别名目标 std.Build.InstallDir

std.Build.Step.Compile.installHeader

函数

第 476 行

将指定头文件标记为与此产物一同安装。 模块链接此产物时,所有标记为安装的头文件都会加入该 模块的包含文件搜索路径。

pub fn installHeader(cs: *Compile, source: LazyPath, dest_rel_path: []const u8) void

参数

cs: *Compile
source: LazyPath
dest_rel_path: []const u8

std.Build.Step.Compile.installHeadersDirectory

函数

第 491 行

将指定目录中的头文件标记为与此产物一同安装。 模块链接此产物时,所有标记为安装的头文件都会加入该 模块的包含文件搜索路径。

pub fn installHeadersDirectory( cs: *Compile, source: LazyPath, dest_rel_path: []const u8, options: HeaderInstallation.Directory.Options, ) void

参数

cs: *Compile
source: LazyPath
dest_rel_path: []const u8
options: HeaderInstallation.Directory.Options

std.Build.Step.Compile.installLibraryHeaders

函数

第 519 行

将 lib 中所有标记为安装的头文件转发到此产物。 模块与此产物链接时,所有标记为安装的头文件都会加入 该模块的头文件搜索路径。

pub fn installLibraryHeaders(cs: *Compile, lib: *Compile) void

参数

cs: *Compile
lib: *Compile

std.Build.Step.Compile.Io

别名

第 6 行

别名目标 std.Io

std.Build.Step.Compile.isDll

函数

第 629 行

pub fn isDll(compile: *Compile) bool

参数

compile: *Compile

std.Build.Step.Compile.isDynamicLibrary

函数

第 621 行

pub fn isDynamicLibrary(compile: *const Compile) bool

参数

compile: *const Compile

std.Build.Step.Compile.isStaticLibrary

函数

第 625 行

pub fn isStaticLibrary(compile: *const Compile) bool

参数

compile: *const Compile

std.Build.Step.Compile.Kind

别名

第 300 行

别名目标 std.Build.Configuration.Step.Compile.Kind

std.Build.Step.Compile.LazyPath

别名

第 14 行

别名目标 std.Build.LazyPath

std.Build.Step.Compile.mem

别名

第 7 行

别名目标 std.mem

std.Build.Step.Compile.Module

别名

第 15 行

别名目标 std.Build.Module

std.Build.Step.Compile.Options

容器

第 273 行

字段

name: []const u8
root_module: *Module
kind: Kind
linkage: ?std.builtin.LinkMode = null
version: ?std.SemanticVersion = null
max_rss: u64 = 0
filters: []const []const u8 = &.{}
test_runner: ?TestRunner = null
use_llvm: ?bool = null
use_lld: ?bool = null
zig_lib_dir: ?LazyPath = null
win32_manifest: ?LazyPath = null

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

若目标文件格式支持,在编译结果中嵌入 .manifest 文件。 https://learn.microsoft.com/en-us/windows/win32/sbscs/manifest-files-reference 清单文件必须具有 .manifest 扩展名。 无论目标为何均可设置。若目标文件格式不支持嵌入清单,则忽略 .manifest 文件。

win32_module_definition: ?LazyPath = null

Win32 模块定义文件。

entitlements: ?LazyPath = null

(Darwin)权限文件路径

std.Build.Step.Compile.panic

别名

第 10 行

别名目标 std.debug.panic

std.Build.Step.Compile.Path

别名

第 17 行

别名目标 std.Build.Cache.Path

std.Build.Step.Compile.producesCompilerRtDynLib

函数

第 651 行

pub fn producesCompilerRtDynLib(compile: *Compile) bool

参数

compile: *Compile

std.Build.Step.Compile.producesImplib

函数

第 658 行

pub fn producesImplib(compile: *Compile) bool

参数

compile: *Compile

std.Build.Step.Compile.producesPdbFile

函数

第 633 行

pub fn producesPdbFile(compile: *Compile) bool

参数

compile: *Compile

std.Build.Step.Compile.rootModuleTarget

函数

第 742 行

pub fn rootModuleTarget(c: *Compile) std.Target

参数

c: *Compile

std.Build.Step.Compile.setLibCFile

函数

第 670 行

pub fn setLibCFile(compile: *Compile, libc_file: ?LazyPath) void

参数

compile: *Compile
libc_file: ?LazyPath

std.Build.Step.Compile.setLinkerScript

函数

第 571 行

pub fn setLinkerScript(compile: *Compile, source: LazyPath) void

参数

compile: *Compile
source: LazyPath

std.Build.Step.Compile.setVerboseCC

函数

第 666 行

pub fn setVerboseCC(compile: *Compile, value: bool) void

参数

compile: *Compile
value: bool

std.Build.Step.Compile.setVerboseLink

函数

第 662 行

pub fn setVerboseLink(compile: *Compile, value: bool) void

参数

compile: *Compile
value: bool

std.Build.Step.Compile.setVersionScript

函数

第 577 行

pub fn setVersionScript(compile: *Compile, source: LazyPath) void

参数

compile: *Compile
source: LazyPath

std.Build.Step.Compile.std

别名

第 5 行

别名目标 std

std.Build.Step.Compile.Step

别名

第 13 行

别名目标 std.Build.Step

std.Build.Step.Compile.StringHashMap

别名

第 11 行

别名目标 std.StringHashMap

std.Build.Step.Compile.TestRunner

容器

第 362 行

字段

path: LazyPath
mode: enum { simple, server }

测试运行器可以采用“简单”模式,启动后运行测试,测试结束即退出; 也可通过标准输入输出使用 std.zig.Server,与构建系统 进行更紧密的交互。

源码

std/Build/Step/Compile.zig

const Compile = @This();

const builtin = @import("builtin");

const std = @import("std");
const Io = std.Io;
const mem = std.mem;
const fs = std.fs;
const assert = std.debug.assert;
const panic = std.debug.panic;
const StringHashMap = std.StringHashMap;
const Allocator = std.mem.Allocator;
const Step = std.Build.Step;
const LazyPath = std.Build.LazyPath;
const Module = std.Build.Module;
const InstallDir = std.Build.InstallDir;
const Path = std.Build.Cache.Path;
const Configuration = std.Build.Configuration;

pub const base_tag: Step.Tag = .compile;

step: Step,
root_module: *Module,

name: []const u8,
linker_script: ?LazyPath = null,
version_script: ?LazyPath = null,
/// 已弃用。
out_filename: []const u8,
linkage: ?std.builtin.LinkMode = null,
version: ?std.SemanticVersion,
kind: Kind,
formatted_panics: ?bool = null,
compress_debug_sections: std.zig.CompressDebugSections = .none,
verbose_link: bool,
verbose_cc: bool,
bundle_compiler_rt: ?bool = null,
bundle_ubsan_rt: ?bool = null,
rdynamic: bool,
import_memory: bool = false,
export_memory: bool = false,
/// 对于 WebAssembly 目标,允许从宿主环境
/// 导入未定义符号。
import_symbols: bool = false,
/// (WebAssembly)从宿主环境导入函数表
import_table: bool = false,
export_table: bool = false,
growable_table: bool = false,
initial_memory: ?u64 = null,
max_memory: ?u64 = null,
shared_memory: bool = false,
global_base: ?u64 = null,
/// 通过选项设置;之后预期仅供读取。
zig_lib_dir: ?LazyPath,
filters: []const []const u8,
test_runner: ?TestRunner,
wasi_exec_model: ?std.builtin.WasiExecModel = null,

installed_headers: std.ArrayList(HeaderInstallation),

/// 此步骤用于创建头文件树,依赖模块可将其添加到头文件搜索路径。
/// 已安装的头文件会复制到此步骤。
/// 仅当某模块首次与此产物链接时创建此步骤,
/// 其他情况下不创建。
installed_headers_include_tree: ?*Step.WriteFile = null,

/// 已弃用。此功能将移至外部包:
/// https://codeberg.org/ziglang/rc
///
/// 编译 .rc 文件时自动检测包含目录的行为。
///  any:优先使用可用的 MSVC,否则回退到 MinGW。
///  msvc:使用 MSVC 包含路径,系统上必须已安装。
///  gnu:使用随 Zig 分发的 MinGW 包含路径。
///  none:不使用任何自动检测的包含路径。
rc_includes: std.zig.RcIncludes = .any,

/// 已弃用。此功能将迁移到外部包:
/// https://codeberg.org/ziglang/rc
///
/// (Windows)要嵌入编译结果的 .manifest 文件。
/// 通过选项设置;之后应仅供读取。
win32_manifest: ?LazyPath = null,

/// (Windows)要嵌入编译产物(dll)的 .def 文件。
/// 通过选项设置,此后应视为只读。
win32_module_definition: ?LazyPath = null,

/// 可执行映像的基地址。
image_base: ?u64 = null,

libc_file: ?LazyPath = null,

each_lib_rpath: ?bool = null,
/// ELF 目标上会生成名为 ".note.gnu.build-id" 的链接节,
/// 用于将剥离符号后的二进制文件与其调试符号对应起来。
///
/// 例如,bloaty 项目要求输入必须具有
/// 构建标识,否则拒绝处理,以避免意外不匹配。
///
/// 默认不包含此节,因为会降低链接速度。
///
/// 此选项覆盖传给 `zig build` 的命令行参数。
build_id: ?std.zig.BuildId = null,

/// 在 ELF 文件中创建 .eh_frame_hdr 节
/// 及 PT.GNU_EH_FRAME 段。
link_eh_frame_hdr: bool = false,
link_emit_relocs: bool = false,

/// 将每个函数放在独立节中,使未使用的函数可在
/// 链接阶段安全地回收。
link_function_sections: bool = false,

/// 将每份数据放入各自的节,使链接阶段
/// 可以安全回收未使用的数据。
link_data_sections: bool = false,

/// 移除从入口点或导出符号
/// 不可达的函数和数据。
link_gc_sections: ?bool = null,

/// (Windows)是否启用 ASLR。映射到 /DYNAMICBASE[:NO] 链接器参数。
linker_dynamicbase: bool = true,

linker_allow_shlib_undefined: ?bool = null,

/// 允许版本脚本引用未定义符号。
linker_allow_undefined_version: ?bool = null,

// 启用或禁用动态节中的新 DT_RUNPATH 标签。
linker_enable_new_dtags: ?bool = null,

/// 允许只读段中的只读重定位。默认不允许。
link_z_notext: bool = false,

/// 强制在处理后将所有重定位设为只读。
link_z_relro: bool = true,

/// 允许在加载后延迟处理重定位。
link_z_lazy: bool = false,

/// 常用页面大小
link_z_common_page_size: ?u64 = null,

/// 最大页大小
link_z_max_page_size: ?u64 = null,

/// 若仍存在任何未定义符号,则强制产生致命错误。
link_z_defs: bool = false,

/// (Darwin)dylib 的安装名称
install_name: ?[]const u8 = null,

/// 必须通过 `Options` 传入。
entitlements: ?LazyPath = null,

/// (Darwin)pagezero 段的大小。
pagezero_size: ?u64 = null,

/// (Darwin)设置加载命令末尾与
/// `__TEXT,__text` 节起始位置之间的填充大小。
headerpad_size: ?u32 = null,

/// (Darwin)自动设置加载命令末尾与 `__TEXT,__text` 节开头
/// 之间的填充大小,使其足以容纳所有扩展到 MAXPATHLEN 的路径。
headerpad_max_install_names: bool = false,

/// (Darwin)移除从入口点或导出符号不可达的动态库。
dead_strip_dylibs: bool = false,

/// (Darwin)强制加载静态归档中实现 Objective-C 类或分类的所有成员。
force_load_objc: bool = false,

/// 是否从符号表中丢弃局部符号。
discard_local_symbols: bool = false,

/// 位置无关可执行文件
pie: ?bool = null,

/// 链接时优化模式
lto: ?std.zig.LtoMode = null,

dll_export_fns: ?bool = null,

subsystem: ?std.zig.Subsystem = null,

/// (Windows)目标为 MinGW ABI 时,使用 Unicode 入口点(wmain/wWinMain)
mingw_unicode_entry_point: bool = false,

/// 链接器必须如何处理可执行文件的入口点。
entry: Entry = .default,

/// 在符号表中强制设为未定义的符号列表,
/// 从而强制链接器解析这些符号。
/// ELF/MachO 对应 `-u <symbol>`,COFF/PE 对应 `/include:<symbol>`。
force_undefined_symbols: std.array_hash_map.String(void),

/// 覆盖默认栈大小
stack_size: ?u64 = null,

use_llvm: ?bool,
use_lld: ?bool,
use_new_linker: ?bool,

/// 对应 `-fallow-so-scripts` / `-fno-allow-so-scripts` 命令行
/// 标志,覆盖传递给 `zig build`
/// 命令的全局用户设置。
///
/// 编译器默认关闭此选项,使系统共享库
/// 全部为 ELF 文件的用户无需承担逐个检查
/// 文件是否为文本文件的开销。
allow_so_scripts: ?bool = null,

/// 此高级设置可以改变本 Compile 步骤的用途。
/// 若此值非 null,表示此 Compile 步骤用于
/// 检查编译错误;若与预期匹配,则返回成功,
/// 否则返回失败。
expect_errors: ?ExpectedCompileErrors = null,

/// 单个编译步骤中不同错误的最大数量,默认为
/// `std.math.maxInt(u16)`。覆盖传给 `zig build` 的参数。
error_limit: ?u32 = null,

/// 启用一种覆盖率插桩,仅在使用依赖它的第三方模糊测试器时有用。否则只会增加不必要的函数调用,拖慢插桩后的二进制程序。
///
/// AFLplusplus v4.21c 使用此类覆盖率插桩;但包括 Zig 在内的现代模糊测试器已经改用“内联 8 位计数器”或“内联布尔标志”,覆盖率记录仅需一条指令,并结合“trace cmp”对比较操作插桩、报告其操作数。
///
/// 若要使用 Zig 内置模糊测试器对一次编译启用模糊测试插桩,请参见 `fuzz` 标志,位于 `Module` 中。
///
///
///
///
///
///
///
sanitize_coverage_trace_pc_guard: ?bool = null,

/// 启用或禁用增量编译。
///
/// 增量编译通过修改现有构建产物来减少编译时间。
/// 非增量编译较慢,但会保留先前的构建产物。
incremental: ?bool = null,

emit_directory: Configuration.OptionalGeneratedFileIndex = .none,
generated_docs: Configuration.OptionalGeneratedFileIndex = .none,
generated_asm: Configuration.OptionalGeneratedFileIndex = .none,
generated_bin: Configuration.OptionalGeneratedFileIndex = .none,
generated_pdb: Configuration.OptionalGeneratedFileIndex = .none,
generated_implib: Configuration.OptionalGeneratedFileIndex = .none,
generated_llvm_bc: Configuration.OptionalGeneratedFileIndex = .none,
generated_llvm_ir: Configuration.OptionalGeneratedFileIndex = .none,
generated_h: Configuration.OptionalGeneratedFileIndex = .none,

pub const ExpectedCompileErrors = union(enum) {
    contains: []const u8,
    exact: []const []const u8,
    starts_with: []const u8,
    stderr_contains: []const u8,
};

pub const Entry = union(enum) {
    /// 让编译器决定是否创建入口点以及入口点的名称。
    ///
    default,
    /// 可执行文件将没有入口点。
    disabled,
    /// 可执行文件将具有采用默认符号名称的入口点。
    enabled,
    /// 可执行文件的入口点将使用指定符号名。
    symbol_name: []const u8,
};

pub const Options = struct {
    name: []const u8,
    root_module: *Module,
    kind: Kind,
    linkage: ?std.builtin.LinkMode = null,
    version: ?std.SemanticVersion = null,
    max_rss: u64 = 0,
    filters: []const []const u8 = &.{},
    test_runner: ?TestRunner = null,
    use_llvm: ?bool = null,
    use_lld: ?bool = null,
    zig_lib_dir: ?LazyPath = null,
    /// 已弃用。此功能将移至外部包:
    /// https://codeberg.org/ziglang/rc
    ///
    /// 若目标文件格式支持,在编译结果中嵌入 `.manifest` 文件。
    /// https://learn.microsoft.com/en-us/windows/win32/sbscs/manifest-files-reference
    /// 清单文件必须具有 `.manifest` 扩展名。
    /// 无论目标为何均可设置。若目标文件格式不支持嵌入清单,则忽略 `.manifest` 文件。
    ///
    win32_manifest: ?LazyPath = null,
    /// Win32 模块定义文件。
    win32_module_definition: ?LazyPath = null,
    /// (Darwin)权限文件路径
    entitlements: ?LazyPath = null,
};

pub const Kind = Configuration.Step.Compile.Kind;

pub const HeaderInstallation = union(enum) {
    file: File,
    directory: Directory,

    pub const File = struct {
        source: LazyPath,
        dest_rel_path: []const u8,

        pub fn dupe(file: File, graph: *const std.Build.Graph) File {
            return .{
                .source = file.source.dupe(graph),
                .dest_rel_path = graph.dupePath(file.dest_rel_path),
            };
        }
    };

    pub const Directory = struct {
        source: LazyPath,
        dest_rel_path: []const u8,
        options: Directory.Options,

        pub const Options = struct {
            /// 以这些后缀中任意一个结尾的文件路径将被排除,不予安装。
            exclude_extensions: []const []const u8 = &.{},
            /// 仅将以这些后缀之一结尾的文件路径纳入安装。
            /// `null` 表示包含所有后缀。
            /// `exclude_extensions` 优先于 `include_extensions`。
            include_extensions: ?[]const []const u8 = &.{".h"},

            pub fn dupe(opts: Directory.Options, graph: *const std.Build.Graph) Directory.Options {
                return .{
                    .exclude_extensions = graph.dupeStrings(opts.exclude_extensions),
                    .include_extensions = if (opts.include_extensions) |incs| graph.dupeStrings(incs) else null,
                };
            }
        };

        pub fn dupe(dir: Directory, graph: *const std.Build.Graph) Directory {
            return .{
                .source = dir.source.dupe(graph),
                .dest_rel_path = graph.dupePath(dir.dest_rel_path),
                .options = dir.options.dupe(graph),
            };
        }
    };

    pub fn getSource(installation: HeaderInstallation) LazyPath {
        return switch (installation) {
            inline .file, .directory => |x| x.source,
        };
    }

    pub fn dupe(installation: HeaderInstallation, graph: *const std.Build.Graph) HeaderInstallation {
        return switch (installation) {
            .file => |f| .{ .file = f.dupe(graph) },
            .directory => |d| .{ .directory = d.dupe(graph) },
        };
    }
};

pub const TestRunner = struct {
    path: LazyPath,
    /// 测试运行器可以采用“简单”模式,启动后运行测试,测试结束即退出;
    /// 也可通过标准输入输出使用 `std.zig.Server`,与构建系统
    /// 进行更紧密的交互。
    mode: enum { simple, server },
};

pub fn create(owner: *std.Build, options: Options) *Compile {
    const graph = owner.graph;
    const arena = graph.arena;

    const name = owner.graph.dupeString(options.name);
    if (mem.find(u8, name, "/") != null or mem.find(u8, name, "\\") != null) {
        panic("invalid name: '{s}'. It looks like a file path, but it is supposed to be the library or application name.", .{name});
    }

    const resolved_target = options.root_module.resolved_target orelse
        @panic("the root Module of a Compile step must be created with a known 'target' field");
    const target = &resolved_target.result;

    const step_name = owner.fmt("compile {s} {s} {s}", .{
        // 避免步骤名称形如 "compile test test" 的常见情况。
        if (options.kind.isTest() and mem.eql(u8, name, "test"))
            @tagName(options.kind)
        else
            owner.fmt("{t} {s}", .{ options.kind, name }),
        @tagName(options.root_module.optimize orelse .debug),
        resolved_target.query.zigTriple(arena) catch @panic("OOM"),
    });

    const out_filename = std.zig.binNameAlloc(arena, .{
        .root_name = name,
        .cpu_arch = target.cpu.arch,
        .os_tag = target.os.tag,
        .ofmt = target.ofmt,
        .abi = target.abi,
        .output_mode = switch (options.kind) {
            .lib => .Lib,
            .obj, .test_obj => .Obj,
            .exe, .@"test" => .Exe,
        },
        .link_mode = options.linkage,
        .version = options.version,
    }) catch @panic("OOM");

    const compile = arena.create(Compile) catch @panic("OOM");
    compile.* = .{
        .root_module = options.root_module,
        .verbose_link = false,
        .verbose_cc = false,
        .linkage = options.linkage,
        .kind = options.kind,
        .name = name,
        .step = .init(.{
            .tag = base_tag,
            .name = step_name,
            .owner = owner,
            .max_rss = options.max_rss,
        }),
        .version = options.version,
        .out_filename = out_filename,
        .installed_headers = .empty,
        .zig_lib_dir = null,
        .filters = options.filters,
        .test_runner = null, // 在下方设置
        .rdynamic = false,
        .force_undefined_symbols = .empty,

        .use_llvm = options.use_llvm,
        .use_lld = options.use_lld,
        .use_new_linker = null,
    };

    if (options.zig_lib_dir) |lp| {
        compile.zig_lib_dir = lp.dupe(graph);
        lp.addStepDependencies(&compile.step);
    }

    if (options.test_runner) |runner| {
        compile.test_runner = .{
            .path = runner.path.dupe(graph),
            .mode = runner.mode,
        };
        runner.path.addStepDependencies(&compile.step);
    }

    // 只有 PE/COFF 格式具有用于嵌入清单的资源表,
    // 因此对于其他目标,清单文件会被直接忽略。
    if (target.ofmt == .coff) {
        if (options.win32_manifest) |lp| {
            compile.win32_manifest = lp.dupe(graph);
            lp.addStepDependencies(&compile.step);
        }
        if (compile.kind == .lib and compile.linkage != null and compile.linkage.? == .dynamic) {
            // 正在构建 Win32 DLL,检查 win32 .def 文件。
            if (options.win32_module_definition) |lp| {
                compile.win32_module_definition = lp.dupe(graph);
                lp.addStepDependencies(&compile.step);
            }
        }
    }

    if (options.entitlements) |lp| {
        compile.entitlements = lp.dupe(graph);
        lp.addStepDependencies(&compile.step);
    }

    return compile;
}

/// 将指定头文件标记为与此产物一同安装。
/// 模块链接此产物时,所有标记为安装的头文件都会加入该
/// 模块的包含文件搜索路径。
pub fn installHeader(cs: *Compile, source: LazyPath, dest_rel_path: []const u8) void {
    const graph = cs.step.owner.graph;
    const arena = graph.arena;
    const installation: HeaderInstallation = .{ .file = .{
        .source = source.dupe(graph),
        .dest_rel_path = graph.dupePath(dest_rel_path),
    } };
    cs.installed_headers.append(arena, installation) catch @panic("OOM");
    cs.addHeaderInstallationToIncludeTree(installation);
    installation.getSource().addStepDependencies(&cs.step);
}

/// 将指定目录中的头文件标记为与此产物一同安装。
/// 模块链接此产物时,所有标记为安装的头文件都会加入该
/// 模块的包含文件搜索路径。
pub fn installHeadersDirectory(
    cs: *Compile,
    source: LazyPath,
    dest_rel_path: []const u8,
    options: HeaderInstallation.Directory.Options,
) void {
    const graph = cs.step.owner.graph;
    const arena = graph.arena;
    const installation: HeaderInstallation = .{ .directory = .{
        .source = source.dupe(graph),
        .dest_rel_path = graph.dupePath(dest_rel_path),
        .options = options.dupe(graph),
    } };
    cs.installed_headers.append(arena, installation) catch @panic("OOM");
    cs.addHeaderInstallationToIncludeTree(installation);
    installation.getSource().addStepDependencies(&cs.step);
}

/// 将指定配置头文件标记为与此产物一同安装。
/// 模块链接此产物时,所有标记为安装的头文件都会加入该
/// 模块的包含文件搜索路径。
pub fn installConfigHeader(cs: *Compile, config_header: *Step.ConfigHeader) void {
    cs.installHeader(config_header.getOutputFile(), config_header.include_path);
}

/// 将 `lib` 中所有标记为安装的头文件转发到此产物。
/// 模块与此产物链接时,所有标记为安装的头文件都会加入
/// 该模块的头文件搜索路径。
pub fn installLibraryHeaders(cs: *Compile, lib: *Compile) void {
    assert(lib.kind == .lib);
    const graph = cs.step.owner.graph;
    const arena = graph.arena;
    for (lib.installed_headers.items) |installation| {
        const installation_copy = installation.dupe(graph);
        cs.installed_headers.append(arena, installation_copy) catch @panic("OOM");
        cs.addHeaderInstallationToIncludeTree(installation_copy);
        installation_copy.getSource().addStepDependencies(&cs.step);
    }
}

fn addHeaderInstallationToIncludeTree(cs: *Compile, installation: HeaderInstallation) void {
    if (cs.installed_headers_include_tree) |wf| switch (installation) {
        .file => |file| {
            _ = wf.addCopyFile(file.source, file.dest_rel_path);
        },
        .directory => |dir| {
            _ = wf.addCopyDirectory(dir.source, dir.dest_rel_path, .{
                .exclude_extensions = dir.options.exclude_extensions,
                .include_extensions = dir.options.include_extensions,
            });
        },
    };
}

pub fn getEmittedIncludeTree(cs: *Compile) LazyPath {
    if (cs.installed_headers_include_tree) |wf| return wf.getDirectory();
    const b = cs.step.owner;
    const wf = b.addWriteFiles();
    cs.installed_headers_include_tree = wf;
    for (cs.installed_headers.items) |installation| {
        cs.addHeaderInstallationToIncludeTree(installation);
    }
    // 编译步骤本身无需依赖写入文件步骤,
    // 只有依赖它的模块需要。
    return wf.getDirectory();
}

pub fn addObjCopy(cs: *Compile, options: Step.ObjCopy.Options) *Step.ObjCopy {
    const b = cs.step.owner;
    var copy = options;
    if (copy.basename == null) {
        if (options.format) |f| {
            copy.basename = b.fmt("{s}.{s}", .{ cs.name, @tagName(f) });
        } else {
            copy.basename = cs.name;
        }
    }
    return b.addObjCopy(cs.getEmittedBin(), copy);
}

pub fn setLinkerScript(compile: *Compile, source: LazyPath) void {
    const graph = compile.step.owner.graph;
    compile.linker_script = source.dupe(graph);
    source.addStepDependencies(&compile.step);
}

pub fn setVersionScript(compile: *Compile, source: LazyPath) void {
    const graph = compile.step.owner.graph;
    compile.version_script = source.dupe(graph);
    source.addStepDependencies(&compile.step);
}

pub fn forceUndefinedSymbol(compile: *Compile, symbol_name: []const u8) void {
    const graph = compile.step.owner.graph;
    const arena = graph.arena;
    compile.force_undefined_symbols.put(arena, graph.dupeString(symbol_name), {}) catch @panic("OOM");
}

/// 返回库、可执行文件或对象是否依赖某个系统库。
/// 包含传递依赖。
pub fn dependsOnSystemLibrary(compile: *Compile, name: []const u8) bool {
    var is_linking_libc = false;
    var is_linking_libcpp = false;

    for (compile.getCompileDependencies(true)) |some_compile| {
        for (some_compile.root_module.getGraph().modules) |mod| {
            for (mod.link_objects.items) |lo| {
                switch (lo) {
                    .system_lib => |lib| if (mem.eql(u8, lib.name, name)) return true,
                    else => {},
                }
            }
            if (mod.link_libc orelse false) is_linking_libc = true;
            if (mod.link_libcpp orelse false) is_linking_libcpp = true;
        }
    }

    const target = compile.rootModuleTarget();

    if (std.zig.target.isLibCLibName(&target, name)) {
        return is_linking_libc;
    }

    if (std.zig.target.isLibCxxLibName(&target, name)) {
        return is_linking_libcpp;
    }

    return false;
}

pub fn isDynamicLibrary(compile: *const Compile) bool {
    return compile.kind == .lib and compile.linkage == .dynamic;
}

pub fn isStaticLibrary(compile: *const Compile) bool {
    return compile.kind == .lib and compile.linkage != .dynamic;
}

pub fn isDll(compile: *Compile) bool {
    return compile.isDynamicLibrary() and compile.rootModuleTarget().os.tag == .windows;
}

pub fn producesPdbFile(compile: *Compile) bool {
    const target = compile.rootModuleTarget();
    // TODO: 这样正确吗?PDB 不是适用于任意 PE/COFF 文件吗?
    // TODO: 直接与编译器共用此逻辑!
    switch (target.os.tag) {
        .windows, .uefi => {},
        else => return false,
    }
    if (target.ofmt == .c) return false;
    if (compile.use_llvm == false) return false;
    if (compile.root_module.strip == true or
        (compile.root_module.strip == null and compile.root_module.optimize == .small))
    {
        return false;
    }
    return compile.isDynamicLibrary() or compile.kind == .exe or compile.kind == .@"test";
}

pub fn producesCompilerRtDynLib(compile: *Compile) bool {
    if (compile.rootModuleTarget().ofmt != .coff) return false;
    if (compile.bundle_compiler_rt orelse (compile.kind == .exe or compile.isDynamicLibrary()))
        return compile.use_llvm == false;
    return false;
}

pub fn producesImplib(compile: *Compile) bool {
    return compile.isDll();
}

pub fn setVerboseLink(compile: *Compile, value: bool) void {
    compile.verbose_link = value;
}

pub fn setVerboseCC(compile: *Compile, value: bool) void {
    compile.verbose_cc = value;
}

pub fn setLibCFile(compile: *Compile, libc_file: ?LazyPath) void {
    const graph = compile.step.owner.graph;
    if (libc_file) |f| {
        compile.libc_file = f.dupe(graph);
        f.addStepDependencies(&compile.step);
    } else {
        compile.libc_file = null;
    }
}

fn getEmittedFileGeneric(compile: *Compile, output_file: *Configuration.OptionalGeneratedFileIndex) LazyPath {
    if (output_file.unwrap()) |index| return .{ .generated = .{ .index = index } };
    const graph = compile.step.owner.graph;
    const index = graph.addGeneratedFile(&compile.step);
    output_file.* = .init(index);
    return .{ .generated = .{ .index = index } };
}

/// 返回包含所生成二进制文件的目录路径。
pub fn getEmittedBinDirectory(compile: *Compile) LazyPath {
    _ = compile.getEmittedBin();
    return compile.getEmittedFileGeneric(&compile.emit_directory);
}

/// 返回生成的可执行文件、库或对象文件路径。
/// 要运行由 zig build 构建的可执行文件,请使用 `run`,或创建安装步骤并调用它。
pub fn getEmittedBin(compile: *Compile) LazyPath {
    return compile.getEmittedFileGeneric(&compile.generated_bin);
}

/// 返回生成的导入库的路径。
/// 此函数只能针对库调用。
pub fn getEmittedImplib(compile: *Compile) LazyPath {
    assert(compile.kind == .lib);
    return compile.getEmittedFileGeneric(&compile.generated_implib);
}

/// 返回生成的头文件路径。
/// 此函数只能针对库或目标文件调用。
pub fn getEmittedH(compile: *Compile) LazyPath {
    assert(compile.kind != .exe and compile.kind != .@"test");
    return compile.getEmittedFileGeneric(&compile.generated_h);
}

/// 返回生成的 PDB 文件。
/// 如果编译不产生 PDB 文件,则会在构建时
/// 引发 FileNotFound 错误。
pub fn getEmittedPdb(compile: *Compile) LazyPath {
    _ = compile.getEmittedBin();
    return compile.getEmittedFileGeneric(&compile.generated_pdb);
}

/// 返回生成的文档目录的路径。
pub fn getEmittedDocs(compile: *Compile) LazyPath {
    return compile.getEmittedFileGeneric(&compile.generated_docs);
}

/// 返回生成的汇编代码的路径。
pub fn getEmittedAsm(compile: *Compile) LazyPath {
    return compile.getEmittedFileGeneric(&compile.generated_asm);
}

/// 返回生成的 LLVM 中间表示的路径。
pub fn getEmittedLlvmIr(compile: *Compile) LazyPath {
    return compile.getEmittedFileGeneric(&compile.generated_llvm_ir);
}

/// 返回生成的 LLVM BC 的路径。
pub fn getEmittedLlvmBc(compile: *Compile) LazyPath {
    return compile.getEmittedFileGeneric(&compile.generated_llvm_bc);
}

pub fn rootModuleTarget(c: *Compile) std.Target {
    // 根模块始终指定目标,因此已知此值非 null。
    return c.root_module.resolved_target.?.result;
}

/// 返回 `start` 递归依赖的全部 `Step.Compile`。`start` 本身
/// 始终作为首个元素返回。如果 `chase_dynamic` 为 `false`,不包括动态库,
/// 也不考虑其依赖;如果 `chase_dynamic` 为 `true`,则将动态库
/// 与其他链接的 `Compile` 一样处理。
pub fn getCompileDependencies(start: *Compile, chase_dynamic: bool) []const *Compile {
    const arena = start.step.owner.graph.arena;

    var compiles: std.array_hash_map.Auto(*Compile, void) = .empty;
    var next_idx: usize = 0;

    compiles.putNoClobber(arena, start, {}) catch @panic("OOM");

    while (next_idx < compiles.count()) {
        const compile = compiles.keys()[next_idx];
        next_idx += 1;

        for (compile.root_module.getGraph().modules) |mod| {
            for (mod.link_objects.items) |lo| {
                switch (lo) {
                    .other_step => |other_compile| {
                        if (!chase_dynamic and other_compile.isDynamicLibrary()) continue;
                        compiles.put(arena, other_compile, {}) catch @panic("OOM");
                    },
                    else => {},
                }
            }
        }
    }

    return compiles.keys();
}