跳转到内容

std.Build.Step.Run

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

第 1 行

字段

step: Step
argv: std.ArrayList(Arg)

直接修改此项时,另见 addArg 和 addArgs

cwd: ?Build.LazyPath

使用 setCwd 设置初始当前工作目录

environ_map: ?*EnvMap

覆盖此字段以修改环境,或使用 setEnvironmentVariable

preopens: std.array_hash_map.Auto(Configuration.String, Build.LazyPath)

将提供给父进程的命名文件。 另见 std.process.Preopens。

color: Color = .auto

控制 NO_COLOR 和 CLICOLOR_FORCE 环境变量。

disable_zig_progress: bool

为 true 时,阻止向子进程传递 ZIG_PROGRESS 环境变量;否则子进程会使用该变量 向父进程发送进度更新。

stdio: StdIo

配置 Run 步骤是否视为具有副作用,以及 是否继承标准输入输出流并将其转发给 父进程。继承时需要全局锁,以防与此 Run 步骤关联的子进程运行期间,其他步骤 干扰标准输入输出。 如果 Run 步骤被判定为没有副作用,且所有 输出文件都已是最新、输入文件也未改变, 则跳过执行。

stdin: StdIn

若 stdio 为 inherit,此字段必须为 .none。 只能使用 setStdIn 设置。

file_inputs: std.ArrayList(std.Build.LazyPath)

额外的输入文件;当其被修改时,表示 Run 步骤 应重新执行。 若判定 Run 步骤具有副作用,则无论 这些文件是否修改,只要该步骤出现在构建图中, 就始终执行。

rename_step_with_output_arg: bool

添加输出参数后,此步骤默认会重命名自身, 以便在构建摘要中显示更合适的名称。 设为 false 可禁用此行为。

skip_foreign_checks: bool

如果为 true,则对于被配置为检查所执行二进制文件输出的 Run 步骤, 如果二进制文件因其面向的系统不同于运行构建图的 宿主系统而无法执行, 该步骤不会使构建失败。

-fqemu 和 -fwasmtime 等命令行参数可能影响 二进制文件是否被判定为其他系统的文件;Rosetta(macOS) 和 binfmt_misc(Linux)等系统配置也会产生影响。

如果此 Run 步骤被视为具有副作用,则此标志 不起作用。

failing_to_execute_foreign_is_an_error: bool

若为 true,无法执行异平台二进制文件将视为 错误。若为 false,失败时改为跳过此步骤。

这允许 Run 步骤尝试使用外部执行器(例如 qemu) 执行异平台二进制文件,而在执行器不可用时不会失败。

stdio_limit: std.Io.Limit

如果标准错误或标准输出超过此大小, 则终止子进程,并使该步骤失败。

captured_stdout: ?*CapturedStdIo
captured_stderr: ?*CapturedStdIo
has_side_effects: bool
producer: ?*Step.Compile

若此 Run 步骤由 Compile 步骤生成,则在此跟踪。

std.Build.Step.Run.addArg

函数

第 567 行

将 arg 的内容原样追加到 传给待运行进程的命令行。

若 arg 是输入文件,必须改用 addFileInput 或相关 函数,以确保缓存行为正确。

若 arg 是输出文件,必须改用 addOutputFileArg 或相关 函数,以确保缓存行为正确。

pub fn addArg(run: *Run, arg: []const u8) void

参数

run: *Run
arg: []const u8

std.Build.Step.Run.addArgs

函数

第 581 行

将 args 中每个元素原样追加到要传给 所运行进程的命令行中。

如果 args 中有元素是输入文件,则必须改用 addFileInput, 以确保正确的缓存行为。

如果 args 中有元素是输出文件,则必须改用 addOutputFileArg 或相关 函数,以确保正确的缓存行为。

pub fn addArgs(run: *Run, args: []const []const u8) void

参数

run: *Run
args: []const []const u8

std.Build.Step.Run.addArtifactArg

函数

第 271 行

已弃用,请使用 addArtifactArg2。

pub fn addArtifactArg(run: *Run, artifact: *Step.Compile) void

参数

run: *Run
artifact: *Step.Compile

std.Build.Step.Run.addArtifactArg2

函数

第 280 行

pub fn addArtifactArg2(run: *Run, artifact: *Step.Compile, options: PathArgOptions) void

参数

run: *Run
artifact: *Step.Compile
options: PathArgOptions

std.Build.Step.Run.addCheck

函数

第 737 行

pub fn addCheck(run: *Run, new_check: StdIo.Check) void

参数

run: *Run
new_check: StdIo.Check

std.Build.Step.Run.addDecoratedDirectoryArg

函数

第 502 行

已弃用,请使用 addDirectoryArg2。

pub fn addDecoratedDirectoryArg( run: *Run, prefix: []const u8, lazy_directory: std.Build.LazyPath, suffix: []const u8, ) void

参数

run: *Run
prefix: []const u8
lazy_directory: std.Build.LazyPath
suffix: []const u8

std.Build.Step.Run.addDepFileOutputArg

函数

第 528 行

已弃用,请使用 addDepFileOutputArg2。

pub fn addDepFileOutputArg(run: *Run, basename: []const u8) std.Build.LazyPath

参数

run: *Run
basename: []const u8

std.Build.Step.Run.addDepFileOutputArg2

函数

第 540 行

添加指向依赖文件(.d)的路径参数,让子进程将 发现的额外依赖写入其中。 每个实例仅允许一个依赖文件参数。

pub fn addDepFileOutputArg2(run: *Run, basename: []const u8, options: PathArgOptions) std.Build.LazyPath

参数

run: *Run
basename: []const u8
options: PathArgOptions

std.Build.Step.Run.addDirectoryArg

函数

第 492 行

已弃用,请使用 addDirectoryArg2。

pub fn addDirectoryArg(run: *Run, lazy_directory: std.Build.LazyPath) void

参数

run: *Run
lazy_directory: std.Build.LazyPath

std.Build.Step.Run.addDirectoryArg2

函数

第 511 行

pub fn addDirectoryArg2( run: *Run, lazy_directory: std.Build.LazyPath, options: PathArgOptions, ) void

参数

run: *Run
lazy_directory: std.Build.LazyPath
options: PathArgOptions

std.Build.Step.Run.addFileArg

函数

第 355 行

参见 addFileArg2。

pub fn addFileArg(run: *Run, lp: std.Build.LazyPath) void

参数

run: *Run
lp: std.Build.LazyPath

std.Build.Step.Run.addFileArg2

函数

第 375 行

将输入文件添加指定字符串前缀后,追加为命令行参数。

例如,前缀 "-F" 会使子进程看到 类似 "-Fexample.txt" 的参数。

即使前缀包含空格, 子进程也只会看到一个参数。后续构建 会将文件修改检测为缓存未命中,从而重新执行子进程。

相关函数:

pub fn addFileArg2(run: *Run, lp: std.Build.LazyPath, options: PathArgOptions) void

参数

run: *Run
lp: std.Build.LazyPath
options: PathArgOptions

std.Build.Step.Run.addFileContentArg

函数

第 390 行

已弃用,使用 addFileContentArg2。

pub fn addFileContentArg(run: *Run, lp: std.Build.LazyPath) void

参数

run: *Run
lp: std.Build.LazyPath

std.Build.Step.Run.addFileContentArg2

函数

第 417 行

将输入文件的内容添加指定字符串前缀后,追加为命令行参数。

例如,前缀 "-F" 会使子进程看到 类似 "-Fmy file content" 的内容。

即使前缀或文件内容包含空白字符, 子进程也只会看到一个参数。 也就是说,直至 EOF 的全部文件内容均呈现为一个连续 字符串,包括转义序列。尤其是任何末尾换行 都会以如下形式出现:"hello,\nfile world!\n"。

后续构建会将源文件的修改检测为缓存未命中, 从而重新执行子进程。

此函数不能用于提供 Run 步骤的第一个参数。

相关函数:

pub fn addFileContentArg2(run: *Run, lp: std.Build.LazyPath, options: ArgOptions) void

参数

run: *Run
lp: std.Build.LazyPath
options: ArgOptions

std.Build.Step.Run.addFileInput

函数

第 808 行

添加一个额外的输入文件;当其被修改时,表示此 Run 步骤应重新执行。 若判定 Run 步骤具有副作用,则无论 此文件是否修改,只要该步骤出现在构建图中, 就始终执行。

pub fn addFileInput(run: *Run, file_input: std.Build.LazyPath) void

参数

run: *Run
file_input: std.Build.LazyPath

std.Build.Step.Run.addOutputDirectoryArg

函数

第 438 行

已弃用,使用 addOutputDirectoryArg2。

pub fn addOutputDirectoryArg(run: *Run, basename: []const u8) std.Build.LazyPath

参数

run: *Run
basename: []const u8

std.Build.Step.Run.addOutputDirectoryArg2

函数

第 465 行

将目录路径作为命令行参数提供给正在运行的命令。 断言 basename 非空。

例如,前缀 "-o" 和 basename "output_dir" 会使 子进程看到类似 "-ozig-cache/.../output_dir" 的参数。

不论前缀或 basename 是否包含空格, 子进程均只会看到一个参数。

返回的 std.Build.LazyPath 可用作构建系统 其他 API 的输入。

相关函数:

pub fn addOutputDirectoryArg2( run: *Run, basename: []const u8, options: PathArgOptions, ) std.Build.LazyPath

参数

run: *Run
basename: []const u8
options: PathArgOptions

std.Build.Step.Run.addOutputFileArg

函数

第 297 行

已弃用,请使用 addOutputFileArg2。

pub fn addOutputFileArg(run: *Run, sub_path: []const u8) std.Build.LazyPath

参数

run: *Run
sub_path: []const u8

std.Build.Step.Run.addOutputFileArg2

函数

第 323 行

将文件路径作为命令行参数传给要运行的命令。

例如,前缀为 "-o"、sub_path 为 "output.txt" 时, 子进程会看到类似的参数:"-ozig-cache/.../output.txt"。

无论前缀或 sub_path 是否包含空格, 子进程看到的都是单个参数。

返回的 std.Build.LazyPath 可以作为整个构建系统中 其他 API 的输入。

相关方法:

  • addFileArg:用于传给子进程的输入文件
pub fn addOutputFileArg2( run: *Run, sub_path: []const u8, options: PathArgOptions, ) std.Build.LazyPath

参数

run: *Run
sub_path: []const u8

生成的输出文件名,可以包含零个或多个路径 分量。

断言其非空。

options: PathArgOptions

std.Build.Step.Run.addPassthruArgs

函数

第 593 行

将传给 zig build 的额外参数,追加到将传给所运行进程的命令行。

这会使该步骤被视为具有副作用,从而禁用缓存。

例如,命令 zig build run -- arg1 arg2 中的“arg1”和“arg2”将传给所运行进程。

pub fn addPassthruArgs(run: *Run) void

参数

run: *Run

std.Build.Step.Run.addPrefixedArtifactArg

函数

第 276 行

已弃用,请使用 addArtifactArg2。

pub fn addPrefixedArtifactArg(run: *Run, prefix: []const u8, artifact: *Step.Compile) void

参数

run: *Run
prefix: []const u8
artifact: *Step.Compile

std.Build.Step.Run.addPrefixedDepFileOutputArg

函数

第 533 行

已弃用,请使用 addDepFileOutputArg2。

pub fn addPrefixedDepFileOutputArg(run: *Run, prefix: []const u8, basename: []const u8) std.Build.LazyPath

参数

run: *Run
prefix: []const u8
basename: []const u8

std.Build.Step.Run.addPrefixedDirectoryArg

函数

第 497 行

已弃用,请使用 addDirectoryArg2。

pub fn addPrefixedDirectoryArg(run: *Run, prefix: []const u8, lazy_directory: std.Build.LazyPath) void

参数

run: *Run
prefix: []const u8
lazy_directory: std.Build.LazyPath

std.Build.Step.Run.addPrefixedFileArg

函数

第 360 行

参见 addFileArg2。

pub fn addPrefixedFileArg(run: *Run, prefix: []const u8, lp: std.Build.LazyPath) void

参数

run: *Run
prefix: []const u8
lp: std.Build.LazyPath

std.Build.Step.Run.addPrefixedFileContentArg

函数

第 395 行

已弃用,使用 addFileContentArg2。

pub fn addPrefixedFileContentArg(run: *Run, prefix: []const u8, lp: std.Build.LazyPath) void

参数

run: *Run
prefix: []const u8
lp: std.Build.LazyPath

std.Build.Step.Run.addPrefixedOutputDirectoryArg

函数

第 443 行

已弃用,使用 addOutputDirectoryArg2。

pub fn addPrefixedOutputDirectoryArg( run: *Run, prefix: []const u8, basename: []const u8, ) std.Build.LazyPath

参数

run: *Run
prefix: []const u8
basename: []const u8

std.Build.Step.Run.addPrefixedOutputFileArg

函数

第 302 行

已弃用,请使用 addOutputFileArg2。

pub fn addPrefixedOutputFileArg( run: *Run, prefix: []const u8, sub_path: []const u8, ) std.Build.LazyPath

参数

run: *Run
prefix: []const u8
sub_path: []const u8

std.Build.Step.Run.addThirdPartyEnabledArgDarling

函数

第 601 行

根据传给 zig build 的 -fdarling 值,在命令行中追加自定义字符串。

pub fn addThirdPartyEnabledArgDarling(run: *Run, toggle_flags: ToggleFlags) void

参数

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.addThirdPartyEnabledArgQemu

函数

第 609 行

根据传给 zig build 的 -fqemu 值, 向命令行追加自定义字符串。

pub fn addThirdPartyEnabledArgQemu(run: *Run, toggle_flags: ToggleFlags) void

参数

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.addThirdPartyEnabledArgRosetta

函数

第 617 行

根据传给 zig build 的 -frosetta 值, 向命令行追加自定义字符串。

pub fn addThirdPartyEnabledArgRosetta(run: *Run, toggle_flags: ToggleFlags) void

参数

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.addThirdPartyEnabledArgWasmtime

函数

第 625 行

根据传给 zig build 的 -fwasmtime 值, 向命令行追加自定义字符串。

pub fn addThirdPartyEnabledArgWasmtime(run: *Run, toggle_flags: ToggleFlags) void

参数

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.addThirdPartyEnabledArgWine

函数

第 633 行

根据传给 zig build 的 -fwine 值,在命令行中追加自定义字符串。

pub fn addThirdPartyEnabledArgWine(run: *Run, toggle_flags: ToggleFlags) void

参数

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.Arg

容器

第 145 行

字段

artifact: DecoratedArtifact
lazy_path: DecoratedLazyPath
decorated_directory: DecoratedLazyPath
file_content: DecoratedFileContent
bytes: []const u8
output_file: *Output
output_file_dep: *Output
output_directory: *Output
passthru

"zig build" 命令行中 "--" 之后传入的参数。

enable_darling: ToggleFlags
enable_qemu: ToggleFlags
enable_rosetta: ToggleFlags
enable_wasmtime: ToggleFlags
enable_wine: ToggleFlags

std.Build.Step.Run.ArgOptions

容器

第 257 行

字段

prefix: []const u8 = ""
suffix: []const u8 = ""

std.Build.Step.Run.assert

别名

第 12 行

别名目标 std.debug.assert

std.Build.Step.Run.base_tag

常量

第 16 行

Step.Tag

std.Build.Step.Run.Build

别名

第 6 行

别名目标 std.Build

std.Build.Step.Run.builtin

常量

第 2 行

std.Build.Step.Run.CapturedStdIo

容器

第 199 行

字段

generated_file: Configuration.GeneratedFileIndex
prefix: []const u8
basename: []const u8
trim_whitespace: TrimWhitespace

std.Build.Step.Run.CapturedStdIo.Options

容器

第 205 行

字段

basename: ?[]const u8 = null

null 表示 stdout/stderr。

trim_whitespace: TrimWhitespace = .none

std.Build.Step.Run.CapturedStdIo.TrimWhitespace

别名

第 212 行

别名目标 std.Build.Configuration.Step.Run.TrimWhitespace

std.Build.Step.Run.captureStdErr

函数

第 757 行

pub fn captureStdErr(run: *Run, options: CapturedStdIo.Options) std.Build.LazyPath

参数

run: *Run
options: CapturedStdIo.Options

std.Build.Step.Run.captureStdOut

函数

第 780 行

pub fn captureStdOut(run: *Run, options: CapturedStdIo.Options) std.Build.LazyPath

参数

run: *Run
options: CapturedStdIo.Options

std.Build.Step.Run.clearEnvironment

函数

第 653 行

pub fn clearEnvironment(run: *Run) void

参数

run: *Run

std.Build.Step.Run.Color

别名

第 99 行

别名目标 std.Build.Configuration.Step.Run.Color

std.Build.Step.Run.Configuration

别名

第 14 行

别名目标 std.Build.Configuration

std.Build.Step.Run.create

函数

第 215 行

pub fn create(owner: *std.Build, name: []const u8) *Run

参数

owner: *std.Build
name: []const u8

std.Build.Step.Run.DecoratedArtifact

容器

第 171 行

字段

prefix: []const u8
suffix: []const u8
artifact: *Step.Compile
make_absolute: bool

std.Build.Step.Run.DecoratedFileContent

容器

第 185 行

字段

prefix: []const u8
lazy_path: std.Build.LazyPath
suffix: []const u8

std.Build.Step.Run.DecoratedLazyPath

容器

第 178 行

字段

prefix: []const u8
lazy_path: std.Build.LazyPath
suffix: []const u8
make_absolute: bool

std.Build.Step.Run.Dir

别名

第 8 行

别名目标 std.Io.Dir

std.Build.Step.Run.enableProtocolMode

函数

第 253 行

pub fn enableProtocolMode(run: *Run) void

参数

run: *Run

std.Build.Step.Run.enableTestRunnerMode

函数

第 249 行

已弃用,请使用 enableProtocolMode。

pub fn enableTestRunnerMode(run: *Run) void

参数

run: *Run

std.Build.Step.Run.EnvMap

别名

第 11 行

别名目标 std.process.Environ.Map

std.Build.Step.Run.expectExitCode

函数

第 724 行

pub fn expectExitCode(run: *Run, code: u8) void

参数

run: *Run
code: u8

std.Build.Step.Run.expectStdErrEqual

函数

第 698 行

添加标准错误精确匹配检查。不添加任何其他检查。

pub fn expectStdErrEqual(run: *Run, bytes: []const u8) void

参数

run: *Run
bytes: []const u8

std.Build.Step.Run.expectStdErrMatch

函数

第 703 行

pub fn expectStdErrMatch(run: *Run, bytes: []const u8) void

参数

run: *Run
bytes: []const u8

std.Build.Step.Run.expectStdOutEqual

函数

第 710 行

添加 stdout 精确匹配检查;若尚无预期终止检查,则还添加退出码为 0 的检查。

pub fn expectStdOutEqual(run: *Run, bytes: []const u8) void

参数

run: *Run
bytes: []const u8

std.Build.Step.Run.expectStdOutMatch

函数

第 718 行

若尚未设置预期终止检查,则添加标准输出匹配检查, 以及退出码为 0 的检查。

pub fn expectStdOutMatch(run: *Run, bytes: []const u8) void

参数

run: *Run
bytes: []const u8

std.Build.Step.Run.getEnvMap

函数

第 660 行

pub fn getEnvMap(run: *Run) *EnvMap

参数

run: *Run

std.Build.Step.Run.getEnvMapInternal

函数

第 664 行

fn getEnvMapInternal(run: *Run) *EnvMap

参数

run: *Run

std.Build.Step.Run.hasTermCheck

函数

第 729 行

pub fn hasTermCheck(run: Run) bool

参数

run: Run

std.Build.Step.Run.Io

别名

第 5 行

别名目标 std.Io

std.Build.Step.Run.mem

别名

第 9 行

别名目标 std.mem

std.Build.Step.Run.Output

容器

第 191 行

字段

generated_file: Configuration.GeneratedFileIndex
prefix: []const u8
basename: []const u8
suffix: []const u8
make_absolute: bool

