> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Hands-on course for automating BUILD file generation with Gazelle and Starlark, including writing custom Gazelle extensions for new languages.
{!user.loggedIn ? (
Sign up for a free Aspect account to access the full training course. Already have one? Log in.
) : null}
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](/learning/bazel-101).
* The free [Aspect CLI](/docs/cli) installed (the Starlark extension API ships with it).
## Course contents
The problem Gazelle solves: Starlark friction, hand-maintained dependency graphs, and the gap between infra experts and product engineers.
Where Gazelle came from and how it walks your source tree to generate and merge BUILD files without clobbering your edits.
Run a prebuilt Gazelle binary the easy way, and learn why that beats building from source.
Which languages Gazelle supports out of the box, who maintains each extension, and why writing your own is often the right call.
Steer Gazelle with directives like exclude, map\_kind, and resolve — and when to avoid directives entirely.
Meet "orion", the Aspect CLI extension API. Register rule kinds and declare targets in a few lines of Starlark.
Inspect source files with regex and tree-sitter AST queries to detect imports, tests, and any syntax you care about.
Real Starlark extensions: ports from Go, plus from-scratch generators for PostCSS and C++.
Augment the stock Gazelle binary with small Starlark extensions — OCI images, lint tests, codegen targets, and more.
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: