Skip to main content

cmd_args

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.

def cmd_args(
*args: CellPath | artifact | cell_root | cmd_args | label | output_artifact | project_root | resolved_macro | str | tagged_command_line | target_label | transitive_set_args_projection | write_json_cli_args | list | RunInfo,
hidden: CellPath | artifact | cell_root | cmd_args | label | output_artifact | project_root | resolved_macro | str | tagged_command_line | target_label | transitive_set_args_projection | write_json_cli_args | list | RunInfo = ...,
delimiter: str = ...,
format: str = ...,
prepend: str = ...,
quote: str = ...,
ignore_artifacts: bool = False,
absolute_prefix: str = ...,
absolute_suffix: str = ...,
parent: int = 0,
relative_to: artifact | cell_root | project_root | (artifact | cell_root | project_root, int) = ...,
replace_regex: list[(buck_regex | str, str)] | (buck_regex | str, str) = ...,
) -> cmd_args

The cmd_args type is created by this function 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.

The arguments are:

  • *args - a list of things to add to the command line, each of which must be coercible to a command line. Further items can be added with cmd.add.
  • format - a string that provides a format to apply to the argument. for example, cmd_args(x, format="--args={}") would prepend --args= before x, or if x was a list, before each element in x.
  • delimiter - added between arguments to join them together. For example, cmd_args(["--args=",x], delimiter="") would produce a single argument to the underlying tool.
  • prepend - added as a separate argument before each argument.
  • quote - indicates whether quoting is to be applied to each argument. The only current valid value is "shell".
  • ignore_artifacts - if True, artifacts paths are used, but artifacts are not pulled.
  • hidden - artifacts not present on the command line, but added as dependencies.
  • absolute_prefix and absolute_suffix - added to the start and end of each artifact.
  • parent - for all the artifacts use their parentth directory (e.g. parent = 1 for the directory the artifact is located, parent = 2 for that directory's parent, etc.).
  • relative_to - make all artifact paths relative to a given location.
  • replace_regex - replaces arguments with a regular expression.

ignore_artifacts

ignore_artifacts=True makes 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.

hidden

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.

absolute_prefix and absolute_suffix

Adds a prefix to the start or end of every artifact.

Prefix is often used if you have a $ROOT variable in a shell script and want to use it to make files absolute.

Suffix is often used in conjunction with absolute_prefix to wrap artifacts in function calls.

cmd_args(script, absolute_prefix = "$ROOT/")
cmd_args(script, absolute_prefix = "call", absolute_suffix = ")")

parent

For all the artifacts 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=1).

relative_to=dir or relative_to=(dir, parent)

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

By default, the paths are relative to the artifacts themselves (equivalent to parent equals to 0). Use parent to make the paths relative to an ancestor directory. For example parent equals to 1 would make all paths relative to the containing dirs of any artifacts in the cmd_args.

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

replace_regex

Replaces all parts matching pattern regular expression (or regular expressions) in each argument with replacement strings.

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.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.relative_to

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

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

By default, the paths are relative to the artifacts themselves (equivalent to parent = 0). Use parent to make the paths relative to an ancestor directory. For example parent = 1 would make all paths relative to the containing dirs of any artifacts in the cmd_args.

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