std.Build.Step.Run.Path

别名

第 13 行

别名目标 std.Build.Cache.Path

std.Build.Step.Run.PathArgOptions

容器

第 262 行

字段

prefix: []const u8 = ""
suffix: []const u8 = ""
make_absolute: bool = false

传给子进程前,将路径转换为绝对路径。并非所有宿主均支持, 应尽可能优先接受相对路径。

std.Build.Step.Run.process

别名

第 10 行

别名目标 std.process

std.Build.Step.Run.removeEnvironmentVariable

函数

第 681 行

pub fn removeEnvironmentVariable(run: *Run, key: []const u8) void

参数

run: *Run
key: []const u8

std.Build.Step.Run.Run

别名

第 1 行

别名目标 std.Build.Step.Run

std.Build.Step.Run.setCwd

函数

第 647 行

pub fn setCwd(run: *Run, cwd: Build.LazyPath) void

参数

run: *Run
cwd: Build.LazyPath

std.Build.Step.Run.setEnvironmentVariable

函数

第 675 行

pub fn setEnvironmentVariable(run: *Run, key: []const u8, value: []const u8) void

参数

run: *Run
key: []const u8
value: []const u8

std.Build.Step.Run.setName

函数

第 243 行

pub fn setName(run: *Run, name: []const u8) void

参数

run: *Run
name: []const u8

std.Build.Step.Run.setPreopen

函数

第 685 行

pub fn setPreopen(run: *Run, name: []const u8, resource: Build.LazyPath) void

参数

run: *Run
name: []const u8
resource: Build.LazyPath

std.Build.Step.Run.setStdIn

函数

第 639 行

pub fn setStdIn(run: *Run, stdin: StdIn) void

参数

run: *Run
stdin: StdIn

std.Build.Step.Run.std

别名

第 4 行

别名目标 std

std.Build.Step.Run.StdIn

容器

第 101 行

字段

none
bytes: []const u8
lazy_path: std.Build.LazyPath

std.Build.Step.Run.StdIo

容器

第 107 行

字段

infer_from_args

根据参数中是否包含输出文件 (通过 addOutputFileArg 添加)来确定 Run 步骤是否具有副作用。 若判定 Run 步骤具有副作用,则等同于 inherit。 若子进程崩溃或返回非零退出码,该步骤失败。

inherit

使 Run 步骤被视为具有副作用,因此 只要它出现在构建图中就始终执行。 这也意味着该步骤会获取全局锁,阻止其他 步骤在此期间运行。 若子进程崩溃或返回非零退出码,该步骤失败。

check: std.ArrayList(Check)

使 Run 步骤被视为没有副作用。 如果任何输入依赖被修改,则重新 执行进程。检查退出码和标准输入输出流 是否满足某些条件,步骤是否成功取决于 这些条件。 注意,如果希望检查退出码为 0,必须将此检查 显式加入列表。

zig_test

此 Run 步骤运行 Zig 单元测试二进制文件,并通过 IPC 协议交换额外元数据。 已弃用,请使用 .protocol。

protocol

此 Run 步骤运行的二进制文件将通过 IPC 协议通信。

std.Build.Step.Run.StdIo.Check

容器

第 134 行

字段

expect_stderr_exact: []const u8
expect_stderr_match: []const u8
expect_stdout_exact: []const u8
expect_stdout_match: []const u8
expect_term: process.Child.Term
expect_stderr_snapshot: std.Build.LazyPath
expect_stdout_snapshot: std.Build.LazyPath

std.Build.Step.Run.Step

别名

第 7 行

别名目标 std.Build.Step

std.Build.Step.Run.ToggleFlags

容器

第 164 行

字段

enabled: ?[]const u8 = null

启用时传入的字符串;若为 null,则省略此参数。

disabled: ?[]const u8 = null

禁用时传入的字符串;若为 null,则省略此参数。

源码

std/Build/Step/Run.zig

const Run = @This();
const builtin = @import("builtin");

const std = @import("std");
const Io = std.Io;
const Build = std.Build;
const Step = std.Build.Step;
const Dir = std.Io.Dir;
const mem = std.mem;
const process = std.process;
const EnvMap = std.process.Environ.Map;
const assert = std.debug.assert;
const Path = std.Build.Cache.Path;
const Configuration = std.Build.Configuration;

pub const base_tag: Step.Tag = .run;

step: Step,

/// 直接修改此项时,另见 addArg 和 addArgs
argv: std.ArrayList(Arg),

/// 使用 `setCwd` 设置初始当前工作目录
cwd: ?Build.LazyPath,

/// 覆盖此字段以修改环境,或使用 setEnvironmentVariable
environ_map: ?*EnvMap,

/// 将提供给父进程的命名文件。
/// 另见 `std.process.Preopens`。
preopens: std.array_hash_map.Auto(Configuration.String, Build.LazyPath),

/// 控制 `NO_COLOR` 和 `CLICOLOR_FORCE` 环境变量。
color: Color = .auto,

/// 为 `true` 时,阻止向子进程传递 `ZIG_PROGRESS`
/// 环境变量;否则子进程会使用该变量
/// 向父进程发送进度更新。
disable_zig_progress: bool,

/// 配置 Run 步骤是否视为具有副作用,以及
/// 是否继承标准输入输出流并将其转发给
/// 父进程。继承时需要全局锁,以防与此
/// Run 步骤关联的子进程运行期间,其他步骤
/// 干扰标准输入输出。
/// 如果 Run 步骤被判定为没有副作用,且所有
/// 输出文件都已是最新、输入文件也未改变,
/// 则跳过执行。
stdio: StdIo,

/// 若 stdio 为 `inherit`,此字段必须为 `.none`。
/// 只能使用 `setStdIn` 设置。
stdin: StdIn,

/// 额外的输入文件;当其被修改时,表示 Run 步骤
/// 应重新执行。
/// 若判定 Run 步骤具有副作用,则无论
/// 这些文件是否修改,只要该步骤出现在构建图中,
/// 就始终执行。
file_inputs: std.ArrayList(std.Build.LazyPath),

/// 添加输出参数后,此步骤默认会重命名自身,
/// 以便在构建摘要中显示更合适的名称。
/// 设为 false 可禁用此行为。
rename_step_with_output_arg: bool,

/// 如果为 true,则对于被配置为检查所执行二进制文件输出的 Run 步骤,
/// 如果二进制文件因其面向的系统不同于运行构建图的
/// 宿主系统而无法执行,
/// 该步骤不会使构建失败。
///
/// -fqemu 和 -fwasmtime 等命令行参数可能影响
/// 二进制文件是否被判定为其他系统的文件;Rosetta(macOS)
/// 和 binfmt_misc(Linux)等系统配置也会产生影响。
///
/// 如果此 Run 步骤被视为具有副作用,则此标志
/// 不起作用。
skip_foreign_checks: bool,

