Skip to main content
Gazelle is the tool used across the Bazel ecosystem to create and maintain BUILD files automatically. It implements a tree walk over the source tree, essentially doing these steps:
  1. List the source files, to create or update a cc_library target with those in the srcs
  2. Read the source files and find the include statements.
  3. Each included symbol comes from a header file. Locate the cc_library target which provides the symbol and add it to deps.
  4. Merge the results with the original BUILD file
Thanks to that final step, Gazelle is non-destructive. Sections of the file which Gazelle doesn’t manage are left alone. You can also opt-out of Gazelle management of any syntactic element (a rule declaration, attribute list, or individual attribute) with a # keep comment.

​
Gazelle extension written in Go

Gazelle has a Language interface allowing extensions to add support for more languages. EngFlow have open-sourced an extension, which expects import statements to be relative to the repository root: https://github.com/EngFlow/gazelle_cc

​
Gazelle extension written in Starlark

Aspect CLI includes a bridge that allows writing extensions in Starlark, Bazel’s configuration language. See Extend Gazelle BUILD file generation for details. Here’s an example: https://github.com/aspect-build/bazel-examples/blob/main/.aspect/gazelle/rules_cc.axl

​
Demo

We can modify source files in the bazel-examples repo and regenerate BUILD files with the Aspect CLI’s gazelle task: aspect gazelle. With the tools/bazel wrapper installed you can also type bazel gazelle; without the CLI, run the target directly with bazel run //tools/gazelle:gazelle.