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.

Be aware that the context argument of the called impl function differs between dynamic_actions where it is actions: AnalysisActions and bxl.dynamic_actions where it is bxl_ctx: bxl.Context.

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")

read_package_visibility​

def read_package_visibility(
package_path: PackagePath | str,
/,
)

Read the visibility declared via package() in the PACKAGE files for the given package path.

Returns the same JSON-shaped value as buck2 audit package-values: a list of visibility pattern strings (with target_name_glob(...) entries rendered as objects). An empty list means the package is visible to nothing by default.

The package_path 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_visibility(ctx):
    node = ctx.unconfigured_targets("root//some/package:target")
    visibility = bxl.read_package_visibility(node.label.package_path)

    visibility2 = bxl.read_package_visibility("root//path/to/pkg")

read_package_visibility_cap​

def read_package_visibility_cap(
package_path: PackagePath | str,
/,
)

Read the visibility cap propagated from enforce_visibility_intersection() in ancestor PACKAGE files for the given package path.

Returns the same JSON-shaped value as buck2 audit package-values: a list of pattern strings, or ["PUBLIC"] when no ancestor caps visibility (the default).

The package_path 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_visibility_cap(ctx):
    node = ctx.unconfigured_targets("root//some/package:target")
    visibility_cap = bxl.read_package_visibility_cap(node.label.package_path)

    visibility_cap2 = bxl.read_package_visibility_cap("root//path/to/pkg")

read_package_within_view​

def read_package_within_view(
package_path: PackagePath | str,
/,
)

Read the within_view declared via package() in the PACKAGE files for the given package path.

Returns the same JSON-shaped value as buck2 audit package-values: a list of pattern strings, or ["PUBLIC"] when the package may depend on anything (the default).

The package_path 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_within_view(ctx):
    node = ctx.unconfigured_targets("root//some/package:target")
    within_view = bxl.read_package_within_view(node.label.package_path)

    within_view2 = bxl.read_package_within_view("root//path/to/pkg")

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))