Skip to main content

bxl_ctx 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_ctx.actions_factory​

bxl_ctx.actions_factory: ""

Returns the action context for creating and running actions.

bxl_ctx.analysis​

def bxl_ctx.analysis(
    labels: "",
    target_platform: "" = None,
    skip_incompatible: bool.type = True
) -> ""

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 [StarlarkAnalysisResult] if the given labels is "singular", or a dict keyed by sub target labels of [StarlarkAnalysisResult] if the given labels is list-like

bxl_ctx.audit​

def bxl_ctx.audit() -> "audit_ctx"

Returns the [StarlarkAuditCtx] that holds all the audit functions.

bxl_ctx.build​

def bxl_ctx.build(
    spec: "",
    target_platform: "" = None,
    *,
    materializations: str.type = "default"
) -> ""

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 of [StarlarkBuildResult] if the given labels is list-like

bxl_ctx.bxl_actions​

def bxl_ctx.bxl_actions(
    *,
    exec_deps: "" = None,
    toolchains: "" = None,
    target_platform: "" = None,
    exec_compatible_with: "" = 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 [BxlContext]. 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.

bxl_ctx.cli_args​

bxl_ctx.cli_args: ""

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.

bxl_ctx.configured_targets​

def bxl_ctx.configured_targets(labels: "", target_platform: "" = None) -> ""

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 [TargetExpr], 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 [StarlarkConfiguredTargetNode] if the given labels is "singular", a dict keyed by target labels of [StarlarkConfiguredTargetNode] if the given labels is list-like

bxl_ctx.cquery​

def bxl_ctx.cquery(target_platform: "" = None) -> "cqueryctx"

Returns the [StarlarkCQueryCtx] 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_ctx.fs​

bxl_ctx.fs: "fs"

Returns the [BxlFilesystem] for performing a basic set of filesystem operations within bxl

bxl_ctx.instant_event​

def bxl_ctx.instant_event(*, id: str.type, 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.

bxl_ctx.output​

bxl_ctx.output: ""

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.

bxl_ctx.resolve​

def bxl_ctx.resolve(action_factory: "actions", promise: "promise") -> [None, ""]

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.actions_factory
    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).map(my_map_function)
    providers_result = ctx.resolve(promise) # result is `provider_callable` type, which is a collection of `provider`s
    ctx.output.print(providers_result[0].my_field)

bxl_ctx.root​

def bxl_ctx.root() -> str.type

Returns the absolute path to the root of the repository

bxl_ctx.unconfigured_targets​

def bxl_ctx.unconfigured_targets(labels: "") -> ""

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_ctx.uquery​

def bxl_ctx.uquery() -> "uqueryctx"

Returns the [StarlarkUQueryCtx] that holds all uquery functions.