字段
tag: Configuration.Step.Tag
name: []const u8
owner: *Build
dependencies: std.ArrayList(*Step)
max_rss: u64设置此字段可声明执行该步骤所需内存字节数的 上限。零表示不设限制。
其目的是为可能占用大量内存的步骤
标注上限。例如,某组单元测试可能需要 4
GiB 内存,且将同时以四种不同的构建
配置运行。若四个步骤同时执行,系统就可能需要
16 GiB 内存,
很容易超过实际可用内存,可能导致
使用默认并发度执行 zig build 时系统崩溃。
此字段使构建运行器执行两项操作:
- 使用 ulimit 限制子进程,使其在超出该 内存限制时失败。这也用于验证 声明的上限值正确。
- 确保任意时刻所有并发步骤的
max_rss 总和不超过构建运行器的
max_total_rss值。此值可通过命令行配置,默认为 系统可用总内存。
debug_stack_trace: std.debug.StackTrace与此步骤创建位置关联的返回地址, 可与调试消息一起打印,辅助诊断。
std.Build.Step.assert
别名
别名目标 std.debug.assert
std.Build.Step.Build
别名
别名目标 std.Build
std.Build.Step.cast
函数
pub fn cast(step: *Step, comptime T: type) ?*T
参数
step: *Step
T: type
std.Build.Step.CheckFile
别名
std.Build.Step.Compile
别名
std.Build.Step.ConfigHeader
别名
std.Build.Step.Configuration
别名
std.Build.Step.dependOn
函数
pub fn dependOn(step: *Step, other: *Step) void
参数
std.Build.Step.dump
函数
为调试打印此 Step 的标识信息。
pub fn dump(step: *Step, t: std.Io.Terminal) void
参数
std.Build.Step.Fail
别名
别名目标 std.Build.Step.Fail
std.Build.Step.FindProgram
别名
std.Build.Step.Fmt
别名
别名目标 std.Build.Step.Fmt
std.Build.Step.init
函数
pub fn init(options: StepOptions) Step
参数
options: StepOptions
std.Build.Step.InstallArtifact
别名
std.Build.Step.InstallDir
别名
std.Build.Step.InstallFile
别名
std.Build.Step.ObjCopy
别名
std.Build.Step.Options
别名
std.Build.Step.Run
别名
别名目标 std.Build.Step.Run
std.Build.Step.std
别名
别名目标 std
std.Build.Step.Step
别名
别名目标 std.Build.Step
std.Build.Step.StepOptions
容器
字段
std.Build.Step.Tag
别名
std.Build.Step.TopLevel
容器
字段
step: Step
description: []const u8
std.Build.Step.TopLevel.base_tag
常量
Step.Tag
std.Build.Step.TranslateC
别名
std.Build.Step.Type
类型函数
pub fn Type(comptime tag: Tag) type
参数
tag: Tag
std.Build.Step.UpdateSourceFiles
别名
std.Build.Step.WriteFile
别名
源码
std/Build/Step.zig
const Step = @This();
const std = @import("../std.zig");
const Build = std.Build;
const assert = std.debug.assert;
const Configuration = std.Build.Configuration;
tag: Configuration.Step.Tag,
name: []const u8,
owner: *Build,
dependencies: std.ArrayList(*Step),
/// 设置此字段可声明执行该步骤所需内存字节数的
/// 上限。零表示不设限制。
///
/// 其目的是为可能占用大量内存的步骤
/// 标注上限。例如,某组单元测试可能需要 4
/// GiB 内存,且将同时以四种不同的构建
/// 配置运行。若四个步骤同时执行,系统就可能需要
/// 16 GiB 内存,
/// 很容易超过实际可用内存,可能导致
/// 使用默认并发度执行 `zig build` 时系统崩溃。
///
/// 此字段使构建运行器执行两项操作:
/// 1. 使用 ulimit 限制子进程,使其在超出该
/// 内存限制时失败。这也用于验证
/// 声明的上限值正确。
/// 2. 确保任意时刻所有并发步骤的
/// max_rss 总和不超过构建运行器的 `max_total_rss`
/// 值。此值可通过命令行配置,默认为
/// 系统可用总内存。
max_rss: u64,
/// 与此步骤创建位置关联的返回地址,
/// 可与调试消息一起打印,辅助诊断。
debug_stack_trace: std.debug.StackTrace,
pub const Tag = Configuration.Step.Tag;
pub fn Type(comptime tag: Tag) type {
return switch (tag) {
.check_file => CheckFile,
.compile => Compile,
.config_header => ConfigHeader,
.fail => Fail,
.find_program => FindProgram,
.fmt => Fmt,
.install_artifact => InstallArtifact,
.install_dir => InstallDir,
.install_file => InstallFile,
.obj_copy => ObjCopy,
.options => Options,
.run => Run,
.top_level => TopLevel,
.translate_c => TranslateC,
.update_source_files => UpdateSourceFiles,
.write_file => WriteFile,
};
}
pub const CheckFile = @import("Step/CheckFile.zig");
pub const Compile = @import("Step/Compile.zig");
pub const ConfigHeader = @import("Step/ConfigHeader.zig");
pub const Fail = @import("Step/Fail.zig");
pub const FindProgram = @import("Step/FindProgram.zig");
pub const Fmt = @import("Step/Fmt.zig");
pub const InstallArtifact = @import("Step/InstallArtifact.zig");
pub const InstallDir = @import("Step/InstallDir.zig");
pub const InstallFile = @import("Step/InstallFile.zig");
pub const ObjCopy = @import("Step/ObjCopy.zig");
pub const Options = @import("Step/Options.zig");
pub const Run = @import("Step/Run.zig");
pub const TranslateC = @import("Step/TranslateC.zig");
pub const UpdateSourceFiles = @import("Step/UpdateSourceFiles.zig");
pub const WriteFile = @import("Step/WriteFile.zig");
pub const TopLevel = struct {
pub const base_tag: Step.Tag = .top_level;
step: Step,
description: []const u8,
};
pub const StepOptions = struct {
tag: Tag,
name: []const u8,
owner: *Build,
first_ret_addr: ?usize = null,
max_rss: u64 = 0,
};
pub fn init(options: StepOptions) Step {
const arena = options.owner.allocator;
return .{
.tag = options.tag,
.name = options.owner.graph.dupeString(options.name),
.owner = options.owner,
.dependencies = .empty,
.max_rss = options.max_rss,
.debug_stack_trace = blk: {
const addr_buf = arena.alloc(usize, options.owner.debug_stack_frames_count) catch @panic("OOM");
const first_ret_addr = options.first_ret_addr orelse @returnAddress();
break :blk std.debug.captureCurrentStackTrace(.{ .first_address = first_ret_addr }, addr_buf);
},
};
}
pub fn dependOn(step: *Step, other: *Step) void {
const arena = step.owner.allocator;
step.dependencies.append(arena, other) catch @panic("OOM");
}
pub fn cast(step: *Step, comptime T: type) ?*T {
if (step.tag == T.base_tag) return @fieldParentPtr("step", step);
return null;
}
/// 为调试打印此 Step 的标识信息。
pub fn dump(step: *Step, t: std.Io.Terminal) void {
const w = t.writer;
if (step.debug_stack_trace.return_addresses.len > 0) {
w.print("name: '{s}'. creation stack trace:\n", .{step.name}) catch {};
std.debug.writeStackTrace(&step.debug_stack_trace, t) catch {};
} else {
const field = "debug_stack_frames_count";
comptime assert(@hasField(Build, field));
t.setColor(.yellow) catch {};
w.print("name: '{s}'. no stack trace collected for this step, see std.Build." ++ field ++ "\n", .{step.name}) catch {};
t.setColor(.reset) catch {};
}
}
test {
_ = CheckFile;
_ = Compile;
_ = ConfigHeader;
_ = Fail;
_ = FindProgram;
_ = Fmt;
_ = InstallArtifact;
_ = InstallDir;
_ = InstallFile;
_ = ObjCopy;
_ = Options;
_ = Run;
_ = TranslateC;
_ = UpdateSourceFiles;
_ = WriteFile;
}