Intro to Gazelle - Aspect Build

Gazelle descends from Glaze, a tool built internally at Google to make Go easier to adopt with Bazel (Glaze is to Blaze as Gazelle is to Bazel). Because Go’s import semantics were designed with Bazel in mind, resolving import statements to the packages that export them was straightforward — making it a natural fit for automation. Gazelle was built and long maintained by Jay Conrod at Google, and is now community-maintained at bazel-contrib/bazel-gazelle — part of bazel-contrib, a Bazel Technical Steering Committee organized under the Linux Foundation.

Basics

BUILD files are “bare facts” that describe the source code and its dependencies. These facts are mostly trivial to derive from the source code itself. So why force engineers to write these by hand? At a high level, it operates following the Visitor pattern:

Walk the source tree like Bazel does, respecting .bazelignore and similar config.
When descending into a directory, read any BUILD file’s “directive” comments for configuration.
Locate source files of interest, typically by file extension.
Declare Bazel targets and their import/export edges.
- Which targets to generate is determined by the source files found and language configuration.
- Imports are found by parsing import statements — similar to how an IDE’s language server works.
- Exports are usually inferred from file paths or package declarations in source files.
After the walk, resolve target imports to Bazel labels and write them into attributes like deps.
Merge updates into the BUILD file, or create one if the directory had none.

This is non-destructive: hand-edits to the BUILD file are preserved. To opt-out of Gazelle managing a syntax element, use the #keep comment, for example:

py_library(
    name = "keeps",
    # Don't manage this attribute at all
    # keep
    srcs = glob(["*.py"]),
    deps = [
        # Don't remove this even if it seems unused
        "@pypi//some-pkg:pkg",  # keep
    ],
)

# Leave this entire rule alone
# keep
js_library(
    name = "ignore",
    srcs = glob(["*.mjs"]),
)

The bazel-gazelle repo also has some Go-specifics, like the go_repository rule, which runs Gazelle on third-party Go packages to generate their BUILD files dynamically.

⌘I

​Basics

Basics