Skip to main content
Writing Bazel BUILD files by hand requires knowing its configuration language — a barrier for many engineers. This course removes that friction by generating BUILD files automatically.
Bazel makes you declare your dependency graph in BUILD files before it will build anything. Maintaining those files by hand is tedious and error-prone. Gazelle reads your source code and writes the BUILD files for you, and the Aspect CLI lets you teach Gazelle about new languages and conventions using Starlark — no Go required. This is a practical, hands-on tutorial. By the end you’ll be able to generate BUILD files for your repository and extend that generation to your own rules and file types.

​
What you’ll learn

  • Why Bazel needs BUILD file generation, and how Gazelle fills the gap.
  • How Gazelle scans your project and produces accurate, non-destructive build targets.
  • How to configure Gazelle with directives for real-world repository layouts.
  • How to write extensions in Starlark to support new languages, custom rules, and project conventions — and how to test them.

​
Prerequisites

  • A working knowledge of Bazel and BUILD files. New to Bazel? Start with Bazel 101.
  • The free Aspect CLI installed (the Starlark extension API ships with it).

​
Course contents

Why generate BUILD files

The problem Gazelle solves: Starlark friction, hand-maintained dependency graphs, and the gap between infra experts and product engineers.

Intro to Gazelle

Where Gazelle came from and how it walks your source tree to generate and merge BUILD files without clobbering your edits.

Install

Run a prebuilt Gazelle binary the easy way, and learn why that beats building from source.

Available languages

Which languages Gazelle supports out of the box, who maintains each extension, and why writing your own is often the right call.

Configuration

Steer Gazelle with directives like exclude, map_kind, and resolve — and when to avoid directives entirely.

The Starlark extension API

Meet “orion”, the Aspect CLI extension API. Register rule kinds and declare targets in a few lines of Starlark.

Query API

Inspect source files with regex and tree-sitter AST queries to detect imports, tests, and any syntax you care about.

Examples

Real Starlark extensions: ports from Go, plus from-scratch generators for PostCSS and C++.

Extending existing languages

Augment the stock Gazelle binary with small Starlark extensions — OCI images, lint tests, codegen targets, and more.

Testing

Verify your extensions with Gazelle’s golden-file test fixtures — for both Go and Starlark generators.

​
Watch the talk

Prefer to watch first? Here’s the live presentation of this course: