Skip to main content

cmd_args type

The cmd_args type is created by cmd_args() and is consumed by ctx.actions.run. The type is a mutable collection of strings and artifact values. In general, command lines, artifacts, strings, RunInfo and lists thereof can be added to or used to construct a cmd_args value. All these methods operate mutably on cmd and return that value too.

cmd_args.absolute_prefix​

def cmd_args.absolute_prefix(prefix: str) -> cmd_args

Adds a prefix to the end of start artifact. Often used if you have a $ROOT variable in a shell script and want to use it to make files absolute.

cmd_args(script).absolute_prefix("$ROOT/")

cmd_args.absolute_suffix​

def cmd_args.absolute_suffix(suffix: str) -> cmd_args

Adds a suffix to the end of every artifact. Useful in conjunction with absolute_prefix to wrap artifacts in function calls.

cmd_args(script).absolute_prefix("call(").absolute_suffix(")")

cmd_args.add​

def cmd_args.add(*args) -> cmd_args

A list of arguments to be added to the command line, which may including cmd_args, artifacts, strings, RunInfo or lists thereof. Note that this operation mutates the input cmd_args.

cmd_args.copy​

def cmd_args.copy() -> cmd_args

Returns a copy of the cmd_args such that any modifications to the original or the returned value will not impact each other. Note that this is a shallow copy, so any inner cmd_args can still be modified.

cmd_args.hidden​

def cmd_args.hidden(*args) -> cmd_args

Things to add to the command line which do not show up but are added as dependencies. The values can be anything normally permissible to pass to add.

Typically used if the command you are running implicitly depends on files that are not passed on the command line, e.g. headers in the case of a C compilation.

cmd_args.ignore_artifacts​

def cmd_args.ignore_artifacts() -> cmd_args

Causes this cmd_args to have no declared dependencies. Allows you to reference the path of an artifact without introducing dependencies on it.

As an example where this can be useful, consider passing a dependency that is only accessed at runtime, but whose path must be baked into the binary. As an example:

resources = cmd_args(resource_file, format = "-DFOO={}").ignore_artifacts()
ctx.actions.run(cmd_args("gcc", "-c", source_file, resources))

Note that ignore_artifacts sets all artifacts referenced by this cmd_args to be ignored, including those added afterwards, so generally create a special cmd_args and scope it quite tightly.

If you actually do use the inputs referenced by this command, you will either error out due to missing dependencies (if running actions remotely) or have untracked dependencies that will fail to rebuild when it should.

cmd_args.inputs​

cmd_args.inputs: command_line_inputs

Collect all the inputs (including hidden) referenced by this command line. The output can be compared for equality and have its len requested to see whether there are any inputs, but is otherwise mostly opaque.

cmd_args.outputs​

cmd_args.outputs: list[output_artifact]

Collect all the outputs (including hidden) referenced by this command line.

cmd_args.parent​

def cmd_args.parent(count: int = _, /) -> cmd_args

For all the artifacts listed in this cmd_args, use their parent directory.

Typically used when the file name is passed one way, and the directory another, e.g. cmd_args(artifact, format="-L{}").parent().

cmd_args.relative_to​

def cmd_args.relative_to(
    directory: artifact | cell_root | project_root,
    /,
    *,
    parent: int = 0
) -> cmd_args

Make all artifact paths relative to a given location. Typically used when the command you are running changes directory.

dir = symlinked_dir(...)
script = [
    cmd_args(cmd_args(dir, format = "cd {}"),
    original_script.relative_to(dir)
]

cmd_args.replace_regex​

def cmd_args.replace_regex(
    pattern: buck_regex | str,
    replacement: str,
    /
) -> cmd_args

Replaces all parts matching pattern regular expression in each argument with replacement string. Several replacements can be added by multiple replace_regex calls.