Gazelle acts like a music arranger, making sure every instrument (source file) has the right sheet music (BUILD rules).
Gazelle is an automated tool for managing Bazel BUILD files in Go projects – a practical workflow to use or customize it.
update-repos
In Bazel, external Go modules are downloaded using go_repository rules. Gazelle generates one such rule for each module in go.mod and go.sum files, which are managed by the Go toolchain. In the Go monorepo, we have over one thousand external modules.
update and fix
Key Components
Loader
Reads project files (e.g., .go files for Go). Extracts metadata to inform Bazel build rules.
Resolver
Maps dependencies within the project or external sources. Ensures paths and package references are consistent.
Generator
Produces or updates Bazel BUILD files based on project structure and dependencies.
Directives
Inline instructions within source files to customize Gazelle’s behavior (e.g., # gazelle:exclude to skip files).
Lifecycle Overview
What happens when we run gazelle update
Project Files
|
[File Scanning]
- Collect source files (.go, .proto, etc.)
|
[Metadata Parsing]
- Extract imports, dependencies, and attributes
|
[Dependency Resolution]
- Map dependencies (internal and external) to Bazel-compatible paths
|
[Rule Generation]
- Write Bazel rules (e.g., go_library, proto_library)
|
[BUILD File Writing]
- Generate or update BUILD files
File Scanning
Gazelle starts by traversing the file system, looking for source files based on predefined patterns or user-specified configurations. It respects project-specific directives like # gazelle:exclude to skip directories or files.
Parsing and Metadata Extraction
Gazelle parses the files to extract key metadata. Metadata includes relationships and requirements between files.
Dependency Resolution
Outputs: A resolved dependency graph, ensuring Bazel can properly locate all resources.
Rule Generation
Generates specific Bazel rules (e.g., go_library, go_binary, proto_library) based on the file types and their roles.