Skip to main content
Jay added a Language interface that allows Gazelle to be extended to more languages — originally used for Protocol Buffers.

​
List of languages

The canonical list lives in the bazel-gazelle supported languages README. At a glance: The Aspect prebuilt binary bundles many of these — the valid languages keys for aspect_gazelle() are buf, cc, go, js, kotlin, orion, proto, python, starlark, and visibility_extension — so you typically don’t compose your own binary at all.

​
Why aren’t there more available?

There are a ton of Gazelle extensions - but they’re mostly in private repositories. That’s because it’s so hard to generalize to support everyone else’s repository conventions. Having an extension in your own repository has benefits. You can easily modify it to follow your local conventions, and to stamp out your own custom rules. We’ll see how writing extensions in Starlark gives you superpowers.

​
Writing your own extension

To write an extension in Go, you can follow the bazel-gazelle extension guide. However, writing a Go extension is hard work:
  • The API is low-level and pretty awkward, and takes a while to learn. Uber has their own alternative API specifically to work around this.
  • The API doesn’t have any opinion about how to parse the sources, and techniques vary widely.
  • Need to learn Go if you don’t already.
  • If you have Go code in your repo already, the deps in your go.mod become a mix of those needed for application code and those needed for extensions, sometimes causing conflicts.
It’s also awkward for OSS rulesets because of the distribution problems that come from having a Go dependency. bazel-skylib and rules_python both have gazelle extensions that require a separate Bazel module.

​
Write extensions in Starlark instead

You don’t have to learn Go, fork an existing language, or ship a separate Bazel module to teach Gazelle about your code. A Gazelle language nicknamed orion wraps a Starlark interpreter and exposes an API for writing your own extensions — in Starlark, the same language you already use in BUILD files. It’s enabled by default when using the aspect_gazelle_prebuilt module, so a product engineer can add BUILD generation for a new file type or custom rule in a handful of lines, right alongside the conventions they already maintain. The rest of this course shows you how:
  • The Starlark extension API — register rule kinds and declare targets with the “orion” API.
  • Examples — real Starlark extensions, from Go ports to from-scratch generators for PostCSS and C++.