Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

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

Before you can write Gazelle extensions in Starlark, you need to configure Gazelle to include the “Orion” language. This hosts the Starlark interpreter inside the Gazelle runtime.

​
Prebuilt

The aspect-gazelle repo publishes pre-compiled binaries of Gazelle with the Orion language included. See https://github.com/aspect-build/aspect-gazelle#install for instructions.

​
From source (advanced)

You can compile your own Gazelle from source and include the Orion language. Unlike the prebuilt approach, this lets you add your own Gazelle extensions written in Go. This includes first-party sources written in your repo, as well as third-party extensions not included in the prebuilt binary. Follow the standard setup instructions at https://github.com/bazel-contrib/bazel-gazelle#setup. Then add the https://github.com/aspect-build/aspect-gazelle/tree/main/language/orion Go module to your project, and finally 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.register_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.register_configure_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.register_configure_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,
)