/// 若为 true,无法执行异平台二进制文件将视为
/// 错误。若为 false,失败时改为跳过此步骤。
///
/// 这允许 Run 步骤尝试使用外部执行器(例如 qemu)
/// 执行异平台二进制文件,而在执行器不可用时不会失败。
failing_to_execute_foreign_is_an_error: bool,

/// 如果标准错误或标准输出超过此大小,
/// 则终止子进程,并使该步骤失败。
stdio_limit: std.Io.Limit,

captured_stdout: ?*CapturedStdIo,
captured_stderr: ?*CapturedStdIo,

has_side_effects: bool,

/// 若此 Run 步骤由 Compile 步骤生成,则在此跟踪。
producer: ?*Step.Compile,

pub const Color = std.Build.Configuration.Step.Run.Color;

pub const StdIn = union(enum) {
    none,
    bytes: []const u8,
    lazy_path: std.Build.LazyPath,
};

pub const StdIo = union(enum) {
    /// 根据参数中是否包含输出文件
    /// (通过 `addOutputFileArg` 添加)来确定 Run 步骤是否具有副作用。
    /// 若判定 Run 步骤具有副作用,则等同于 `inherit`。
    /// 若子进程崩溃或返回非零退出码,该步骤失败。
    infer_from_args,
    /// 使 Run 步骤被视为具有副作用,因此
    /// 只要它出现在构建图中就始终执行。
    /// 这也意味着该步骤会获取全局锁,阻止其他
    /// 步骤在此期间运行。
    /// 若子进程崩溃或返回非零退出码,该步骤失败。
    inherit,
    /// 使 Run 步骤被视为*没有*副作用。
    /// 如果任何输入依赖被修改,则重新
    /// 执行进程。检查退出码和标准输入输出流
    /// 是否满足某些条件,步骤是否成功取决于
    /// 这些条件。
    /// 注意,如果希望检查退出码为 0,必须将此检查
    /// 显式加入列表。
    check: std.ArrayList(Check),
    /// 此 Run 步骤运行 Zig 单元测试二进制文件,并通过 IPC 协议交换额外元数据。
    /// 已弃用,请使用 `.protocol`。
    ///
    zig_test,
    /// 此 Run 步骤运行的二进制文件将通过 IPC 协议通信。
    protocol,

    pub const Check = union(enum) {
        expect_stderr_exact: []const u8,
        expect_stderr_match: []const u8,
        expect_stdout_exact: []const u8,
        expect_stdout_match: []const u8,
        expect_term: process.Child.Term,
        expect_stderr_snapshot: std.Build.LazyPath,
        expect_stdout_snapshot: std.Build.LazyPath,
    };
};

pub const Arg = union(enum) {
    artifact: DecoratedArtifact,
    lazy_path: DecoratedLazyPath,
    decorated_directory: DecoratedLazyPath,
    file_content: DecoratedFileContent,
    bytes: []const u8,
    output_file: *Output,
    output_file_dep: *Output,
    output_directory: *Output,
    /// "zig build" 命令行中 "--" 之后传入的参数。
    passthru,

    enable_darling: ToggleFlags,
    enable_qemu: ToggleFlags,
    enable_rosetta: ToggleFlags,
    enable_wasmtime: ToggleFlags,
    enable_wine: ToggleFlags,
};

pub const ToggleFlags = struct {
    /// 启用时传入的字符串;若为 null,则省略此参数。
    enabled: ?[]const u8 = null,
    /// 禁用时传入的字符串;若为 null,则省略此参数。
    disabled: ?[]const u8 = null,
};

pub const DecoratedArtifact = struct {
    prefix: []const u8,
    suffix: []const u8,
    artifact: *Step.Compile,
    make_absolute: bool,
};

pub const DecoratedLazyPath = struct {
    prefix: []const u8,
    lazy_path: std.Build.LazyPath,
    suffix: []const u8,
    make_absolute: bool,
};

pub const DecoratedFileContent = struct {
    prefix: []const u8,
    lazy_path: std.Build.LazyPath,
    suffix: []const u8,
};

pub const Output = struct {
    generated_file: Configuration.GeneratedFileIndex,
    prefix: []const u8,
    basename: []const u8,
    suffix: []const u8,
    make_absolute: bool,
};

pub const CapturedStdIo = struct {
    generated_file: Configuration.GeneratedFileIndex,
    prefix: []const u8,
    basename: []const u8,
    trim_whitespace: TrimWhitespace,

    pub const Options = struct {
        /// `null` 表示 `stdout`/`stderr`。
        basename: ?[]const u8 = null,
        /// 不影响 `expectStdOutEqual`/`expectStdErrEqual`。
        trim_whitespace: TrimWhitespace = .none,
    };

    pub const TrimWhitespace = std.Build.Configuration.Step.Run.TrimWhitespace;
};

pub fn create(owner: *std.Build, name: []const u8) *Run {
    const run = owner.allocator.create(Run) catch @panic("OOM");
    run.* = .{
        .step = .init(.{
            .tag = base_tag,
            .name = name,
            .owner = owner,
        }),
        .argv = .empty,
        .cwd = null,
        .environ_map = null,
        .preopens = .empty,
        .disable_zig_progress = false,
        .stdio = .infer_from_args,
        .stdin = .none,
        .file_inputs = .empty,
        .rename_step_with_output_arg = true,
        .skip_foreign_checks = false,
        .failing_to_execute_foreign_is_an_error = true,
        .stdio_limit = .unlimited,
        .captured_stdout = null,
        .captured_stderr = null,
        .has_side_effects = false,
        .producer = null,
    };
    return run;
}

pub fn setName(run: *Run, name: []const u8) void {
    run.step.name = run.step.owner.graph.dupeString(name);
    run.rename_step_with_output_arg = false;
}

/// 已弃用,请使用 `enableProtocolMode`。
pub fn enableTestRunnerMode(run: *Run) void {
    run.stdio = .zig_test;
}

pub fn enableProtocolMode(run: *Run) void {
    run.stdio = .protocol;
}

pub const ArgOptions = struct {
    prefix: []const u8 = "",
    suffix: []const u8 = "",
};

pub const PathArgOptions = struct {
    prefix: []const u8 = "",
    suffix: []const u8 = "",
    /// 传给子进程前,将路径转换为绝对路径。并非所有宿主均支持,
    /// 应尽可能优先接受相对路径。
    make_absolute: bool = false,
};

/// 已弃用,请使用 `addArtifactArg2`。
pub fn addArtifactArg(run: *Run, artifact: *Step.Compile) void {
    run.addArtifactArg2(artifact, .{});
}

/// 已弃用,请使用 `addArtifactArg2`。
pub fn addPrefixedArtifactArg(run: *Run, prefix: []const u8, artifact: *Step.Compile) void {
    run.addArtifactArg2(artifact, .{ .prefix = prefix });
}

