extend.rst

Extending Gazelle

Gazelle started out as a build file generator for Go projects, but it can be extended to support other languages and custom sets of rules.

To extend Gazelle, you must do three things:

• Write a go_library with a function named NewLanguage that provides an implementation of the Language interface. This interface provides hooks for generating rules, parsing configuration directives, and resolving imports to Bazel labels. By convention, the library's package name should match the language (for example, proto or bzl).
• Write a gazelle_binary rule. Include your library in the languages list.
• Write a gazelle rule that points to your gazelle_binary. When you run bazel run //:gazelle, your binary will be built and executed instead of the default binary.

Supported languages

Some extensions have been published by the community.

• bazel-skylib has an extension for generating bzl_library rules. See @bazel_skylib//gazelle/bzl.
• rules_sass has an extension for generating sass_library and sass_binary rules (currently pending in PR #75).
• rules_r has an extension for generating rules for R package builds and tests.
• Ecosia's bazel_rules_nodejs_contrib has an extension for generating js_library, jest_node_test, js_import, and ts_library rules.
• Tweag's rules_haskell has an extension, gazelle_cabal, for generating rules from Cabal files

If you have an extension you'd like linked here, please open a PR!

Example

TODO: Add a self-contained, concise, realistic example.

Gazelle itself is built using the model described above, so it may serve as an example.

//language/proto:go_default_library and //language/go:go_default_library both implement the Language interface. There is also //internal/gazellebinarytest:go_default_library, a stub implementation used for testing.

//cmd/gazelle is a gazelle_binary rule that includes both of these libraries through the DEFAULT_LANGUAGES list (you may want to use DEFAULT_LANGUAGES in your own rule).

load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle_binary")

gazelle_binary(
    name = "gazelle",
    languages = DEFAULT_LANGUAGES,
    visibility = ["//visibility:public"],
)

This binary can be invoked using a gazelle rule like this:

load("@bazel_gazelle//:def.bzl", "gazelle")

# gazelle:prefix example.com/project
gazelle(
    name = "gazelle",
    gazelle = "//:my_gazelle_binary",
)

You can run this with bazel run //:gazelle.

gazelle_binary

The gazelle_binary rule builds a Go binary that incorporates a list of language extensions. This requires generating a small amount of code that must be compiled into Gazelle's main package, so the normal go_binary rule is not used.

When the binary runs, each language extension is run sequentially. This affects the order that rules appear in generated build files. Metadata may be produced by an earlier extension and consumed by a later extension. For example, the proto extension stores metadata in hidden attributes of generated proto_library rules. The Go extension uses this metadata to generate go_proto_library rules.

The following attributes are supported on the gazelle_binary rule.

Name	Type	Default value
languages	label_list	mandatory value
A list of language extensions the Gazelle binary will use. Each extension must be a go_library or something compatible. Each extension must export a function named NewLanguage with no parameters that returns a value assignable to Language.

The following attributes are deprecated (#803):

Name	Type	Default value
pure	string	auto
Same meaning as go_binary. It may be necessary to set this to avoid command flags that affect both host and target configurations.
static | string | auto
Same meaning as go_binary. It may be necessary to set this to avoid command flags that affect both host and target configurations.
race	string	auto
Same meaning as go_binary. It may be necessary to set this to avoid command flags that affect both host and target configurations.
msan	string	auto
Same meaning as go_binary. It may be necessary to set this to avoid command flags that affect both host and target configurations.
goos	string	auto
Same meaning as go_binary. It may be necessary to set this to avoid command flags that affect both host and target configurations.
goarch | string | auto
Same meaning as go_binary. It may be necessary to set this to avoid command flags that affect both host and target configurations.

Interacting with protos

The proto extension (//language/proto:go_default_library) gathers metadata from .proto files and generates proto_library rules based on that metadata. Extensions that generate language-specific proto rules (e.g., go_proto_library) may use this metadata.

For API reference, see the proto godoc.

To get proto configuration information, call proto.GetProtoConfig. This is mainly useful for discovering the current proto mode.

To get information about proto_library rules, examine the OtherGen list of rules passed to language.GenerateRules. This is a list of rules generated by other language extensions, and it will include proto_library rules in each directory, if there were any. For each of these rules, you can call r.PrivateAttr(proto.PackageKey) to get a proto.Package record. This includes the proto package name, as well as source names, imports, and options.