Skip to content
Standard libraryZig 0.17.0Official documentation
Sourcestd/Build/Step/Run.zig

Source line 1

Fields

step: Step
argv: std.ArrayList(Arg)

See also addArg and addArgs to modifying this directly

cwd: ?Build.LazyPath

Use setCwd to set the initial current working directory

environ_map: ?*EnvMap

Override this field to modify the environment, or use setEnvironmentVariable

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

Named files that will be provided to the parent process. See std.process.Preopens.

color: Color = .auto

Controls the NO_COLOR and CLICOLOR_FORCE environment variables.

disable_zig_progress: bool

When true prevents ZIG_PROGRESS environment variable from being passed to the child process, which otherwise would be used for the child to send progress updates to the parent.

stdio: StdIo

Configures whether the Run step is considered to have side-effects, and also whether the Run step will inherit stdio streams, forwarding them to the parent process, in which case will require a global lock to prevent other steps from interfering with stdio while the subprocess associated with this Run step is running. If the Run step is determined to not have side-effects, then execution will be skipped if all output files are up-to-date and input files are unchanged.

stdin: StdIn

This field must be .none if stdio is inherit. It should be only set using setStdIn.

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

Additional input files that, when modified, indicate that the Run step should be re-executed. If the Run step is determined to have side-effects, the Run step is always executed when it appears in the build graph, regardless of whether these files have been modified.

rename_step_with_output_arg: bool

After adding an output argument, this step will by default rename itself for a better display name in the build summary. This can be disabled by setting this to false.

skip_foreign_checks: bool

If this is true, a Run step which is configured to check the output of the executed binary will not fail the build if the binary cannot be executed due to being for a foreign binary to the host system which is running the build graph.

Command-line arguments such as -fqemu and -fwasmtime may affect whether a binary is detected as foreign, as well as system configuration such as Rosetta (macOS) and binfmt_misc (Linux).

If this Run step is considered to have side-effects, then this flag does nothing.

failing_to_execute_foreign_is_an_error: bool

If this is true, failing to execute a foreign binary will be considered an error. However if this is false, the step will be skipped on failure instead.

This allows for a Run step to attempt to execute a foreign binary using an external executor (such as qemu) but not fail if the executor is unavailable.

stdio_limit: std.Io.Limit

If stderr or stdout exceeds this amount, the child process is killed and the step fails.

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

If this Run step was produced by a Compile step, it is tracked here.

std.Build.Step.Run.addArg

function

Source line 567

Appends the contents of arg, verbatim, to the command line that will be passed to the process being run.

If arg is an input file, addFileInput (or related function) must be used instead to ensure correct cache behavior.

If arg is an output file, addOutputFileArg (or related function) must be used instead to ensure correct cache behavior.

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

Parameters

run: *Run
arg: []const u8

std.Build.Step.Run.addArgs

function

Source line 581

Appends each of args, verbatim, to the command line that will be passed to the process being run.

If any element of args is an input file, addFileInput must be used instead to ensure correct cache behavior.

If any element of args is an output file, addOutputFileArg (or related function) must be used instead to ensure correct cache behavior.

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

Parameters

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

std.Build.Step.Run.addArtifactArg

function

Source line 271

Deprecated, use addArtifactArg2.

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

Parameters

run: *Run
artifact: *Step.Compile

std.Build.Step.Run.addArtifactArg2

function

Source line 280

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

Parameters

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

std.Build.Step.Run.addCheck

function

Source line 737

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

Parameters

run: *Run
new_check: StdIo.Check

std.Build.Step.Run.addDecoratedDirectoryArg

function

Source line 502

Deprecated, use addDirectoryArg2.

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

Parameters

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

std.Build.Step.Run.addDepFileOutputArg

function

Source line 528

Deprecated, use addDepFileOutputArg2.

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

Parameters

run: *Run
basename: []const u8

std.Build.Step.Run.addDepFileOutputArg2

function

Source line 540

Add a path argument to a dep file (.d) for the child process to write its discovered additional dependencies. Only one dep file argument is allowed by instance.

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

Parameters

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

std.Build.Step.Run.addDirectoryArg

function

Source line 492

Deprecated, use addDirectoryArg2.

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

Parameters

run: *Run
lazy_directory: std.Build.LazyPath

std.Build.Step.Run.addDirectoryArg2

function

Source line 511

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

Parameters

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

std.Build.Step.Run.addFileArg

function

Source line 355

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

Parameters

run: *Run
lp: std.Build.LazyPath

std.Build.Step.Run.addFileArg2

function

Source line 375

Appends an input file to the command line arguments prepended with a string.

For example, a prefix of "-F" will result in the child process seeing something like this: "-Fexample.txt"

The child process will see a single argument, even if the prefix has spaces. Modifications to this file will be detected as a cache miss in subsequent builds, causing the child process to be re-executed.

Related:

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

Parameters

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

std.Build.Step.Run.addFileContentArg

function

Source line 390

Deprecated, use addFileContentArg2.

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

Parameters

run: *Run
lp: std.Build.LazyPath

std.Build.Step.Run.addFileContentArg2

function

Source line 417

Appends the content of an input file to the command line arguments prepended with a string.

For example, a prefix of "-F" will result in the child process seeing something like this: "-Fmy file content"

The child process will see a single argument, even if the prefix and/or the file contain whitespace. This means that the entire file content up to EOF is rendered as one contiguous string, including escape sequences. Notably, any (trailing) newlines will show up like this: "hello,\nfile world!\n"

Modifications to the source file will be detected as a cache miss in subsequent builds, causing the child process to be re-executed.

This function may not be used to supply the first argument of a Run step.

Related:

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

Parameters

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

std.Build.Step.Run.addFileInput

function

Source line 808

Adds an additional input files that, when modified, indicates that this Run step should be re-executed. If the Run step is determined to have side-effects, the Run step is always executed when it appears in the build graph, regardless of whether this file has been modified.

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

Parameters

run: *Run
file_input: std.Build.LazyPath

std.Build.Step.Run.addOutputDirectoryArg

function

Source line 438

Deprecated, use addOutputDirectoryArg2.

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

Parameters

run: *Run
basename: []const u8

std.Build.Step.Run.addOutputDirectoryArg2

function

Source line 465

Provides a directory path as a command line argument to the command being run. Asserts basename is not empty.

For example, a prefix of "-o" and basename of "output_dir" will result in the child process seeing something like this: "-ozig-cache/.../output_dir"

The child process will see a single argument, regardless of whether the prefix or basename have spaces.

The returned std.Build.LazyPath can be used as inputs to other APIs throughout the build system.

Related:

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

Parameters

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

std.Build.Step.Run.addOutputFileArg

function

Source line 297

Deprecated, use addOutputFileArg2.

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

Parameters

run: *Run
sub_path: []const u8

std.Build.Step.Run.addOutputFileArg2

function

Source line 323

Provides a file path as a command line argument to the command being run.

For example, a prefix of "-o" and sub_path of "output.txt" will result in the child process seeing something like this: "-ozig-cache/.../output.txt"

The child process will see a single argument, regardless of whether the prefix or sub_path have spaces.

The returned std.Build.LazyPath can be used as inputs to other APIs throughout the build system.

Related:

  • addFileArg - for input files given to the child process
pub fn addOutputFileArg2( run: *Run, sub_path: []const u8, options: PathArgOptions, ) std.Build.LazyPath

Parameters

run: *Run
sub_path: []const u8

The name of the generated output file which may have zero or more path components.

Asserted to be non-empty.

options: PathArgOptions

std.Build.Step.Run.addPassthruArgs

function

Source line 593

Appends the extra arguments provided to zig build to the command line that will be passed to the process being run.

This causes the step to be considered to have side effects, disabling caching.

In the example command zig build run -- arg1 arg2, "arg1" and "arg2" will be passed to the process being run.

pub fn addPassthruArgs(run: *Run) void

Parameters

run: *Run

std.Build.Step.Run.addPrefixedArtifactArg

function

Source line 276

Deprecated, use addArtifactArg2.

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

Parameters

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

std.Build.Step.Run.addPrefixedDepFileOutputArg

function

Source line 533

Deprecated, use addDepFileOutputArg2.

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

Parameters

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

std.Build.Step.Run.addPrefixedDirectoryArg

function

Source line 497

Deprecated, use addDirectoryArg2.

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

Parameters

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

std.Build.Step.Run.addPrefixedFileArg

function

Source line 360

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

Parameters

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

std.Build.Step.Run.addPrefixedFileContentArg

function

Source line 395

Deprecated, use addFileContentArg2.

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

Parameters

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

std.Build.Step.Run.addPrefixedOutputDirectoryArg

function

Source line 443

Deprecated, use addOutputDirectoryArg2.

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

Parameters

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

std.Build.Step.Run.addPrefixedOutputFileArg

function

Source line 302

Deprecated, use addOutputFileArg2.

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

Parameters

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

std.Build.Step.Run.addThirdPartyEnabledArgDarling

function

Source line 601

Appends a custom string to the command line depending on the -fdarling value passed to zig build.

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

Parameters

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.addThirdPartyEnabledArgQemu

function

Source line 609

Appends a custom string to the command line depending on the -fqemu value passed to zig build.

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

Parameters

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.addThirdPartyEnabledArgRosetta

function

Source line 617

Appends a custom string to the command line depending on the -frosetta value passed to zig build.

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

Parameters

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.addThirdPartyEnabledArgWasmtime

function

Source line 625

Appends a custom string to the command line depending on the -fwasmtime value passed to zig build.

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

Parameters

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.addThirdPartyEnabledArgWine

function

Source line 633

Appends a custom string to the command line depending on the -fwine value passed to zig build.

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

Parameters

run: *Run
toggle_flags: ToggleFlags

std.Build.Step.Run.Arg

container

Source line 145

Fields

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

The arguments passed after "--" on the "zig build" CLI.

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

std.Build.Step.Run.ArgOptions

container

Source line 257

Fields

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

std.Build.Step.Run.assert

alias

Source line 12

Alias of std.debug.assert

std.Build.Step.Run.base_tag

constant

Source line 16

Step.Tag

std.Build.Step.Run.Build

alias

Source line 6

Alias of std.Build

std.Build.Step.Run.builtin

constant

Source line 2

std.Build.Step.Run.CapturedStdIo

container

Source line 199

Fields

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

std.Build.Step.Run.CapturedStdIo.Options

container

Source line 205

Fields

basename: ?[]const u8 = null

null means stdout/stderr.

trim_whitespace: TrimWhitespace = .none

std.Build.Step.Run.CapturedStdIo.TrimWhitespace

alias

Source line 212

Alias of std.Build.Configuration.Step.Run.TrimWhitespace

std.Build.Step.Run.captureStdErr

function

Source line 757

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

Parameters

run: *Run
options: CapturedStdIo.Options

std.Build.Step.Run.captureStdOut

function

Source line 780

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

Parameters

run: *Run
options: CapturedStdIo.Options

std.Build.Step.Run.clearEnvironment

function

Source line 653

pub fn clearEnvironment(run: *Run) void

Parameters

run: *Run

std.Build.Step.Run.Color

alias

Source line 99

Alias of std.Build.Configuration.Step.Run.Color

std.Build.Step.Run.Configuration

alias

Source line 14

Alias of std.Build.Configuration

std.Build.Step.Run.create

function

Source line 215

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

Parameters

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

std.Build.Step.Run.DecoratedArtifact

container

Source line 171

Fields

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

std.Build.Step.Run.DecoratedFileContent

container

Source line 185

Fields

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

std.Build.Step.Run.DecoratedLazyPath

container

Source line 178

Fields

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

std.Build.Step.Run.Dir

alias

Source line 8

Alias of std.Io.Dir

std.Build.Step.Run.enableProtocolMode

function

Source line 253

pub fn enableProtocolMode(run: *Run) void

Parameters

run: *Run

std.Build.Step.Run.enableTestRunnerMode

function

Source line 249

Deprecated, use enableProtocolMode.

pub fn enableTestRunnerMode(run: *Run) void

Parameters

run: *Run

std.Build.Step.Run.EnvMap

alias

Source line 11

Alias of std.process.Environ.Map

std.Build.Step.Run.expectExitCode

function

Source line 724

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

Parameters

run: *Run
code: u8

std.Build.Step.Run.expectStdErrEqual

function

Source line 698

Adds a check for exact stderr match. Does not add any other checks.

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

Parameters

run: *Run
bytes: []const u8

std.Build.Step.Run.expectStdErrMatch

function

Source line 703

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

Parameters

run: *Run
bytes: []const u8

std.Build.Step.Run.expectStdOutEqual

function

Source line 710

Adds a check for exact stdout match as well as a check for exit code 0, if there is not already an expected termination check.

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

Parameters

run: *Run
bytes: []const u8

std.Build.Step.Run.expectStdOutMatch

function

Source line 718

Adds a check for stdout match as well as a check for exit code 0, if there is not already an expected termination check.

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

Parameters

run: *Run
bytes: []const u8

std.Build.Step.Run.getEnvMap

function

Source line 660

pub fn getEnvMap(run: *Run) *EnvMap

Parameters

run: *Run

std.Build.Step.Run.getEnvMapInternal

function

Source line 664

fn getEnvMapInternal(run: *Run) *EnvMap

Parameters

run: *Run

std.Build.Step.Run.hasTermCheck

function

Source line 729

pub fn hasTermCheck(run: Run) bool

Parameters

run: Run

std.Build.Step.Run.Io

alias

Source line 5

Alias of std.Io

std.Build.Step.Run.mem

alias

Source line 9

Alias of std.mem

std.Build.Step.Run.Output

container

Source line 191

Fields

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

std.Build.Step.Run.Path

alias

Source line 13

Alias of std.Build.Cache.Path

std.Build.Step.Run.PathArgOptions

container

Source line 262

Fields

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

Makes the path absolute before passing it to the child process. Not supported by all hosts, prefer accepting relative paths when possible.

std.Build.Step.Run.process

alias

Source line 10

Alias of std.process

std.Build.Step.Run.removeEnvironmentVariable

function

Source line 681

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

Parameters

run: *Run
key: []const u8

std.Build.Step.Run.Run

alias

Source line 1

Alias of std.Build.Step.Run

std.Build.Step.Run.setCwd

function

Source line 647

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

Parameters

run: *Run
cwd: Build.LazyPath

std.Build.Step.Run.setEnvironmentVariable

function

Source line 675

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

Parameters

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

std.Build.Step.Run.setName

function

Source line 243

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

Parameters

run: *Run
name: []const u8

std.Build.Step.Run.setPreopen

function

Source line 685

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

Parameters

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

std.Build.Step.Run.setStdIn

function

Source line 639

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

Parameters

run: *Run
stdin: StdIn

std.Build.Step.Run.std

alias

Source line 4

Alias of std

std.Build.Step.Run.StdIn

container

Source line 101

Fields

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

std.Build.Step.Run.StdIo

container

Source line 107

Fields

infer_from_args

Whether the Run step has side-effects will be determined by whether or not one of the args is an output file (added with addOutputFileArg). If the Run step is determined to have side-effects, this is the same as inherit. The step will fail if the subprocess crashes or returns a non-zero exit code.

inherit

Causes the Run step to be considered to have side-effects, and therefore always execute when it appears in the build graph. It also means that this step will obtain a global lock to prevent other steps from running in the meantime. The step will fail if the subprocess crashes or returns a non-zero exit code.

check: std.ArrayList(Check)

Causes the Run step to be considered to not have side-effects. The process will be re-executed if any of the input dependencies are modified. The exit code and standard I/O streams will be checked for certain conditions, and the step will succeed or fail based on these conditions. Note that an explicit check for exit code 0 needs to be added to this list if such a check is desirable.

zig_test

This Run step is running a zig unit test binary and will communicate extra metadata over the IPC protocol. Deprecated, use .protocol.

protocol

This Run step is running a binary that will communicate over the IPC protocol.

std.Build.Step.Run.StdIo.Check

container

Source line 134

Fields

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

alias

Source line 7

Alias of std.Build.Step

std.Build.Step.Run.ToggleFlags

container

Source line 164