pub fn addArtifactArg2(run: *Run, artifact: *Step.Compile, options: PathArgOptions) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;

    const prefixed_artifact: DecoratedArtifact = .{
        .prefix = graph.dupeString(options.prefix),
        .artifact = artifact,
        .suffix = graph.dupeString(options.suffix),
        .make_absolute = options.make_absolute,
    };
    run.argv.append(arena, .{ .artifact = prefixed_artifact }) catch @panic("OOM");

    const bin_file = artifact.getEmittedBin();
    bin_file.addStepDependencies(&run.step);
}

/// 已弃用,请使用 `addOutputFileArg2`。
pub fn addOutputFileArg(run: *Run, sub_path: []const u8) std.Build.LazyPath {
    return run.addOutputFileArg2(sub_path, .{});
}

/// 已弃用,请使用 `addOutputFileArg2`。
pub fn addPrefixedOutputFileArg(
    run: *Run,
    prefix: []const u8,
    sub_path: []const u8,
) std.Build.LazyPath {
    return run.addOutputFileArg2(sub_path, .{ .prefix = prefix });
}

/// 将文件路径作为命令行参数传给要运行的命令。
///
/// 例如,前缀为 "-o"、`sub_path` 为 "output.txt" 时,
/// 子进程会看到类似的参数:"-ozig-cache/.../output.txt"。
///
/// 无论前缀或 `sub_path` 是否包含空格,
/// 子进程看到的都是单个参数。
///
/// 返回的 `std.Build.LazyPath` 可以作为整个构建系统中
/// 其他 API 的输入。
///
/// 相关方法:
/// * `addFileArg`:用于传给子进程的输入文件
pub fn addOutputFileArg2(
    run: *Run,
    /// 生成的输出文件名,可以包含零个或多个路径
    /// 分量。
    ///
    /// 断言其非空。
    sub_path: []const u8,
    options: PathArgOptions,
) std.Build.LazyPath {
    const b = run.step.owner;
    const graph = b.graph;
    const arena = graph.arena;
    assert(sub_path.len != 0);

    const output = graph.create(Output);
    output.* = .{
        .prefix = graph.dupeString(options.prefix),
        .basename = graph.dupeString(sub_path),
        .suffix = graph.dupeString(options.suffix),
        .generated_file = graph.addGeneratedFile(&run.step),
        .make_absolute = options.make_absolute,
    };
    run.argv.append(arena, .{ .output_file = output }) catch @panic("OOM");

    if (run.rename_step_with_output_arg) {
        run.setName(b.fmt("{s} ({s})", .{ run.step.name, sub_path }));
    }

    return .{ .generated = .{ .index = output.generated_file } };
}

/// 参见 `addFileArg2`。
pub fn addFileArg(run: *Run, lp: std.Build.LazyPath) void {
    run.addFileArg2(lp, .{});
}

/// 参见 `addFileArg2`。
pub fn addPrefixedFileArg(run: *Run, prefix: []const u8, lp: std.Build.LazyPath) void {
    run.addFileArg2(lp, .{ .prefix = prefix });
}

/// 将输入文件添加指定字符串前缀后,追加为命令行参数。
///
/// 例如,前缀 "-F" 会使子进程看到
/// 类似 "-Fexample.txt" 的参数。
///
/// 即使前缀包含空格,
/// 子进程也只会看到一个参数。后续构建
/// 会将文件修改检测为缓存未命中,从而重新执行子进程。
///
/// 相关函数:
/// * `addOutputFileArg`:用于子进程生成的文件。
pub fn addFileArg2(run: *Run, lp: std.Build.LazyPath, options: PathArgOptions) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;

    const prefixed_file_source: DecoratedLazyPath = .{
        .prefix = graph.dupeString(options.prefix),
        .lazy_path = lp.dupe(graph),
        .suffix = graph.dupeString(options.suffix),
        .make_absolute = options.make_absolute,
    };
    run.argv.append(arena, .{ .lazy_path = prefixed_file_source }) catch @panic("OOM");
    lp.addStepDependencies(&run.step);
}

/// 已弃用,使用 `addFileContentArg2`。
pub fn addFileContentArg(run: *Run, lp: std.Build.LazyPath) void {
    return run.addFileContentArg2(lp, .{});
}

/// 已弃用,使用 `addFileContentArg2`。
pub fn addPrefixedFileContentArg(run: *Run, prefix: []const u8, lp: std.Build.LazyPath) void {
    return run.addFileContentArg2(lp, .{ .prefix = prefix });
}

/// 将输入文件的内容添加指定字符串前缀后,追加为命令行参数。
///
/// 例如,前缀 "-F" 会使子进程看到
/// 类似 "-Fmy file content" 的内容。
///
/// 即使前缀或文件内容包含空白字符,
/// 子进程也只会看到一个参数。
/// 也就是说,直至 EOF 的全部文件内容均呈现为一个连续
/// 字符串,包括转义序列。尤其是任何末尾换行
/// 都会以如下形式出现:"hello,\nfile world!\n"。
///
/// 后续构建会将源文件的修改检测为缓存未命中,
/// 从而重新执行子进程。
///
/// 此函数不能用于提供 `Run` 步骤的第一个参数。
///
/// 相关函数:
/// * `addFileContentArg`:相同功能,但不添加前缀。
pub fn addFileContentArg2(run: *Run, lp: std.Build.LazyPath, options: ArgOptions) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;

    // 此步骤配置阶段 API 的某些部分依赖第一个参数具有一定的
    // 透明性和可读性,但在其路径可于 make 阶段解析之前,
    // `lp` 指定文件的内容仍完全不透明。
    if (run.argv.items.len == 0) {
        @panic("'addFileContentArg'/'addPrefixedFileContentArg' cannot be first argument");
    }

    const file_content: DecoratedFileContent = .{
        .prefix = graph.dupeString(options.prefix),
        .lazy_path = lp.dupe(graph),
        .suffix = graph.dupeString(options.suffix),
    };
    run.argv.append(arena, .{ .file_content = file_content }) catch @panic("OOM");
    lp.addStepDependencies(&run.step);
}

/// 已弃用,使用 `addOutputDirectoryArg2`。
pub fn addOutputDirectoryArg(run: *Run, basename: []const u8) std.Build.LazyPath {
    return run.addOutputDirectoryArg2(basename, .{});
}

/// 已弃用,使用 `addOutputDirectoryArg2`。
pub fn addPrefixedOutputDirectoryArg(
    run: *Run,
    prefix: []const u8,
    basename: []const u8,
) std.Build.LazyPath {
    return run.addOutputDirectoryArg2(basename, .{ .prefix = prefix });
}

