字段
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 = &.{} }
ModulestdassertLazyPathStepArrayListRPathLinkObjectSystemLibCSourceLanguageCSourceFilesCSourceFileRcSourceFileIncludeDirLinkFrameworkOptionsCreateOptionsImportinitcreateaddImportaddAnonymousImportaddOptionsLinkSystemLibraryOptionslinkSystemLibrarylinkFrameworkAddCSourceFilesOptionsaddCSourceFilesaddCSourceFileaddWin32ResourceFileaddAssemblyFileaddObjectFileaddObjectlinkLibraryaddAfterIncludePathaddSystemIncludePathaddIncludePathaddConfigHeaderaddSystemFrameworkPathaddFrameworkPathaddEmbedPathaddLibraryPathaddRPathaddRPathSpecialaddCMacrolinkLibraryOrObjectrequireKnownTargetGraphgetGraph
std.Build.Module.addAfterIncludePath
函数
pub fn addAfterIncludePath(m: *Module, lazy_path: LazyPath) void
参数
std.Build.Module.addAnonymousImport
函数
创建新模块,并将其添加为可通过 @import 使用的模块。
pub fn addAnonymousImport(m: *Module, name: []const u8, options: CreateOptions) void
参数
std.Build.Module.addAssemblyFile
函数
pub fn addAssemblyFile(m: *Module, source: LazyPath) void
参数
std.Build.Module.addCMacro
函数
pub fn addCMacro(m: *Module, name: []const u8, value: []const u8) void
参数
std.Build.Module.addConfigHeader
函数
pub fn addConfigHeader(m: *Module, config_header: *Step.ConfigHeader) void
参数
m: *Module
config_header: *Step.ConfigHeader
std.Build.Module.addCSourceFile
函数
pub fn addCSourceFile(m: *Module, source: CSourceFile) void
参数
m: *Module
source: CSourceFile
std.Build.Module.addCSourceFiles
函数
当存在许多非 Zig 源文件且希望它们使用相同标志时很有用。
pub fn addCSourceFiles(m: *Module, options: AddCSourceFilesOptions) void
参数
m: *Module
options: AddCSourceFilesOptions
std.Build.Module.AddCSourceFilesOptions
容器
字段
root: ?LazyPath = null若提供 root,则 files 相对于它,而非
拥有 Compile 步骤的程序包。
files: []const []const u8
flags: []const []const u8 = &.{}
language: ?CSourceLanguage = null默认根据各文件的扩展名,分别确定其语言
std.Build.Module.addEmbedPath
函数
pub fn addEmbedPath(m: *Module, lazy_path: LazyPath) void
参数
std.Build.Module.addFrameworkPath
函数
pub fn addFrameworkPath(m: *Module, directory_path: LazyPath) void
参数
std.Build.Module.addImport
函数
添加一个现有模块,以供 @import 使用。
pub fn addImport(m: *Module, name: []const u8, module: *Module) void
参数
std.Build.Module.addIncludePath
函数
pub fn addIncludePath(m: *Module, lazy_path: LazyPath) void
参数
std.Build.Module.addLibraryPath
函数
pub fn addLibraryPath(m: *Module, directory_path: LazyPath) void
参数
std.Build.Module.addObject
函数
pub fn addObject(m: *Module, object: *Step.Compile) void
参数
std.Build.Module.addObjectFile
函数
pub fn addObjectFile(m: *Module, object: LazyPath) void
参数
std.Build.Module.addOptions
函数
将一组键值对转换为 Zig 源码文件,然后以指定名称加入
Module 的导入表。这样即可通过
@import("module_name") 导入这些选项。
pub fn addOptions(m: *Module, module_name: []const u8, options: *Step.Options) void
参数
std.Build.Module.addRPath
函数
pub fn addRPath(m: *Module, directory_path: LazyPath) void
参数
std.Build.Module.addRPathSpecial
函数
pub fn addRPathSpecial(m: *Module, bytes: []const u8) void
参数
m: *Module
bytes: []const u8
std.Build.Module.addSystemFrameworkPath
函数
pub fn addSystemFrameworkPath(m: *Module, directory_path: LazyPath) void
参数
std.Build.Module.addSystemIncludePath
函数
pub fn addSystemIncludePath(m: *Module, lazy_path: LazyPath) void
参数
std.Build.Module.addWin32ResourceFile
函数
已弃用。此功能将移至外部软件包: https://codeberg.org/ziglang/rc
资源文件必须使用扩展名 .rc。
可针对任意目标调用。如果目标文件格式不支持嵌入资源,
则忽略 .rc 文件。
pub fn addWin32ResourceFile(m: *Module, source: RcSourceFile) void
参数
m: *Module
source: RcSourceFile
std.Build.Module.ArrayList
别名
别名目标 std.ArrayList
std.Build.Module.assert
别名
别名目标 std.debug.assert
std.Build.Module.create
函数
pub fn create(owner: *std.Build, options: CreateOptions) *Module
参数
owner: *std.Build
options: CreateOptions
std.Build.Module.CreateOptions
容器
插入导入表时,此处未指定的选项
将从父级 Module 继承。
字段
root_source_file: ?LazyPath = null可以是生成文件,此时模块恰好包含一个文件;
也可以是组成该模块的文件目录中
根源文件的路径。
若为 null,表示此模块仅由 link_objects 构成。
imports: []const Import = &.{}
target: ?std.Build.ResolvedTarget = null
optimize: ?std.builtin.Optimize = null
link_libc: ?bool = nulltrue 要求包含此 Module 的编译链接 libc。
false 会在包含此 Module 的编译将链接 libc 时导致构建失败。
null 既不要求也不阻止链接 libc。
link_libcpp: ?bool = nulltrue 要求包含此 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
容器
字段
file: LazyPath
flags: []const []const u8 = &.{}
language: ?CSourceLanguage = null默认根据各文件的扩展名,分别确定其语言
std.Build.Module.CSourceFile.dupe
函数
pub fn dupe(file: CSourceFile, graph: *const std.Build.Graph) CSourceFile
参数
file: CSourceFile
graph: *const std.Build.Graph
std.Build.Module.CSourceFiles
容器
字段
root: LazyPath
files: []const []const u8files 相对于 root,
后者默认为构建根目录。
flags: []const []const u8
language: ?CSourceLanguage默认根据各文件的扩展名,分别确定其语言
std.Build.Module.CSourceLanguage
容器
字段
c
cpp
objective_c
objective_cpp
assembly标准汇编
assembly_with_preprocessor使用 C 预处理器的汇编
std.Build.Module.CSourceLanguage.clangIdentifier
函数
传递给 Clang 命令行选项 "-x" 的值。
pub fn clangIdentifier(self: CSourceLanguage) [:0]const u8
参数
self: CSourceLanguage
std.Build.Module.getGraph
函数
pub fn getGraph(root: *Module) Graph
参数
root: *Module
std.Build.Module.Graph
容器
modules 与 names 的元素一一对应。
字段
modules: []const *Module
names: []const []const u8
std.Build.Module.Import
容器
字段
name: []const u8
module: *Module
std.Build.Module.IncludeDir
容器
字段
std.Build.Module.init
函数
pub fn init( m: *Module, owner: *std.Build, value: union(enum) { options: CreateOptions, existing: *const Module }, ) void
参数
std.Build.Module.LazyPath
别名
别名目标 std.Build.LazyPath
std.Build.Module.linkFramework
函数
pub fn linkFramework(m: *Module, name: []const u8, options: LinkFrameworkOptions) void
参数
std.Build.Module.LinkFrameworkOptions
容器
字段
needed: bool = false无论是否实际依赖动态库,都链接它们。 为 false 时,链接器会省略那些 没有任何符号被引用的动态库。
weak: bool = false将此库中所有被引用的符号标记为弱符号。这意味着,若另一个编译单元提供同名符号,链接器不会报告“符号重复”错误,而会将所有对该符号的引用解析到强符号版本。
链接器遇到两个弱符号时,根据编译单元传给链接器的顺序选择,后提供的优先。
std.Build.Module.linkLibrary
函数
pub fn linkLibrary(m: *Module, library: *Step.Compile) void
参数
std.Build.Module.linkLibraryOrObject
函数
fn linkLibraryOrObject(m: *Module, other: *Step.Compile) void
参数
std.Build.Module.LinkObject
容器
字段
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
函数
pub fn linkSystemLibrary( m: *Module, name: []const u8, options: LinkSystemLibraryOptions, ) void
参数
std.Build.Module.LinkSystemLibraryOptions
容器
字段
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
别名
别名目标 std.Build.Module
std.Build.Module.RcSourceFile
容器
已弃用。此功能将移至外部包: https://codeberg.org/ziglang/rc
字段
file: LazyPath
flags: []const []const u8 = &.{}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
include_paths: []const LazyPath = &.{}可能尚未存在的头文件路径,因此需指定为 LazyPath。
每个路径将以 /I <resolved path> 的形式追加到标志中。
std.Build.Module.RcSourceFile.dupe
函数
pub fn dupe(file: RcSourceFile, graph: *const std.Build.Graph) RcSourceFile
参数
file: RcSourceFile
graph: *const std.Build.Graph
std.Build.Module.requireKnownTarget
函数
fn requireKnownTarget(m: *Module) *const std.Target
参数
m: *Module
std.Build.Module.RPath
容器
字段
lazy_path: LazyPath
special: []const u8
std.Build.Module.std
别名
别名目标 std
std.Build.Module.Step
别名
别名目标 std.Build.Step
std.Build.Module.SystemLib
容器
字段
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
别名
std.Build.Module.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;
}