Extend Gazelle BUILD file generation

This page covers writing custom Gazelle extensions in AXL, run by the Orion Gazelle language. For running aspect gazelle in CI (setup, flags, and CI YAML), see aspect gazelle.

Gazelle is the standard tool for generating or updating Bazel build definitions (files named BUILD, which Bazel uses to describe build targets) based on the content of source files. Gazelle offers a Go API so you can extend it with support for additional languages. See the Extending Gazelle documentation for details. Learning this API requires effort and adds a compile-time dependency for developers. Instead, you can use the Aspect Extension Language (AXL), a Starlark dialect, to write Starlark extensions that augment Gazelle.

Install Orion

Extensions run in “Orion”, a Gazelle language that hosts a Starlark interpreter inside Gazelle.

Prebuilt

The prebuilt Gazelle from aspect_gazelle_prebuilt includes Orion. Set it up as in aspect gazelle › Prebuilt binary.

From source (advanced)

Compile your own Gazelle when you also need Go extensions: first-party ones in your repo, or third-party extensions the prebuilt binary doesn’t include. Follow the standard Gazelle setup, add the Orion Go module to your project, and add its go_library target to the languages list in gazelle_binary.

Define an extension

Start by registering the rule kinds your extension will generate. For example, to generate BUILD files that include:

load("//tools/oci:go_image.bzl", "go_image")

Declare the rule kind:

aspect.gazelle_rule_kind("go_image", {
    "From": "//tools/oci:go_image.bzl",
    "ResolveAttrs": ["binary"],
})

Next, define two functions for your extension:

prepare: Specify what information your extension needs from the source files, such as file extensions or regular expression queries.
declare: Implement the logic to generate new build targets based on the collected information.

Pass these functions to aspect.orion_extension() to register your extension with Gazelle. You can use named functions or anonymous lambdas as needed. The following code continues the example:

def declare_targets(ctx):
    for file in ctx.sources:
        if len(file.query_results["has_main"]) > 0:
            ctx.targets.add(
                name = "image",
                kind = "go_image",
                attrs = {
                    "binary": path.base(ctx.rel),
                },
            )

aspect.orion_extension(
    id = "go_image",
    prepare = lambda cfg: aspect.PrepareResult(
        sources = [aspect.SourceExtensions(".go")],
        queries = {
            "has_main": aspect.RegexQuery(
                filter = "*.go",
                expression = """(?P<main>func\\s+main\\(.*?\\))""",
            ),
        },
    ),
    declare = declare_targets,
)

The older names aspect.register_rule_kind and aspect.register_configure_extension still work but print a deprecation warning.

Run the extension

Save the extension as tools/gazelle/go_image.axl and add it to the extensions of your aspect_gazelle target:

tools/gazelle/BUILD

load("@aspect_gazelle_prebuilt//:def.bzl", "aspect_gazelle")

aspect_gazelle(
    name = "gazelle",
    languages = ["go"],
    extensions = ["go_image.axl"],
)

Then run aspect gazelle to generate the go_image targets. Disable the extension in a package and its subpackages with a # gazelle:go_image disabled directive in the BUILD file. For a hands-on walkthrough of writing extensions, see the Aspect 150 course.

​Install Orion

​Prebuilt

​From source (advanced)

​Define an extension

​Run the extension

Install Orion

Prebuilt

From source (advanced)

Define an extension

Run the extension