/// 将目录路径作为命令行参数提供给正在运行的命令。
/// 断言 `basename` 非空。
///
/// 例如,前缀 "-o" 和 basename "output_dir" 会使
/// 子进程看到类似 "-ozig-cache/.../output_dir" 的参数。
///
/// 不论前缀或 basename 是否包含空格,
/// 子进程均只会看到一个参数。
///
/// 返回的 `std.Build.LazyPath` 可用作构建系统
/// 其他 API 的输入。
///
/// 相关函数:
/// * `addDirectoryArg`:向子进程提供输入目录。
pub fn addOutputDirectoryArg2(
    run: *Run,
    basename: []const u8,
    options: PathArgOptions,
) std.Build.LazyPath {
    if (basename.len == 0) @panic("basename must not be empty");
    const graph = run.step.owner.graph;
    const arena = graph.arena;

    const output = arena.create(Output) catch @panic("OOM");
    output.* = .{
        .prefix = graph.dupeString(options.prefix),
        .basename = graph.dupeString(basename),
        .suffix = graph.dupeString(options.suffix),
        .generated_file = graph.addGeneratedFile(&run.step),
        .make_absolute = options.make_absolute,
    };
    run.argv.append(arena, .{ .output_directory = output }) catch @panic("OOM");

    if (run.rename_step_with_output_arg) {
        run.setName(std.fmt.allocPrint(arena, "{s} ({s})", .{ run.step.name, basename }) catch @panic("OOM"));
    }

    return .{ .generated = .{ .index = output.generated_file } };
}

/// 已弃用,请使用 `addDirectoryArg2`。
pub fn addDirectoryArg(run: *Run, lazy_directory: std.Build.LazyPath) void {
    run.addDirectoryArg2(lazy_directory, .{});
}

/// 已弃用,请使用 `addDirectoryArg2`。
pub fn addPrefixedDirectoryArg(run: *Run, prefix: []const u8, lazy_directory: std.Build.LazyPath) void {
    run.addDirectoryArg2(lazy_directory, .{ .prefix = prefix });
}

/// 已弃用,请使用 `addDirectoryArg2`。
pub fn addDecoratedDirectoryArg(
    run: *Run,
    prefix: []const u8,
    lazy_directory: std.Build.LazyPath,
    suffix: []const u8,
) void {
    run.addDirectoryArg2(lazy_directory, .{ .prefix = prefix, .suffix = suffix });
}

pub fn addDirectoryArg2(
    run: *Run,
    lazy_directory: std.Build.LazyPath,
    options: PathArgOptions,
) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .{ .decorated_directory = .{
        .prefix = graph.dupeString(options.prefix),
        .lazy_path = lazy_directory.dupe(graph),
        .suffix = graph.dupeString(options.suffix),
        .make_absolute = options.make_absolute,
    } }) catch @panic("OOM");
    lazy_directory.addStepDependencies(&run.step);
}

/// 已弃用,请使用 `addDepFileOutputArg2`。
pub fn addDepFileOutputArg(run: *Run, basename: []const u8) std.Build.LazyPath {
    return run.addDepFileOutputArg2(basename, .{});
}

/// 已弃用,请使用 `addDepFileOutputArg2`。
pub fn addPrefixedDepFileOutputArg(run: *Run, prefix: []const u8, basename: []const u8) std.Build.LazyPath {
    return run.addDepFileOutputArg2(basename, .{ .prefix = prefix });
}

/// 添加指向依赖文件(.d)的路径参数,让子进程将
/// 发现的额外依赖写入其中。
/// 每个实例仅允许一个依赖文件参数。
pub fn addDepFileOutputArg2(run: *Run, basename: []const u8, options: PathArgOptions) std.Build.LazyPath {
    const b = run.step.owner;
    const graph = b.graph;
    const arena = graph.arena;

    const dep_file = arena.create(Output) catch @panic("OOM");
    dep_file.* = .{
        .prefix = graph.dupeString(options.prefix),
        .basename = graph.dupeString(basename),
        .suffix = graph.dupeString(options.suffix),
        .generated_file = graph.addGeneratedFile(&run.step),
        .make_absolute = options.make_absolute,
    };

    run.argv.append(arena, .{ .output_file_dep = dep_file }) catch @panic("OOM");

    return .{ .generated = .{ .index = dep_file.generated_file } };
}

/// 将 `arg` 的内容原样追加到
/// 传给待运行进程的命令行。
///
/// 若 `arg` 是输入文件,必须改用 `addFileInput` 或相关
/// 函数,以确保缓存行为正确。
///
/// 若 `arg` 是输出文件,必须改用 `addOutputFileArg` 或相关
/// 函数,以确保缓存行为正确。
pub fn addArg(run: *Run, arg: []const u8) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .{ .bytes = graph.dupeString(arg) }) catch @panic("OOM");
}

/// 将 `args` 中每个元素原样追加到要传给
/// 所运行进程的命令行中。
///
/// 如果 `args` 中有元素是输入文件,则必须改用 `addFileInput`,
/// 以确保正确的缓存行为。
///
/// 如果 `args` 中有元素是输出文件,则必须改用 `addOutputFileArg` 或相关
/// 函数,以确保正确的缓存行为。
pub fn addArgs(run: *Run, args: []const []const u8) void {
    for (args) |arg| run.addArg(arg);
}

/// 将传给 `zig build` 的额外参数,追加到将传给所运行进程的命令行。
///
/// 这会使该步骤被视为具有副作用,从而禁用缓存。
///
/// 例如,命令 `zig build run -- arg1 arg2` 中的“arg1”和“arg2”将传给所运行进程。
///
///
///
pub fn addPassthruArgs(run: *Run) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .passthru) catch @panic("OOM");
}

/// 根据传给 `zig build` 的 `-fdarling`
/// 值,在命令行中追加自定义字符串。
pub fn addThirdPartyEnabledArgDarling(run: *Run, toggle_flags: ToggleFlags) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .{ .enable_darling = toggle_flags }) catch @panic("OOM");
}

/// 根据传给 `zig build` 的 `-fqemu` 值,
/// 向命令行追加自定义字符串。
pub fn addThirdPartyEnabledArgQemu(run: *Run, toggle_flags: ToggleFlags) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .{ .enable_qemu = toggle_flags }) catch @panic("OOM");
}

/// 根据传给 `zig build` 的 `-frosetta` 值,
/// 向命令行追加自定义字符串。
pub fn addThirdPartyEnabledArgRosetta(run: *Run, toggle_flags: ToggleFlags) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .{ .enable_rosetta = toggle_flags }) catch @panic("OOM");
}

/// 根据传给 `zig build` 的 `-fwasmtime` 值,
/// 向命令行追加自定义字符串。
pub fn addThirdPartyEnabledArgWasmtime(run: *Run, toggle_flags: ToggleFlags) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .{ .enable_wasmtime = toggle_flags }) catch @panic("OOM");
}