Fields

enabled: ?[]const u8 = null

The string to pass when enabled, or null to omit the arg.

disabled: ?[]const u8 = null

The string to pass when disabled, or null to omit the arg.

Source code

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,

/// See also addArg and addArgs to modifying this directly
argv: std.ArrayList(Arg),

/// Use `setCwd` to set the initial current working directory
cwd: ?Build.LazyPath,

/// Override this field to modify the environment, or use setEnvironmentVariable
environ_map: ?*EnvMap,

/// Named files that will be provided to the parent process.
/// See `std.process.Preopens`.
preopens: std.array_hash_map.Auto(Configuration.String, Build.LazyPath),

/// Controls the `NO_COLOR` and `CLICOLOR_FORCE` environment variables.
color: Color = .auto,

/// When `true` prevents `ZIG_PROGRESS` environment variable from being passed
/// to the child process, which otherwise would be used for the child to send
/// progress updates to the parent.
disable_zig_progress: bool,

/// Configures whether the Run step is considered to have side-effects, and also
/// whether the Run step will inherit stdio streams, forwarding them to the
/// parent process, in which case will require a global lock to prevent other
/// steps from interfering with stdio while the subprocess associated with this
/// Run step is running.
/// If the Run step is determined to not have side-effects, then execution will
/// be skipped if all output files are up-to-date and input files are
/// unchanged.
stdio: StdIo,

/// This field must be `.none` if stdio is `inherit`.
/// It should be only set using `setStdIn`.
stdin: StdIn,

/// Additional input files that, when modified, indicate that the Run step
/// should be re-executed.
/// If the Run step is determined to have side-effects, the Run step is always
/// executed when it appears in the build graph, regardless of whether these
/// files have been modified.
file_inputs: std.ArrayList(std.Build.LazyPath),

/// After adding an output argument, this step will by default rename itself
/// for a better display name in the build summary.
/// This can be disabled by setting this to false.
rename_step_with_output_arg: bool,

/// If this is true, a Run step which is configured to check the output of the
/// executed binary will not fail the build if the binary cannot be executed
/// due to being for a foreign binary to the host system which is running the
/// build graph.
///
/// Command-line arguments such as -fqemu and -fwasmtime may affect whether a
/// binary is detected as foreign, as well as system configuration such as
/// Rosetta (macOS) and binfmt_misc (Linux).
///
/// If this Run step is considered to have side-effects, then this flag does
/// nothing.
skip_foreign_checks: bool,

/// If this is true, failing to execute a foreign binary will be considered an
/// error. However if this is false, the step will be skipped on failure instead.
///
/// This allows for a Run step to attempt to execute a foreign binary using an
/// external executor (such as qemu) but not fail if the executor is unavailable.
failing_to_execute_foreign_is_an_error: bool,

/// If stderr or stdout exceeds this amount, the child process is killed and
/// the step fails.
stdio_limit: std.Io.Limit,

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

has_side_effects: bool,

/// If this Run step was produced by a Compile step, it is tracked here.
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) {
    /// Whether the Run step has side-effects will be determined by whether or not one
    /// of the args is an output file (added with `addOutputFileArg`).
    /// If the Run step is determined to have side-effects, this is the same as `inherit`.
    /// The step will fail if the subprocess crashes or returns a non-zero exit code.
    infer_from_args,
    /// Causes the Run step to be considered to have side-effects, and therefore
    /// always execute when it appears in the build graph.
    /// It also means that this step will obtain a global lock to prevent other
    /// steps from running in the meantime.
    /// The step will fail if the subprocess crashes or returns a non-zero exit code.
    inherit,
    /// Causes the Run step to be considered to *not* have side-effects. The
    /// process will be re-executed if any of the input dependencies are
    /// modified. The exit code and standard I/O streams will be checked for
    /// certain conditions, and the step will succeed or fail based on these
    /// conditions.
    /// Note that an explicit check for exit code 0 needs to be added to this
    /// list if such a check is desirable.
    check: std.ArrayList(Check),
    /// This Run step is running a zig unit test binary and will communicate
    /// extra metadata over the IPC protocol.
    /// Deprecated, use `.protocol`.
    zig_test,
    /// This Run step is running a binary that will communicate over the IPC protocol.
    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,
    /// The arguments passed after "--" on the "zig build" CLI.
    passthru,

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

pub const ToggleFlags = struct {
    /// The string to pass when enabled, or null to omit the arg.
    enabled: ?[]const u8 = null,
    /// The string to pass when disabled, or null to omit the arg.
    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` means `stdout`/`stderr`.
        basename: ?[]const u8 = null,
        /// Does not affect `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;
}

/// Deprecated, use `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 = "",
    /// Makes the path absolute before passing it to the child process. Not supported by all hosts,
    /// prefer accepting relative paths when possible.
    make_absolute: bool = false,
};

