字段
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 步骤生成,则在此跟踪。
RunbuiltinstdIoBuildStepDirmemprocessEnvMapassertPathConfigurationbase_tagColorStdInStdIoArgToggleFlagsDecoratedArtifactDecoratedLazyPathDecoratedFileContentOutputCapturedStdIocreatesetNameenableTestRunnerModeenableProtocolModeArgOptionsPathArgOptionsaddArtifactArgaddPrefixedArtifactArgaddArtifactArg2addOutputFileArgaddPrefixedOutputFileArgaddOutputFileArg2addFileArgaddPrefixedFileArgaddFileArg2addFileContentArgaddPrefixedFileContentArgaddFileContentArg2addOutputDirectoryArgaddPrefixedOutputDirectoryArgaddOutputDirectoryArg2addDirectoryArgaddPrefixedDirectoryArgaddDecoratedDirectoryArgaddDirectoryArg2addDepFileOutputArgaddPrefixedDepFileOutputArgaddDepFileOutputArg2addArgaddArgsaddPassthruArgsaddThirdPartyEnabledArgDarlingaddThirdPartyEnabledArgQemuaddThirdPartyEnabledArgRosettaaddThirdPartyEnabledArgWasmtimeaddThirdPartyEnabledArgWinesetStdInsetCwdclearEnvironmentgetEnvMapgetEnvMapInternalsetEnvironmentVariableremoveEnvironmentVariablesetPreopenexpectStdErrEqualexpectStdErrMatchexpectStdOutEqualexpectStdOutMatchexpectExitCodehasTermCheckaddCheckcaptureStdErrcaptureStdOutaddFileInput
std.Build.Step.Run.addArg
函数
将 arg 的内容原样追加到
传给待运行进程的命令行。
若 arg 是输入文件,必须改用 addFileInput 或相关
函数,以确保缓存行为正确。
若 arg 是输出文件,必须改用 addOutputFileArg 或相关
函数,以确保缓存行为正确。
pub fn addArg(run: *Run, arg: []const u8) void
参数
run: *Run
arg: []const u8
std.Build.Step.Run.addArgs
函数
将 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
函数
已弃用,请使用 addArtifactArg2。
pub fn addArtifactArg(run: *Run, artifact: *Step.Compile) void
参数
std.Build.Step.Run.addArtifactArg2
函数
pub fn addArtifactArg2(run: *Run, artifact: *Step.Compile, options: PathArgOptions) void
参数
std.Build.Step.Run.addCheck
函数
pub fn addCheck(run: *Run, new_check: StdIo.Check) void
参数
std.Build.Step.Run.addDecoratedDirectoryArg
函数
已弃用,请使用 addDirectoryArg2。
pub fn addDecoratedDirectoryArg( run: *Run, prefix: []const u8, lazy_directory: std.Build.LazyPath, suffix: []const u8, ) void
参数
std.Build.Step.Run.addDepFileOutputArg
函数
已弃用,请使用 addDepFileOutputArg2。
pub fn addDepFileOutputArg(run: *Run, basename: []const u8) std.Build.LazyPath
参数
run: *Run
basename: []const u8
std.Build.Step.Run.addDepFileOutputArg2
函数
添加指向依赖文件(.d)的路径参数,让子进程将 发现的额外依赖写入其中。 每个实例仅允许一个依赖文件参数。
pub fn addDepFileOutputArg2(run: *Run, basename: []const u8, options: PathArgOptions) std.Build.LazyPath
参数
std.Build.Step.Run.addDirectoryArg
函数
已弃用,请使用 addDirectoryArg2。
pub fn addDirectoryArg(run: *Run, lazy_directory: std.Build.LazyPath) void
参数
std.Build.Step.Run.addDirectoryArg2
函数
pub fn addDirectoryArg2( run: *Run, lazy_directory: std.Build.LazyPath, options: PathArgOptions, ) void
参数
std.Build.Step.Run.addFileArg
函数
参见 addFileArg2。
pub fn addFileArg(run: *Run, lp: std.Build.LazyPath) void
参数
std.Build.Step.Run.addFileArg2
函数
将输入文件添加指定字符串前缀后,追加为命令行参数。
例如,前缀 "-F" 会使子进程看到 类似 "-Fexample.txt" 的参数。
即使前缀包含空格, 子进程也只会看到一个参数。后续构建 会将文件修改检测为缓存未命中,从而重新执行子进程。
相关函数:
addOutputFileArg:用于子进程生成的文件。
pub fn addFileArg2(run: *Run, lp: std.Build.LazyPath, options: PathArgOptions) void
参数
std.Build.Step.Run.addFileContentArg
函数
已弃用,使用 addFileContentArg2。
pub fn addFileContentArg(run: *Run, lp: std.Build.LazyPath) void
参数
std.Build.Step.Run.addFileContentArg2
函数
将输入文件的内容添加指定字符串前缀后,追加为命令行参数。
例如,前缀 "-F" 会使子进程看到 类似 "-Fmy file content" 的内容。
即使前缀或文件内容包含空白字符, 子进程也只会看到一个参数。 也就是说,直至 EOF 的全部文件内容均呈现为一个连续 字符串,包括转义序列。尤其是任何末尾换行 都会以如下形式出现:"hello,\nfile world!\n"。
后续构建会将源文件的修改检测为缓存未命中, 从而重新执行子进程。
此函数不能用于提供 Run 步骤的第一个参数。
相关函数:
addFileContentArg:相同功能,但不添加前缀。
pub fn addFileContentArg2(run: *Run, lp: std.Build.LazyPath, options: ArgOptions) void
参数
std.Build.Step.Run.addFileInput
函数
添加一个额外的输入文件;当其被修改时,表示此 Run 步骤应重新执行。 若判定 Run 步骤具有副作用,则无论 此文件是否修改,只要该步骤出现在构建图中, 就始终执行。
pub fn addFileInput(run: *Run, file_input: std.Build.LazyPath) void
参数
std.Build.Step.Run.addOutputDirectoryArg
函数
已弃用,使用 addOutputDirectoryArg2。
pub fn addOutputDirectoryArg(run: *Run, basename: []const u8) std.Build.LazyPath
参数
run: *Run
basename: []const u8
std.Build.Step.Run.addOutputDirectoryArg2
函数
将目录路径作为命令行参数提供给正在运行的命令。
断言 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
参数
std.Build.Step.Run.addOutputFileArg
函数
已弃用,请使用 addOutputFileArg2。
pub fn addOutputFileArg(run: *Run, sub_path: []const u8) std.Build.LazyPath
参数
run: *Run
sub_path: []const u8
std.Build.Step.Run.addOutputFileArg2
函数
将文件路径作为命令行参数传给要运行的命令。
例如,前缀为 "-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
参数
std.Build.Step.Run.addPassthruArgs
函数
将传给 zig build 的额外参数,追加到将传给所运行进程的命令行。
这会使该步骤被视为具有副作用,从而禁用缓存。
例如,命令 zig build run -- arg1 arg2 中的“arg1”和“arg2”将传给所运行进程。
pub fn addPassthruArgs(run: *Run) void
参数
run: *Run
std.Build.Step.Run.addPrefixedArtifactArg
函数
已弃用,请使用 addArtifactArg2。
pub fn addPrefixedArtifactArg(run: *Run, prefix: []const u8, artifact: *Step.Compile) void
参数
std.Build.Step.Run.addPrefixedDepFileOutputArg
函数
已弃用,请使用 addDepFileOutputArg2。
pub fn addPrefixedDepFileOutputArg(run: *Run, prefix: []const u8, basename: []const u8) std.Build.LazyPath
参数
std.Build.Step.Run.addPrefixedDirectoryArg
函数
已弃用,请使用 addDirectoryArg2。
pub fn addPrefixedDirectoryArg(run: *Run, prefix: []const u8, lazy_directory: std.Build.LazyPath) void
参数
std.Build.Step.Run.addPrefixedFileArg
函数
参见 addFileArg2。
pub fn addPrefixedFileArg(run: *Run, prefix: []const u8, lp: std.Build.LazyPath) void
参数
std.Build.Step.Run.addPrefixedFileContentArg
函数
已弃用,使用 addFileContentArg2。
pub fn addPrefixedFileContentArg(run: *Run, prefix: []const u8, lp: std.Build.LazyPath) void
参数
std.Build.Step.Run.addPrefixedOutputDirectoryArg
函数
已弃用,使用 addOutputDirectoryArg2。
pub fn addPrefixedOutputDirectoryArg( run: *Run, prefix: []const u8, basename: []const u8, ) std.Build.LazyPath
参数
std.Build.Step.Run.addPrefixedOutputFileArg
函数
已弃用,请使用 addOutputFileArg2。
pub fn addPrefixedOutputFileArg( run: *Run, prefix: []const u8, sub_path: []const u8, ) std.Build.LazyPath
参数
std.Build.Step.Run.addThirdPartyEnabledArgDarling
函数
根据传给 zig build 的 -fdarling
值,在命令行中追加自定义字符串。
pub fn addThirdPartyEnabledArgDarling(run: *Run, toggle_flags: ToggleFlags) void
参数
run: *Run
toggle_flags: ToggleFlags
std.Build.Step.Run.addThirdPartyEnabledArgQemu
函数
根据传给 zig build 的 -fqemu 值,
向命令行追加自定义字符串。
pub fn addThirdPartyEnabledArgQemu(run: *Run, toggle_flags: ToggleFlags) void
参数
run: *Run
toggle_flags: ToggleFlags
std.Build.Step.Run.addThirdPartyEnabledArgRosetta
函数
根据传给 zig build 的 -frosetta 值,
向命令行追加自定义字符串。
pub fn addThirdPartyEnabledArgRosetta(run: *Run, toggle_flags: ToggleFlags) void
参数
run: *Run
toggle_flags: ToggleFlags
std.Build.Step.Run.addThirdPartyEnabledArgWasmtime
函数
根据传给 zig build 的 -fwasmtime 值,
向命令行追加自定义字符串。
pub fn addThirdPartyEnabledArgWasmtime(run: *Run, toggle_flags: ToggleFlags) void
参数
run: *Run
toggle_flags: ToggleFlags
std.Build.Step.Run.addThirdPartyEnabledArgWine
函数
根据传给 zig build 的 -fwine
值,在命令行中追加自定义字符串。
pub fn addThirdPartyEnabledArgWine(run: *Run, toggle_flags: ToggleFlags) void
参数
run: *Run
toggle_flags: ToggleFlags
std.Build.Step.Run.Arg
容器
字段
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
容器
字段
prefix: []const u8 = ""
suffix: []const u8 = ""
std.Build.Step.Run.assert
别名
别名目标 std.debug.assert
std.Build.Step.Run.base_tag
常量
Step.Tag
std.Build.Step.Run.Build
别名
别名目标 std.Build
std.Build.Step.Run.builtin
常量
std.Build.Step.Run.CapturedStdIo
容器
字段
generated_file: Configuration.GeneratedFileIndex
prefix: []const u8
basename: []const u8
trim_whitespace: TrimWhitespace
std.Build.Step.Run.CapturedStdIo.Options
容器
字段
std.Build.Step.Run.CapturedStdIo.TrimWhitespace
别名
std.Build.Step.Run.captureStdErr
函数
pub fn captureStdErr(run: *Run, options: CapturedStdIo.Options) std.Build.LazyPath
参数
run: *Run
options: CapturedStdIo.Options
std.Build.Step.Run.captureStdOut
函数
pub fn captureStdOut(run: *Run, options: CapturedStdIo.Options) std.Build.LazyPath
参数
run: *Run
options: CapturedStdIo.Options
std.Build.Step.Run.clearEnvironment
函数
pub fn clearEnvironment(run: *Run) void
参数
run: *Run
std.Build.Step.Run.Color
别名
std.Build.Step.Run.Configuration
别名
std.Build.Step.Run.create
函数
pub fn create(owner: *std.Build, name: []const u8) *Run
参数
std.Build.Step.Run.DecoratedArtifact
容器
字段
std.Build.Step.Run.DecoratedFileContent
容器
字段
std.Build.Step.Run.DecoratedLazyPath
容器
字段
std.Build.Step.Run.Dir
别名
别名目标 std.Io.Dir
std.Build.Step.Run.enableProtocolMode
函数
pub fn enableProtocolMode(run: *Run) void
参数
run: *Run
std.Build.Step.Run.enableTestRunnerMode
函数
已弃用,请使用 enableProtocolMode。
pub fn enableTestRunnerMode(run: *Run) void
参数
run: *Run
std.Build.Step.Run.EnvMap
别名
std.Build.Step.Run.expectExitCode
函数
pub fn expectExitCode(run: *Run, code: u8) void
参数
run: *Run
code: u8
std.Build.Step.Run.expectStdErrEqual
函数
添加标准错误精确匹配检查。不添加任何其他检查。
pub fn expectStdErrEqual(run: *Run, bytes: []const u8) void
参数
run: *Run
bytes: []const u8
std.Build.Step.Run.expectStdErrMatch
函数
pub fn expectStdErrMatch(run: *Run, bytes: []const u8) void
参数
run: *Run
bytes: []const u8
std.Build.Step.Run.expectStdOutEqual
函数
添加 stdout 精确匹配检查;若尚无预期终止检查,则还添加退出码为 0 的检查。
pub fn expectStdOutEqual(run: *Run, bytes: []const u8) void
参数
run: *Run
bytes: []const u8
std.Build.Step.Run.expectStdOutMatch
函数
若尚未设置预期终止检查,则添加标准输出匹配检查, 以及退出码为 0 的检查。
pub fn expectStdOutMatch(run: *Run, bytes: []const u8) void
参数
run: *Run
bytes: []const u8
std.Build.Step.Run.getEnvMap
函数
pub fn getEnvMap(run: *Run) *EnvMap
参数
run: *Run
std.Build.Step.Run.getEnvMapInternal
函数
fn getEnvMapInternal(run: *Run) *EnvMap
参数
run: *Run
std.Build.Step.Run.hasTermCheck
函数
pub fn hasTermCheck(run: Run) bool
参数
run: Run
std.Build.Step.Run.Io
别名
别名目标 std.Io
std.Build.Step.Run.mem
别名
别名目标 std.mem
std.Build.Step.Run.Output
容器
字段
generated_file: Configuration.GeneratedFileIndex
prefix: []const u8
basename: []const u8
suffix: []const u8
make_absolute: bool
std.Build.Step.Run.Path
别名
别名目标 std.Build.Cache.Path
std.Build.Step.Run.PathArgOptions
容器
字段
prefix: []const u8 = ""
suffix: []const u8 = ""
make_absolute: bool = false传给子进程前,将路径转换为绝对路径。并非所有宿主均支持, 应尽可能优先接受相对路径。
std.Build.Step.Run.process
别名
别名目标 std.process
std.Build.Step.Run.removeEnvironmentVariable
函数
pub fn removeEnvironmentVariable(run: *Run, key: []const u8) void
参数
run: *Run
key: []const u8
std.Build.Step.Run.Run
别名
别名目标 std.Build.Step.Run
std.Build.Step.Run.setCwd
函数
pub fn setCwd(run: *Run, cwd: Build.LazyPath) void
参数
std.Build.Step.Run.setEnvironmentVariable
函数
pub fn setEnvironmentVariable(run: *Run, key: []const u8, value: []const u8) void
参数
std.Build.Step.Run.setName
函数
pub fn setName(run: *Run, name: []const u8) void
参数
run: *Run
name: []const u8
std.Build.Step.Run.setPreopen
函数
pub fn setPreopen(run: *Run, name: []const u8, resource: Build.LazyPath) void
参数
std.Build.Step.Run.setStdIn
函数
pub fn setStdIn(run: *Run, stdin: StdIn) void
参数
std.Build.Step.Run.std
别名
别名目标 std
std.Build.Step.Run.StdIn
容器
字段
std.Build.Step.Run.StdIo
容器
字段
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
容器
字段
std.Build.Step.Run.Step
别名
别名目标 std.Build.Step
std.Build.Step.Run.ToggleFlags
容器
字段
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");
}