Skip to main content

Bxl APIs

anon_rule​

def anon_rule(
*,
impl: typing.Callable["*, bxl_ctx: bxl.Context, attrs: struct(..)", list[Provider]],
attrs: dict[str, Attr],
doc: str = "",
artifact_promise_mappings: dict[str, typing.Callable[[typing.Any], list]] = ...,
) -> def(**kwargs: typing.Any) -> None

Create a new anonymous rule.

ctarget_set​

def ctarget_set(
nodes: list[bxl.ConfiguredTargetNode] = ...,
) -> target_set

Creates a target set from a list of configured nodes.

Sample usage:

def _impl_ctarget_set(ctx):
    targets = bxl.ctarget_set([cnode_a, cnode_b])
    ctx.output.print(type(targets))
    ctx.output.print(len(targets))

dynamic_actions​

def dynamic_actions(
*,
impl: typing.Callable["*, actions: AnalysisActions, **kwargs: typing.Any", list[Provider]],
attrs: dict[str, DynamicAttrType],
) -> DynamicActionCallable

Create new bxl dynamic action callable. Returned object will be callable, and the result of calling it can be passed to ctx.actions.dynamic_output_new.

fail_no_stacktrace​

def fail_no_stacktrace(*args) -> None

get_path_without_materialization​

def get_path_without_materialization(
this: Artifact,
ctx: bxl.Context,
/,
*,
abs: bool = False,
) -> str

The output path of an artifact-like (source, build, declared). Takes an optional boolean to print the absolute or relative path. Note that this method returns an artifact path without asking for the artifact to be materialized (i.e. it may not actually exist on the disk yet).

This is a risky function to call because you may accidentally pass this path to further BXL actions that expect the artifact to be materialized. If this happens, the BXL script will error out. If you want the path without materialization for other uses that don’t involve passing them into further actions, then it’s safe.

Sample usage:

def _impl_get_path_without_materialization(ctx):
    owner = ctx.cquery().owner("cell//path/to/file")[0]
    artifact = owner.get_source("cell//path/to/file", ctx)
    source_artifact_project_rel_path = get_path_without_materialization(artifact, ctx)
    ctx.output.print(source_artifact_project_rel_path) # Note this artifact is NOT ensured or materialized

get_paths_without_materialization​

def get_paths_without_materialization(
cmd_line: Artifact | CellPath | CellRoot | Label | OutputArtifact | ProjectRoot | ResolvedStringWithMacros | TaggedCommandLine | TargetLabel | TransitiveSetArgsProjection | WriteJsonCliArgs | cmd_args | str | RunInfo,
ctx: bxl.Context,
/,
*,
abs: bool = False,
)

The output paths of a cmd_args() inputs. The output paths will be returned as a list. Takes an optional boolean to print the absolute or relative path. Note that this method returns an artifact path without asking for the artifact to be materialized, (i.e. it may not actually exist on the disk yet).

This is a risky function to call because you may accidentally pass this path to further BXL actions that expect the artifact to be materialized. If this happens, the BXL script will error out. If you want the path without materialization for other uses that don’t involve passing them into further actions, then it’s safe.

Sample usage:

def _impl_get_paths_without_materialization(ctx):
    node = ctx.configured_targets("root//bin:the_binary")
    providers = ctx.analysis(node).providers()
    path = get_paths_without_materialization(providers[RunInfo], abs=True) # Note this artifact is NOT ensured or materialized
    ctx.output.print(path)

main​

def main(
*,
impl: typing.Callable,
cli_args: dict[str, bxl.CliArgs],
doc: str = "",
)

now​

def now() -> bxl.Instant

Creates an Instant at the current time.

Sample usage:

def _impl_elapsed_millis(ctx):
    instant = now()
    time_a = instant.elapsed_millis()
    # do something that takes a long time
    time_b = instant.elapsed_millis()

    ctx.output.print(time_a)
    ctx.output.print(time_b)

This function is only accessible through Bxl.

read_package_value​

def read_package_value(
package_path: PackagePath | str,
key: str,
/,
)

Read package value from the specified package path.

Returns the value specified in the PACKAGE file for the given package path and key, or None if not found.

This function returns the nearest name value registered per PACKAGE based on the given PackagePath or str, or None if such value does not exist.

The package parameter accepts any of the following:

  • A PackagePath
  • A string representing a package path (e.g., "root//some/package")

Sample usage:

def _impl_read_package_value(ctx):
    # Get a unconfigured target from the package we want to read metadata from
    node = ctx.unconfigured_targets("root//some/package:target")
    pkg_path = node.label.package_path

    # Read a package value with the given key from the unconfigured target
    pkg_value1 = bxl.read_package_value(pkg_path, "aaa.bbb")

    pkg_value2 = bxl.read_package_value("root//path/to/pkg", "aaa.ccc")

utarget_set​

def utarget_set(
nodes: list[bxl.UnconfiguredTargetNode] = ...,
) -> target_set

Creates a target set from a list of unconfigured nodes.

Sample usage:

def _impl_utarget_set(ctx):
    unode_a = ctx.unconfigured_targets("root//bin:foo")
    unode_b = ctx.unconfigured_targets("root//bin:bar")
    targets = bxl.utarget_set([unode_a, unode_b])
    ctx.output.print(type(targets))
    ctx.output.print(len(targets))