/// Deprecated, use `addArtifactArg2`.
pub fn addArtifactArg(run: *Run, artifact: *Step.Compile) void {
    run.addArtifactArg2(artifact, .{});
}

/// Deprecated, use `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);
}

/// Deprecated, use `addOutputFileArg2`.
pub fn addOutputFileArg(run: *Run, sub_path: []const u8) std.Build.LazyPath {
    return run.addOutputFileArg2(sub_path, .{});
}

/// Deprecated, use `addOutputFileArg2`.
pub fn addPrefixedOutputFileArg(
    run: *Run,
    prefix: []const u8,
    sub_path: []const u8,
) std.Build.LazyPath {
    return run.addOutputFileArg2(sub_path, .{ .prefix = prefix });
}

/// Provides a file path as a command line argument to the command being run.
///
/// For example, a prefix of "-o" and `sub_path` of "output.txt" will result in
/// the child process seeing something like this: "-ozig-cache/.../output.txt"
///
/// The child process will see a single argument, regardless of whether the
/// prefix or `sub_path` have spaces.
///
/// The returned `std.Build.LazyPath` can be used as inputs to other APIs
/// throughout the build system.
///
/// Related:
/// * `addFileArg` - for input files given to the child process
pub fn addOutputFileArg2(
    run: *Run,
    /// The name of the generated output file which may have zero or more path
    /// components.
    ///
    /// Asserted to be non-empty.
    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 } };
}

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

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

/// Appends an input file to the command line arguments prepended with a string.
///
/// For example, a prefix of "-F" will result in the child process seeing something
/// like this: "-Fexample.txt"
///
/// The child process will see a single argument, even if the prefix has
/// spaces. Modifications to this file will be detected as a cache miss in
/// subsequent builds, causing the child process to be re-executed.
///
/// Related:
/// * `addOutputFileArg` - for files generated by the child process
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);
}

/// Deprecated, use `addFileContentArg2`.
pub fn addFileContentArg(run: *Run, lp: std.Build.LazyPath) void {
    return run.addFileContentArg2(lp, .{});
}

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

/// Appends the content of an input file to the command line arguments prepended with a string.
///
/// For example, a prefix of "-F" will result in the child process seeing something
/// like this: "-Fmy file content"
///
/// The child process will see a single argument, even if the prefix and/or the file
/// contain whitespace.
/// This means that the entire file content up to EOF is rendered as one contiguous
/// string, including escape sequences. Notably, any (trailing) newlines will show up
/// like this: "hello,\nfile world!\n"
///
/// Modifications to the source file will be detected as a cache miss in subsequent
/// builds, causing the child process to be re-executed.
///
/// This function may not be used to supply the first argument of a `Run` step.
///
/// Related:
/// * `addFileContentArg` - same thing but without the prefix
pub fn addFileContentArg2(run: *Run, lp: std.Build.LazyPath, options: ArgOptions) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;

    // Some parts of this step's configure phase API rely on the first argument being somewhat
    // transparent/readable, but the content of the file specified by `lp` remains completely
    // opaque until its path can be resolved during the make phase.
    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);
}

/// Deprecated, use `addOutputDirectoryArg2`.
pub fn addOutputDirectoryArg(run: *Run, basename: []const u8) std.Build.LazyPath {
    return run.addOutputDirectoryArg2(basename, .{});
}

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