/// 根据传给 `zig build` 的 `-fwine`
/// 值,在命令行中追加自定义字符串。
pub fn addThirdPartyEnabledArgWine(run: *Run, toggle_flags: ToggleFlags) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .{ .enable_wine = toggle_flags }) catch @panic("OOM");
}

pub fn setStdIn(run: *Run, stdin: StdIn) void {
    switch (stdin) {
        .lazy_path => |lazy_path| lazy_path.addStepDependencies(&run.step),
        .bytes, .none => {},
    }
    run.stdin = stdin;
}

pub fn setCwd(run: *Run, cwd: Build.LazyPath) void {
    const graph = run.step.owner.graph;
    cwd.addStepDependencies(&run.step);
    run.cwd = cwd.dupe(graph);
}

pub fn clearEnvironment(run: *Run) void {
    const b = run.step.owner;
    const new_env_map = b.allocator.create(EnvMap) catch @panic("OOM");
    new_env_map.* = .init(b.allocator);
    run.environ_map = new_env_map;
}

pub fn getEnvMap(run: *Run) *EnvMap {
    return getEnvMapInternal(run);
}

fn getEnvMapInternal(run: *Run) *EnvMap {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    return run.environ_map orelse {
        const cloned_map = arena.create(EnvMap) catch @panic("OOM");
        cloned_map.* = graph.environ_map.clone(arena) catch @panic("OOM");
        run.environ_map = cloned_map;
        return cloned_map;
    };
}

pub fn setEnvironmentVariable(run: *Run, key: []const u8, value: []const u8) void {
    const environ_map = run.getEnvMap();
    // 此数据结构已会复制键和值。
    environ_map.put(key, value) catch @panic("OOM");
}

pub fn removeEnvironmentVariable(run: *Run, key: []const u8) void {
    _ = run.getEnvMap().swapRemove(key);
}

pub fn setPreopen(run: *Run, name: []const u8, resource: Build.LazyPath) void {
    const graph = run.step.owner.graph;
    const wc = &graph.wip_configuration;
    const arena = graph.arena;
    resource.addStepDependencies(&run.step);
    run.preopens.put(
        arena,
        wc.addString(name) catch @panic("OOM"),
        resource.dupe(graph),
    ) catch @panic("OOM");
}

/// 添加标准错误精确匹配检查。不添加任何其他检查。
pub fn expectStdErrEqual(run: *Run, bytes: []const u8) void {
    const graph = run.step.owner.graph;
    run.addCheck(.{ .expect_stderr_exact = graph.dupeString(bytes) });
}

pub fn expectStdErrMatch(run: *Run, bytes: []const u8) void {
    const graph = run.step.owner.graph;
    run.addCheck(.{ .expect_stderr_match = graph.dupeString(bytes) });
}

/// 添加 stdout 精确匹配检查;若尚无预期终止检查,则还添加退出码为 0 的检查。
///
pub fn expectStdOutEqual(run: *Run, bytes: []const u8) void {
    const graph = run.step.owner.graph;
    run.addCheck(.{ .expect_stdout_exact = graph.dupeString(bytes) });
    if (!run.hasTermCheck()) run.expectExitCode(0);
}

/// 若尚未设置预期终止检查,则添加标准输出匹配检查,
/// 以及退出码为 0 的检查。
pub fn expectStdOutMatch(run: *Run, bytes: []const u8) void {
    const graph = run.step.owner.graph;
    run.addCheck(.{ .expect_stdout_match = graph.dupeString(bytes) });
    if (!run.hasTermCheck()) run.expectExitCode(0);
}

pub fn expectExitCode(run: *Run, code: u8) void {
    const new_check: StdIo.Check = .{ .expect_term = .{ .exited = code } };
    run.addCheck(new_check);
}

pub fn hasTermCheck(run: Run) bool {
    for (run.stdio.check.items) |check| switch (check) {
        .expect_term => return true,
        else => continue,
    };
    return false;
}

pub fn addCheck(run: *Run, new_check: StdIo.Check) void {
    const b = run.step.owner;

    switch (run.stdio) {
        .infer_from_args => {
            run.stdio = .{ .check = .empty };
            run.stdio.check.append(b.allocator, new_check) catch @panic("OOM");
        },
        .check => |*checks| checks.append(b.allocator, new_check) catch @panic("OOM"),
        else => @panic("illegal call to addCheck: conflicting helper method calls. Suggest to directly set stdio field of Run instead"),
    }

    switch (new_check) {
        .expect_stderr_snapshot,
        .expect_stdout_snapshot,
        => |file| run.addFileInput(file),
        else => {},
    }
}

pub fn captureStdErr(run: *Run, options: CapturedStdIo.Options) std.Build.LazyPath {
    switch (run.stdio) {
        .infer_from_args, .check => {},
        .inherit, .zig_test, .protocol => unreachable,
    }

    const b = run.step.owner;
    const graph = b.graph;
    const arena = graph.arena;

    if (run.captured_stderr) |captured| return .{ .generated = .{ .index = captured.generated_file } };

    const captured = arena.create(CapturedStdIo) catch @panic("OOM");
    captured.* = .{
        .prefix = "",
        .basename = if (options.basename) |basename| graph.dupeString(basename) else "stderr",
        .generated_file = graph.addGeneratedFile(&run.step),
        .trim_whitespace = options.trim_whitespace,
    };
    run.captured_stderr = captured;
    return .{ .generated = .{ .index = captured.generated_file } };
}

pub fn captureStdOut(run: *Run, options: CapturedStdIo.Options) std.Build.LazyPath {
    switch (run.stdio) {
        .infer_from_args, .check => {},
        .inherit, .zig_test, .protocol => unreachable,
    }

    const b = run.step.owner;
    const graph = b.graph;
    const arena = graph.arena;

    if (run.captured_stdout) |captured| return .{ .generated = .{ .index = captured.generated_file } };

    const captured = arena.create(CapturedStdIo) catch @panic("OOM");
    captured.* = .{
        .prefix = "",
        .basename = if (options.basename) |basename| graph.dupeString(basename) else "stdout",
        .generated_file = graph.addGeneratedFile(&run.step),
        .trim_whitespace = options.trim_whitespace,
    };
    run.captured_stdout = captured;
    return .{ .generated = .{ .index = captured.generated_file } };
}

/// 添加一个额外的输入文件;当其被修改时,表示此 Run
/// 步骤应重新执行。
/// 若判定 Run 步骤具有副作用,则无论
/// 此文件是否修改,只要该步骤出现在构建图中,
/// 就始终执行。
pub fn addFileInput(run: *Run, file_input: std.Build.LazyPath) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    file_input.addStepDependencies(&run.step);
    run.file_inputs.append(arena, file_input.dupe(graph)) catch @panic("OOM");
}