字段
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 = nullELF 目标上会生成名为 ".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
CompilebuiltinstdIomemfsassertpanicStringHashMapAllocatorStepLazyPathModuleInstallDirPathConfigurationbase_tagExpectedCompileErrorsEntryOptionsKindHeaderInstallationTestRunnercreateinstallHeaderinstallHeadersDirectoryinstallConfigHeaderinstallLibraryHeadersaddHeaderInstallationToIncludeTreegetEmittedIncludeTreeaddObjCopysetLinkerScriptsetVersionScriptforceUndefinedSymboldependsOnSystemLibraryisDynamicLibraryisStaticLibraryisDllproducesPdbFileproducesCompilerRtDynLibproducesImplibsetVerboseLinksetVerboseCCsetLibCFilegetEmittedFileGenericgetEmittedBinDirectorygetEmittedBingetEmittedImplibgetEmittedHgetEmittedPdbgetEmittedDocsgetEmittedAsmgetEmittedLlvmIrgetEmittedLlvmBcrootModuleTargetgetCompileDependencies
std.Build.Step.Compile.addHeaderInstallationToIncludeTree
函数
fn addHeaderInstallationToIncludeTree(cs: *Compile, installation: HeaderInstallation) void
参数
cs: *Compile
installation: HeaderInstallation
std.Build.Step.Compile.addObjCopy
函数
pub fn addObjCopy(cs: *Compile, options: Step.ObjCopy.Options) *Step.ObjCopy
参数
std.Build.Step.Compile.Allocator
别名
别名目标 std.mem.Allocator
std.Build.Step.Compile.assert
别名
别名目标 std.debug.assert
std.Build.Step.Compile.base_tag
常量
Step.Tag
std.Build.Step.Compile.builtin
常量
std.Build.Step.Compile.Compile
别名
std.Build.Step.Compile.Configuration
别名
std.Build.Step.Compile.create
函数
pub fn create(owner: *std.Build, options: Options) *Compile
参数
std.Build.Step.Compile.dependsOnSystemLibrary
函数
返回库、可执行文件或对象是否依赖某个系统库。 包含传递依赖。
pub fn dependsOnSystemLibrary(compile: *Compile, name: []const u8) bool
参数
compile: *Compile
name: []const u8
std.Build.Step.Compile.Entry
容器
字段
default让编译器决定是否创建入口点以及入口点的名称。
disabled可执行文件将没有入口点。
enabled可执行文件将具有采用默认符号名称的入口点。
symbol_name: []const u8可执行文件的入口点将使用指定符号名。
std.Build.Step.Compile.ExpectedCompileErrors
容器
字段
contains: []const u8
exact: []const []const u8
starts_with: []const u8
stderr_contains: []const u8
std.Build.Step.Compile.forceUndefinedSymbol
函数
pub fn forceUndefinedSymbol(compile: *Compile, symbol_name: []const u8) void
参数
compile: *Compile
symbol_name: []const u8
std.Build.Step.Compile.fs
别名
别名目标 std.fs
std.Build.Step.Compile.getCompileDependencies
函数
返回 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
函数
返回生成的汇编代码的路径。
pub fn getEmittedAsm(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.getEmittedBin
函数
返回生成的可执行文件、库或对象文件路径。
要运行由 zig build 构建的可执行文件,请使用 run,或创建安装步骤并调用它。
pub fn getEmittedBin(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.getEmittedBinDirectory
函数
返回包含所生成二进制文件的目录路径。
pub fn getEmittedBinDirectory(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.getEmittedDocs
函数
返回生成的文档目录的路径。
pub fn getEmittedDocs(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.getEmittedFileGeneric
函数
fn getEmittedFileGeneric(compile: *Compile, output_file: *Configuration.OptionalGeneratedFileIndex) LazyPath
参数
compile: *Compile
output_file: *Configuration.OptionalGeneratedFileIndex
std.Build.Step.Compile.getEmittedH
函数
返回生成的头文件路径。 此函数只能针对库或目标文件调用。
pub fn getEmittedH(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.getEmittedImplib
函数
返回生成的导入库的路径。 此函数只能针对库调用。
pub fn getEmittedImplib(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.getEmittedIncludeTree
函数
pub fn getEmittedIncludeTree(cs: *Compile) LazyPath
参数
cs: *Compile
std.Build.Step.Compile.getEmittedLlvmBc
函数
返回生成的 LLVM BC 的路径。
pub fn getEmittedLlvmBc(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.getEmittedLlvmIr
函数
返回生成的 LLVM 中间表示的路径。
pub fn getEmittedLlvmIr(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.getEmittedPdb
函数
返回生成的 PDB 文件。 如果编译不产生 PDB 文件,则会在构建时 引发 FileNotFound 错误。
pub fn getEmittedPdb(compile: *Compile) LazyPath
参数
compile: *Compile
std.Build.Step.Compile.HeaderInstallation
容器
字段
std.Build.Step.Compile.HeaderInstallation.Directory
容器
字段
std.Build.Step.Compile.HeaderInstallation.Directory.dupe
函数
pub fn dupe(dir: Directory, graph: *const std.Build.Graph) Directory
参数
std.Build.Step.Compile.HeaderInstallation.Directory.Options
容器
字段
exclude_extensions: []const []const u8 = &.{}以这些后缀中任意一个结尾的文件路径将被排除,不予安装。
include_extensions: ?[]const []const u8 = &.{".h"}仅将以这些后缀之一结尾的文件路径纳入安装。
null 表示包含所有后缀。
exclude_extensions 优先于 include_extensions。
std.Build.Step.Compile.HeaderInstallation.Directory.Options.dupe
函数
pub fn dupe(opts: Directory.Options, graph: *const std.Build.Graph) Directory.Options
参数
std.Build.Step.Compile.HeaderInstallation.dupe
函数
pub fn dupe(installation: HeaderInstallation, graph: *const std.Build.Graph) HeaderInstallation
参数
installation: HeaderInstallation
graph: *const std.Build.Graph
std.Build.Step.Compile.HeaderInstallation.File
容器
字段
source: LazyPath
dest_rel_path: []const u8
std.Build.Step.Compile.HeaderInstallation.File.dupe
函数
pub fn dupe(file: File, graph: *const std.Build.Graph) File
参数
std.Build.Step.Compile.HeaderInstallation.getSource
函数
pub fn getSource(installation: HeaderInstallation) LazyPath
参数
installation: HeaderInstallation
std.Build.Step.Compile.installConfigHeader
函数
将指定配置头文件标记为与此产物一同安装。 模块链接此产物时,所有标记为安装的头文件都会加入该 模块的包含文件搜索路径。
pub fn installConfigHeader(cs: *Compile, config_header: *Step.ConfigHeader) void
参数
cs: *Compile
config_header: *Step.ConfigHeader
std.Build.Step.Compile.InstallDir
别名
别名目标 std.Build.InstallDir
std.Build.Step.Compile.installHeader
函数
将指定头文件标记为与此产物一同安装。 模块链接此产物时,所有标记为安装的头文件都会加入该 模块的包含文件搜索路径。
pub fn installHeader(cs: *Compile, source: LazyPath, dest_rel_path: []const u8) void
参数
std.Build.Step.Compile.installHeadersDirectory
函数
将指定目录中的头文件标记为与此产物一同安装。 模块链接此产物时,所有标记为安装的头文件都会加入该 模块的包含文件搜索路径。
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
函数
将 lib 中所有标记为安装的头文件转发到此产物。
模块与此产物链接时,所有标记为安装的头文件都会加入
该模块的头文件搜索路径。
pub fn installLibraryHeaders(cs: *Compile, lib: *Compile) void
参数
std.Build.Step.Compile.Io
别名
别名目标 std.Io
std.Build.Step.Compile.isDll
函数
pub fn isDll(compile: *Compile) bool
参数
compile: *Compile
std.Build.Step.Compile.isDynamicLibrary
函数
pub fn isDynamicLibrary(compile: *const Compile) bool
参数
compile: *const Compile
std.Build.Step.Compile.isStaticLibrary
函数
pub fn isStaticLibrary(compile: *const Compile) bool
参数
compile: *const Compile
std.Build.Step.Compile.Kind
别名
std.Build.Step.Compile.LazyPath
别名
别名目标 std.Build.LazyPath
std.Build.Step.Compile.mem
别名
别名目标 std.mem
std.Build.Step.Compile.Module
别名
别名目标 std.Build.Module
std.Build.Step.Compile.Options
容器
字段
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 = nullWin32 模块定义文件。
entitlements: ?LazyPath = null(Darwin)权限文件路径
std.Build.Step.Compile.panic
别名
别名目标 std.debug.panic
std.Build.Step.Compile.Path
别名
别名目标 std.Build.Cache.Path
std.Build.Step.Compile.producesCompilerRtDynLib
函数
pub fn producesCompilerRtDynLib(compile: *Compile) bool
参数
compile: *Compile
std.Build.Step.Compile.producesImplib
函数
pub fn producesImplib(compile: *Compile) bool
参数
compile: *Compile
std.Build.Step.Compile.producesPdbFile
函数
pub fn producesPdbFile(compile: *Compile) bool
参数
compile: *Compile
std.Build.Step.Compile.rootModuleTarget
函数
pub fn rootModuleTarget(c: *Compile) std.Target
参数
c: *Compile
std.Build.Step.Compile.setLibCFile
函数
pub fn setLibCFile(compile: *Compile, libc_file: ?LazyPath) void
参数
std.Build.Step.Compile.setLinkerScript
函数
pub fn setLinkerScript(compile: *Compile, source: LazyPath) void
参数
std.Build.Step.Compile.setVerboseCC
函数
pub fn setVerboseCC(compile: *Compile, value: bool) void
参数
compile: *Compile
value: bool
std.Build.Step.Compile.setVerboseLink
函数
pub fn setVerboseLink(compile: *Compile, value: bool) void
参数
compile: *Compile
value: bool
std.Build.Step.Compile.setVersionScript
函数
pub fn setVersionScript(compile: *Compile, source: LazyPath) void
参数
std.Build.Step.Compile.std
别名
别名目标 std
std.Build.Step.Compile.Step
别名
别名目标 std.Build.Step
std.Build.Step.Compile.StringHashMap
别名
别名目标 std.StringHashMap
std.Build.Step.Compile.TestRunner
容器
字段
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();
}