/// Provides a directory path as a command line argument to the command being run.
/// Asserts `basename` is not empty.
///
/// For example, a prefix of "-o" and basename of "output_dir" will result in
/// the child process seeing something like this: "-ozig-cache/.../output_dir"
///
/// The child process will see a single argument, regardless of whether the
/// prefix or basename have spaces.
///
/// The returned `std.Build.LazyPath` can be used as inputs to other APIs
/// throughout the build system.
///
/// Related:
/// * `addDirectoryArg` - for input directories given to the child process
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 } };
}

/// Deprecated, use `addDirectoryArg2`.
pub fn addDirectoryArg(run: *Run, lazy_directory: std.Build.LazyPath) void {
    run.addDirectoryArg2(lazy_directory, .{});
}

/// Deprecated, use `addDirectoryArg2`.
pub fn addPrefixedDirectoryArg(run: *Run, prefix: []const u8, lazy_directory: std.Build.LazyPath) void {
    run.addDirectoryArg2(lazy_directory, .{ .prefix = prefix });
}

/// Deprecated, use `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);
}

/// Deprecated, use `addDepFileOutputArg2`.
pub fn addDepFileOutputArg(run: *Run, basename: []const u8) std.Build.LazyPath {
    return run.addDepFileOutputArg2(basename, .{});
}

/// Deprecated, use `addDepFileOutputArg2`.
pub fn addPrefixedDepFileOutputArg(run: *Run, prefix: []const u8, basename: []const u8) std.Build.LazyPath {
    return run.addDepFileOutputArg2(basename, .{ .prefix = prefix });
}

/// Add a path argument to a dep file (.d) for the child process to write its
/// discovered additional dependencies.
/// Only one dep file argument is allowed by instance.
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 } };
}

/// Appends the contents of `arg`, verbatim, to the command line that will be
/// passed to the process being run.
///
/// If `arg` is an input file, `addFileInput` (or related function) must be
/// used instead to ensure correct cache behavior.
///
/// If `arg` is an output file, `addOutputFileArg` (or related function) must
/// be used instead to ensure correct cache behavior.
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");
}

/// Appends each of `args`, verbatim, to the command line that will be passed
/// to the process being run.
///
/// If any element of `args` is an input file, `addFileInput` must be used
/// instead to ensure correct cache behavior.
///
/// If any element of `args` is an output file, `addOutputFileArg` (or related
/// function) must be used instead to ensure correct cache behavior.
pub fn addArgs(run: *Run, args: []const []const u8) void {
    for (args) |arg| run.addArg(arg);
}

/// Appends the extra arguments provided to `zig build` to the command line
/// that will be passed to the process being run.
///
/// This causes the step to be considered to have side effects, disabling
/// caching.
///
/// In the example command `zig build run -- arg1 arg2`, "arg1" and "arg2" will
/// be passed to the process being run.
pub fn addPassthruArgs(run: *Run) void {
    const graph = run.step.owner.graph;
    const arena = graph.arena;
    run.argv.append(arena, .passthru) catch @panic("OOM");
}

/// Appends a custom string to the command line depending on the `-fdarling`
/// value passed to `zig build`.
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");
}

/// Appends a custom string to the command line depending on the `-fqemu`
/// value passed to `zig build`.
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");
}

/// Appends a custom string to the command line depending on the `-frosetta`
/// value passed to `zig build`.
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");
}

/// Appends a custom string to the command line depending on the `-fwasmtime`
/// value passed to `zig build`.
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");
}

/// Appends a custom string to the command line depending on the `-fwine`
/// value passed to `zig build`.
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();
    // This data structure already dupes keys and values.
    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");
}

/// Adds a check for exact stderr match. Does not add any other checks.
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) });
}

/// Adds a check for exact stdout match as well as a check for exit code 0, if
/// there is not already an expected termination check.
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);
}

/// Adds a check for stdout match as well as a check for exit code 0, if there
/// is not already an expected termination check.
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 } };
}

/// Adds an additional input files that, when modified, indicates that this Run
/// step should be re-executed.
/// If the Run step is determined to have side-effects, the Run step is always
/// executed when it appears in the build graph, regardless of whether this
/// file has been modified.
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");
}