跳转到内容
标准库Zig 0.17.0官方原文
源码std/Build/Step.zig

第 1 行

字段

tag: Configuration.Step.Tag
name: []const u8
owner: *Build
dependencies: std.ArrayList(*Step)
max_rss: u64

设置此字段可声明执行该步骤所需内存字节数的 上限。零表示不设限制。

其目的是为可能占用大量内存的步骤 标注上限。例如,某组单元测试可能需要 4 GiB 内存,且将同时以四种不同的构建 配置运行。若四个步骤同时执行,系统就可能需要 16 GiB 内存, 很容易超过实际可用内存,可能导致 使用默认并发度执行 zig build 时系统崩溃。

此字段使构建运行器执行两项操作:

  1. 使用 ulimit 限制子进程,使其在超出该 内存限制时失败。这也用于验证 声明的上限值正确。
  2. 确保任意时刻所有并发步骤的 max_rss 总和不超过构建运行器的 max_total_rss 值。此值可通过命令行配置,默认为 系统可用总内存。
debug_stack_trace: std.debug.StackTrace

与此步骤创建位置关联的返回地址, 可与调试消息一起打印,辅助诊断。

std.Build.Step.assert

别名

第 5 行

别名目标 std.debug.assert

std.Build.Step.Build

别名

第 4 行

别名目标 std.Build

std.Build.Step.cast

函数

第 115 行

pub fn cast(step: *Step, comptime T: type) ?*T

参数

step: *Step
T: type

std.Build.Step.CheckFile

别名

第 62 行

别名目标 std.Build.Step.CheckFile

std.Build.Step.Compile

别名

第 63 行

别名目标 std.Build.Step.Compile

std.Build.Step.ConfigHeader

别名

第 64 行

别名目标 std.Build.Step.ConfigHeader

std.Build.Step.Configuration

别名

第 6 行

别名目标 std.Build.Configuration

std.Build.Step.dependOn

函数

第 110 行

pub fn dependOn(step: *Step, other: *Step) void

参数

step: *Step
other: *Step

std.Build.Step.dump

函数

第 121 行

为调试打印此 Step 的标识信息。

pub fn dump(step: *Step, t: std.Io.Terminal) void

参数

step: *Step
t: std.Io.Terminal

std.Build.Step.Fail

别名

第 65 行

别名目标 std.Build.Step.Fail

std.Build.Step.FindProgram

别名

第 66 行

别名目标 std.Build.Step.FindProgram

std.Build.Step.Fmt

别名

第 67 行

别名目标 std.Build.Step.Fmt

std.Build.Step.init

函数

第 93 行

pub fn init(options: StepOptions) Step

参数

options: StepOptions

std.Build.Step.InstallArtifact

别名

第 68 行

别名目标 std.Build.Step.InstallArtifact

std.Build.Step.InstallDir

别名

第 69 行

别名目标 std.Build.Step.InstallDir

std.Build.Step.InstallFile

别名

第 70 行

别名目标 std.Build.Step.InstallFile

std.Build.Step.ObjCopy

别名

第 71 行

别名目标 std.Build.Step.ObjCopy

std.Build.Step.Options

别名

第 72 行

别名目标 std.Build.Step.Options

std.Build.Step.Run

别名

第 73 行

别名目标 std.Build.Step.Run

std.Build.Step.std

别名

第 3 行

别名目标 std

std.Build.Step.Step

别名

第 1 行

别名目标 std.Build.Step

std.Build.Step.StepOptions

容器

第 85 行

字段

tag: Tag
name: []const u8
owner: *Build
first_ret_addr: ?usize = null
max_rss: u64 = 0

std.Build.Step.Tag

别名

第 39 行

别名目标 std.Build.Configuration.Step.Tag

std.Build.Step.TopLevel

容器

第 78 行

字段

step: Step
description: []const u8

std.Build.Step.TopLevel.base_tag

常量

第 79 行

Step.Tag

std.Build.Step.TranslateC

别名

第 74 行

别名目标 std.Build.Step.TranslateC

std.Build.Step.Type

类型函数

第 41 行

pub fn Type(comptime tag: Tag) type

参数

tag: Tag

std.Build.Step.UpdateSourceFiles

别名

第 75 行

别名目标 std.Build.Step.UpdateSourceFiles

std.Build.Step.WriteFile

别名

第 76 行

别名目标 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;
}