Rule APIs
When implementing a rule, you are given a value of type context
and are expected to produce providers. This page details those providers and the attributes and APIs that they offer.
Providers
DefaultInfo(default_outputs : ["artifact"], other_outputs : [["artifact", "cmd_args"]] = [], sub_targets : {str.type: ["provider"]} = {})
- the provider that is used for:buck2 build
- builds everything indefault_outputs
andother_outputs
.$(location)
- uses thedefault_outputs
.buck2 build my_target[foo]
- selects thefoo
value fromsub_targets
.- Note: if you use
cmd_args
inother_outputs
, then it will expand to all the inputs referenced by thecmd_args
you provide.
RunInfo(args)
- used forbuck2 run
, whereargs
is anything that can be converted intocmd_args
, including a command line itself.ExternalRunnerTestInfo(...)
- for details, see Test Execution.
Type context
The starting type, usually bound as ctx
.
ctx.attrs
- returns the attributes of the target as a Starlark struct with a field for each attribute, which varies per rule.ctx.actions
- returnsactions
allowing you to define actions.ctx.label
- returns alabel
representing the target.
Type actions
Most output filenames can either be artifacts created with declare_output
or strings that are implicitly converted to output artifacts.
ctx.actions.declare_output([prefix], filename, dir = False)
- returns anartifact
with the namefilename
, which when asked for its name, will returnfilename
(which may include a directory portion).prefix
(optional) - provides a silent part of the filename, which can be used to disambiguate but whose presence will not be visible to anyone using theartifact
. By default, outputs are considered files; passdir = True
to indicate it is a directory.declare_output
- mainly used to produce an unbound artifact for passing toctx.actions.run
.
ctx.actions.write(filename, content, is_executable : bool.type = false, allow_args : bool.type = false)
- returns anartifact
whose contents arecontent
.filename
- can be a string or an existing artifact created withdeclare_output
.is_executable
(optional) - indicates whether the resulting file should be marked with executable permissions.allow_args
(optional) - must be set toTrue
if you want to write parameter arguments to the file (in particular, macros that write to file).- If it is true, the result will be a pair of the
artifact
containingcontent
and a list ofartifact
values that were written by macros, which should be used in hidden fields or similar.
- If it is true, the result will be a pair of the
ctx.actions.write_json(filename, content, with_inputs = False)
- returns anartifact
whose contents arecontent
written as a JSON value.filename
- can be a string, or an existing artifact created withdeclare_output
.content
- must be composed of the basic json types (Boolean, number, string, list/tuple, dictionary) plus artifacts and command lines.- An artifact will be written as a string containing the path.
- A command line will be written as a list of strings, unless
joined=True
is set, in which case it will be a string.
- If you pass
with_inputs = True
, you'll get back acmd_args
that expands to the JSON file but carries all the underlying inputs as dependencies (so you don't have to use, for example,hidden
for them to be added to an action that already receives the JSON file).
ctx.actions.copy_file(dest, src)
- copies the sourceartifact
to the destination (which can be a string representing a filename or an outputartifact
) and returns the outputartifact
. The copy works for files or directories.ctx.actions.symlink_file(dest, src)
- creates a symlink to the sourceartifact
at the destination (which can be a string representing a filename or an outputartifact
) and returns the outputartifact
. The symlink works for files or directories.ctx.actions.symlinked_dir(output, srcs : {str.type: "artifact"})
- returns an artifact that is a directory containing symlinks. Thesrcs
must be a dictionary of path (as string, relative to the result directory) to boundartifact,
which will be laid out in the directory.ctx.actions.copied_dir(output, srcs : {str.type: "artifact"}, copy : bool.type = false)
- returns an artifact which is a directory containing copied files. Thesrcs
must be a dictionary of path (as string, relative to the result directory) to the boundartifact
, which will be laid out in the directory.ctx.actions.download_file(output, url : str.type, sha1: str.type, is_executable : bool.type = false)
- downloads a URL to an output (filename as string or outputartifact
). The file at the URL must have the givensha1
or the command will fail. The optional parameteris_executable
indicates whether the resulting file should be marked with executable permissions.ctx.actions.run(arguments, category : str.type, identifier : str.type = "", env : {str.type: str.type} = {}, local_only : bool.type = false, always_print_stderr : bool.type = false, weight : int.type = 1, metadata_env_var: str.type = None, metadata_path: str.type = None, no_outputs_cleanup: bool.type = false)
- runs a command.arguments
- must be of typecmd_args
, or a type convertible to such (such as a list of strings and artifacts) and must contain at least one.as_output()
artifact.category
andidentifier
- when used together, identify the action in Buck2's event stream, and must be unique for a given target.weight
is used to note how heavy the command is and will typically be set to a higher value to indicate that less such commands should be run in parallel (if running locally).no_outputs_cleanup
- if this flag is set then Buck2 won't clean the outputs of a previous build that might be present on a disk; in which case, command fromarguments
should be responsible for the cleanup (that is useful, for example, when an action is supporting incremental mode and its outputs are based on result from a previous build).metadata_env_var
andmetadata_path
- both should either be set or unset.metadata_path
defines a path relative to the result directory for a file with action metadata, which will be created right before the command will be run.- Metadata contains the path relative to the Buck2 project root and hash digest for every action input (this excludes symlinks as they could be resolved by a user script if needed). The resolved path relative to the Buck2 project for the metadata file will be passed to command from
arguments
, via the environment variable, with its name set bymetadata_env_var
.
- Metadata contains the path relative to the Buck2 project root and hash digest for every action input (this excludes symlinks as they could be resolved by a user script if needed). The resolved path relative to the Buck2 project for the metadata file will be passed to command from
- Both
metadata_env_var
andmetadata_path
are useful when making actions behave in an incremental manner (for details, see Incremental Actions)
ctx.actions.tset(type, value = None, children = None)
- creates a new transitive set (for details, see Transitive Sets).ctx.actions.cas_artifact(output, digest : str.type, use_case: str.type, expires_after_timestamp: int.type, is_executable : bool.type = false)
- downloads a CAS artifact to an output.digest
- must look likeSHA1:SIZE
.use_case
- your RE use case.expires_after_timestamp
- must be a UNIX timestamp. Your digest's TTL must exceed this timestamp. Your build will break once the digest expires, so make sure the expiry is long enough (preferably, in years).is_executable
(optional) - indicates the resulting file should be marked with executable permissions.
Type 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.
cmd_args(*args, format: str.type = "", delimiter: str.type = None, prepend: str.type = None, quote: str.type = None)
- creates and returns acmd_args
type.*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 withcmd.add
.format
(optional) - a string that provides a format to apply to the argument. for example,cmd_args(x, format="--args={}")
would prepend--args=
beforex
, or ifx
was a list, before each element inx
.delimiter
(optional) - added between arguments to join them together. For example,cmd_args(["--args=",x], delimiter="")
would produce a single argument to the underlying tool.prepend
(optional) - added as a separate argument before each argument.quote
(optional) - indicates whether quoting is to be applied to each argument. Note: the only current valid value is"shell"
.
cmd.add(*args)
- a list of arguments to be added to the command line, as percmd_args
.cmd.hidden(*args)
- things to add to the command line which do not show up but are added as dependencies.cmd.ignore_artifacts()
- conceptually the opposite ofhidden()
. It causes none of the arguments of the command line to be added as dependencies.- Use this if you need the path to an artifact but not the artifact itself.
- Note: if you do find yourself needing any of the inputs referenced by this command, you will hit build errors due to missing dependencies.
cmd.relative_to(directory, parent : int.type = 0)
- complex magic. Before using this, please contact Meta's Buck2 team.cmd.absolute_prefix(prefix : str.type)
- adds a prefix to the front of every artifact.cmd.absolute_suffix(suffix : str.type)
- adds a suffix to the end of every artifact.cmd.parent(count : int.type = 1)
- uses the parent of all given artifacts. Often used ascmd_args(artifact, format="-L{}").parent()
.cmd.replace_regex(pattern : str.type, replacement : str.type)
- replaces all parts matchingpattern
regular expression in each argument withreplacement
string. Several replacements can be added by multiplereplace_regex
calls.cmd.copy()
- returns a copy of thecmd_args
such that any modifications to the original or the returned value will not impact each other.cmd.inputs
- returns a list of the artifacts that are inputs to this command line.cmd.outputs
- returns a list of the artifacts that are outputs of this command line.
Type label
A label represents a configured target.
For example, the label fbcode//buck2/hello:world (ovr_config//platform/linux:x86_64-fbcode-46b26edb4b80a905)
has the following attributes:
package
gives backbuck2/hello
name
gives backworld
sub_target
gives backNone
path
gives backfbcode/buck2/hello
cell
gives backfbcode
raw_target()
gives backfbcode//buck2/hello:world
without the configuration
Type artifact
An artifact, which has a location on disk. Some of that location is considered private, and some (the suffix) is available for use.
The examples below assume an artifact such as one created with ctx.actions.declare_output("hello/world.txt")
. It has the following attributes:
basename
gives backworld.txt
extension
gives back.txt
is_source
-True
if the artifact is a source, otherwiseFalse
.owner
gives back alabel
representing the rule that created it (if it is a build output) orNone
(if it is a source).as_output()
gives a value suitable for setting as an output toctx.actions.run
.short_path
gives backhello/world.txt
Projected artifacts
Artifacts can be projected via the project()
method. Projecting an artifact yields a path within it.
For example, if artifact foo
is a directory containing a file bar
, then foo.project("bar")
yields the file bar
.
It is possible for projected artifacts to hide the prefix in order to have the short name of the resulting artifact only contain the projected path, by passing hide_prefix = True
to project()
.