bxl.Context
type
The bxl context that the top level bxl implementation receives as parameter. This context contains all the core bxl functions to query, build, create actions, etc.
bxl.Context.analysis
def bxl.Context.analysis(
labels: bxl.ConfiguredTargetNode | bxl.UnconfiguredTargetNode | configured_target_label | label | providers_label | str | target_label | target_set | target_set | list[bxl.ConfiguredTargetNode | bxl.UnconfiguredTargetNode | configured_target_label | label | providers_label | str | target_label],
target_platform: None | str | target_label = ...,
*,
skip_incompatible: bool = True,
) -> None | bxl.AnalysisResult | dict[label, bxl.AnalysisResult]
Runs analysis on the given labels
, accepting an optional target_platform
which is the target platform configuration used to resolve configurations of any unconfigured target nodes, and an optional skip_incompatible
boolean that indicates whether to skip analysis of nodes that are incompatible with the target platform. The target_platform
is either a string that can be parsed as a target label, or a target label.
The given labels
is a providers expression, which is either:
- a single string that is a `target pattern`.
- a single target node or label, configured or unconfigured
- a single sub target label, configured or unconfigured
- a list of the two options above.
This returns either a single analysis_result
if the given labels
argument is "singular",
or a dict keyed by sub target labels of analysis
if the given labels
argument
is list-like
bxl.Context.aquery
def bxl.Context.aquery(
target_platform: None | str | target_label = ...,
) -> bxl.AqueryContext
Returns the aqueryctx
that holds all the aquery functions. This function takes an optional parameter target_platform
, which is the target platform configuration used to configured any unconfigured target nodes.
The target_platform
is a target label, or a string that is a target label.
bxl.Context.audit
def bxl.Context.audit() -> bxl.AuditContext
Returns the audit_ctx
that holds all the audit functions.
bxl.Context.build
def bxl.Context.build(
labels: bxl.ConfiguredTargetNode | bxl.UnconfiguredTargetNode | configured_target_label | label | providers_label | str | target_label | target_set | target_set | list[bxl.ConfiguredTargetNode | bxl.UnconfiguredTargetNode | configured_target_label | label | providers_label | str | target_label],
target_platform: None | str | target_label = ...,
*,
materializations: str = "default",
) -> dict[label, bxl.BuildResult]
Runs a build on the given labels
, accepting an optional target_platform
which is the target platform configuration used to resolve configurations. Note that when build()
is called, the artifacts are materialized without needing to additionally call ensure()
on them.
The given labels
is a providers expression, which is either:
- a single string that is a `target pattern`.
- a single target node or label, configured or unconfigured
- a single provider label, configured or unconfigured
- a list of the two options above.
This returns a dict keyed by sub target labels mapped to bxl_build_result
s if the
given labels
argument is list-like.
This function is not available on the bxl_ctx
when called from dynamic_output
.
bxl.Context.bxl_actions
def bxl.Context.bxl_actions(
*,
exec_deps: None | bxl.UnconfiguredTargetNode | providers_label | str | target_label | target_set | list[bxl.UnconfiguredTargetNode | providers_label | str | target_label] = None,
toolchains: None | bxl.UnconfiguredTargetNode | providers_label | str | target_label | target_set | list[bxl.UnconfiguredTargetNode | providers_label | str | target_label] = None,
target_platform: None | str | target_label = ...,
exec_compatible_with: None | bxl.UnconfiguredTargetNode | str | target_label | target_set | list[bxl.UnconfiguredTargetNode | str | target_label] = None,
) -> bxl.Actions
Returns the bxl actions to create and register actions for this bxl function. This will have the execution platform resolved according to the execution deps and toolchains you pass into this function. You'll be able to access the analysis action factory of the correct execution platform, toolchains, and execution deps of the corresponding configuration via this context.
Actions created by bxl will not be built by default. Instead, they are marked to be built
by ctx.output.ensure(artifact)
on the output module of the bxl_ctx
. Only artifacts
marked by ensure will be built.
Sample usage:
def _impl_write_action(ctx):
bxl_actions = ctx.bxl_actions()
output = bxl_actions.actions.write("my_output", "my_content")
ensured = ctx.output.ensure(output)
ctx.output.print(ensured)
There are several optional named parameters:
exec_deps
- These are dependencies you wish to access as executables for creating the action.
This is usually the same set of targets one would pass to rule's attr.exec_dep
.
toolchains
- The set of toolchains needed for the actions you intend to create.
target_platform
- The intended target platform for your toolchains
exec_compatible_with
- Explicit list of configuration nodes (like platforms or constraints)
that these actions are compatible with. This is the 'exec_compatible_with' attribute of a target.
If you passed in exec_deps
or toolchains
, you can access the resolved dependencies using the exec_deps
and toolchains
attributes on the bxl_actions
, which both return a dict
of unconfigured subtarget labels
and their configured/resolved dependency
objects.
Note that the keys of exec_deps
and toolchains
must be unconfigured subtarget labels (providers_label
s),
and not unconfigured target labels. You can use ctx.unconfigured_sub_targets(...)
or with_sub_target()
on
target_label
to create the label.
def _impl_run_action(ctx):
my_exec_dep = ctx.unconfigured_sub_targets("foo//bar:baz") # has some provider that you would use in the action
bxl_actions = ctx.bxl_actions(exec_deps = [my_exec_dep]) # call once, reuse wherever needed
output = bxl_actions.actions.run(
[
"python3",
bxl_actions.exec_deps[my_exec_dep][RunInfo], # access resolved exec_deps on the `bxl_actions`
out.as_output(),
],
category = "command",
local_only = True,
)
ctx.output.ensure(output)
When called from a dynamic_output
, bxl_actions()
cannot be configured with a different execution
platform resolution from the parent BXL.
bxl.Context.cell_root
def bxl.Context.cell_root() -> str
Returns the absolute path to the cell of the repository
This function is not available on the bxl_ctx
when called from dynamic_output
.
bxl.Context.cli_args
bxl.Context.cli_args: struct(..)
A struct of the command line args as declared using the [cli_args
] module. These command lines are resolved per the users input on the cli when invoking the bxl script.
If you wish to pass in a kebab-cased arg, the arg accessed from the BXL context's cli_args
attrbute will always be in snakecase. For example, if you passed in my-arg
, accessing it
within BXL would look like ctx.cli_args.my_arg
.
This attribute is not available on the bxl context within the a dynamic lambda.
bxl.Context.configured_targets
def bxl.Context.configured_targets(
labels: bxl.ConfiguredTargetNode | bxl.UnconfiguredTargetNode | configured_target_label | str | target_label | target_set | target_set | list[bxl.ConfiguredTargetNode | bxl.UnconfiguredTargetNode | configured_target_label | str | target_label],
/,
target_platform: None | str | target_label = ...,
*,
modifiers: None | list[str] = None,
) -> None | bxl.ConfiguredTargetNode | target_set
Gets the target nodes for the labels
, accepting an optional target_platform
which is the target platform configuration used to resolve configurations of any unconfigured target nodes. The target_platform
is either a string that can be parsed as a target label, or a target label.
The given labels
is a [TargetListExpr
], which is either:
- a single string that is a `target pattern`.
- a single target node or label, configured or unconfigured
- a list of the two options above.
Note that this function does not accept Label
(which is a configured provider label), since this
is the label of a subtarget. You can get the underlying configured target label on the Label
using configured_targets()
(ex: my_label.configured_target()
).
This returns either a single target_node
if the given labels
is "singular", a dict keyed by target labels of target_node
if the
given labels
is list-like
bxl.Context.cquery
def bxl.Context.cquery(
target_platform: None | str | target_label = ...,
) -> bxl.CqueryContext
Returns the cqueryctx
that holds all the cquery functions. This function takes an optional parameter target_platform
, which is the target platform configuration used to configured any unconfigured target nodes.
The target_platform
is a target label, or a string that is a target label.
bxl.Context.fs
bxl.Context.fs: bxl.Filesystem
Returns the bxl.Filesystem
for performing a basic set of filesystem operations within bxl
bxl.Context.instant_event
def bxl.Context.instant_event(*, id: str, metadata) -> None
Emits a user-defined instant event, taking in a required string id and a metadata dictionary where the keys are strings, and values are either strings, bools, or ints. The id is user-supplied, and used to identify the instant events in the event logs more easily.
You may pass in an ensured artifact as a value in the metadata. The resulting output would be the ensured artifact's relative or absolute path as a string.
bxl.Context.lazy
bxl.Context.lazy: bxl.LazyContext
Lazy/batch/error handling operations.
bxl.Context.output
bxl.Context.output: bxl.OutputStream
Gets the output stream to the console via stdout. Items written to the output stream are considered to be the results of a bxl script, which will be displayed to stdout by buck2 even when the script is cached.
Prints that are not result of the bxl should be printed via stderr via the stdlib print
and pprint
.
This function is not available on the bxl_ctx
when called from dynamic_output
.
bxl.Context.resolve
def bxl.Context.resolve(action_factory: actions, promise: promise)
Awaits a promise and returns an optional value of the promise.
Sample usage:
load("//path/to/rules:rules.bzl", "my_anon_targets_rule", "my_map_function")
def _resolve_impl(ctx):
actions = ctx.bxl_actions().actions
my_attrs = {
"false": False,
"int": 42,
"list_string": ["a", "b", "c"],
"string": "a-string",
"true": True,
}
promise = actions.anon_target(my_anon_targets_rule, attrs).promise.map(my_map_function)
providers_result = ctx.resolve(actions, promise) # result is `provider_collection` type, which is a collection of `provider`s
ctx.output.print(providers_result[0].my_field)
bxl.Context.root
def bxl.Context.root() -> str
Returns the absolute path to the root of the repository
This function is not available on the bxl_ctx
when called from dynamic_output
.
bxl.Context.target_exists
def bxl.Context.target_exists(label: str) -> bool
Checks if a target label exists. Target label must be a string literal, and an exact target.
bxl.Context.target_universe
def bxl.Context.target_universe(
labels: bxl.ConfiguredTargetNode | bxl.UnconfiguredTargetNode | configured_target_label | str | target_label | target_set | target_set | list[bxl.ConfiguredTargetNode | bxl.UnconfiguredTargetNode | configured_target_label | str | target_label],
target_platform: None | str | target_label = ...,
*,
keep_going: bool = False,
) -> bxl.TargetUniverse
Returns the target_universe
that can lookup valid configured nodes in the universe.
The given labels
is a target expression, which is either:
- a single string that is a `target pattern`.
- a single target node or label, configured or unconfigured
- a single subtarget label, configured or unconfigured
- a list of the two options above.
Also takes in an optional target_platform
param to configure the nodes with, and a keep_going``
flag to skip any loading or configuration errors. Note that
keep_going` currently can only be used
if the input labels is a single target pattern as a string literal.
bxl.Context.unconfigured_sub_targets
def bxl.Context.unconfigured_sub_targets(
labels: bxl.UnconfiguredTargetNode | providers_label | str | target_label | target_set | list[bxl.UnconfiguredTargetNode | providers_label | str | target_label],
) -> providers_label | dict[str, providers_label]
Gets the unconfigured subtargets for the given labels
The given labels
is a providers expression, which is either:
- a single string that is a `target pattern`.
- a single target node or label, configured or unconfigured
- a single subtarget label, configured or unconfigured
- a list of the two options above.
This returns either a single providers_label
if the given labels
argument
is "singular", or dict of the subtarget string representation to the
providers_label
if the given labels
argument is list-like.
Note that this function does not check that this subtarget exists in the repo.
bxl.Context.unconfigured_targets
def bxl.Context.unconfigured_targets(
labels: bxl.UnconfiguredTargetNode | str | target_label | target_set | list[bxl.UnconfiguredTargetNode | str | target_label],
) -> bxl.UnconfiguredTargetNode | target_set
Gets the unconfigured target nodes for the labels
The given labels
is either:
- a single string that is a `target pattern`.
- a single unconfigured target node or label
- a list of the two options above.
This returns either a single [StarlarkTargetNode
] if the given labels
is "singular", a dict keyed by target labels of [StarlarkTargetNode
] if the
given labels
is list-like
bxl.Context.uquery
def bxl.Context.uquery() -> bxl.UqueryContext
Returns the uqueryctx
that holds all uquery functions.