# Module used by stardoc to generate API documentation. # Not meant for use by bazel-gazelle users. """ 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](#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. Tests ----- To write tests for your gazelle extension, you can use [gazelle_generation_test](#gazelle_generation_test), which will run a gazelle binary of your choosing on a set of test workspaces. Supported languages ------------------- Moved to [/README.rst](/README.rst#supported-languages) 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). ```starlark load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle_binary") gazelle_binary( name = "gazelle", languages = [ "@rules_python//gazelle", # Use gazelle from rules_python. "@bazel_gazelle//language/go", # Built-in rule from gazelle for Golang. "@bazel_gazelle//language/proto", # Built-in rule from gazelle for Protos. # Any languages that depend on Gazelle's proto plugin must come after it. "@external_repository//language/gazelle", # External languages can be added here. ], visibility = ["//visibility:public"], ) ``` This binary can be invoked using a `gazelle` rule like this: ```starlark 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`. 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. [Language]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language#Language [//internal/gazellebinarytest:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/internal/gazellebinarytest [//language/go:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/go [//language/proto:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/proto [gazelle]: https://github.com/bazelbuild/bazel-gazelle#bazel-rule [go_binary]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-binary [go_library]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-library [proto godoc]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto [proto.GetProtoConfig]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#GetProtoConfig [proto.Package]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#Package """ load("gazelle_binary.bzl", _gazelle_binary = "gazelle_binary") load( "//internal/generationtest:generationtest.bzl", _gazelle_generation_test = "gazelle_generation_test", ) gazelle_binary = _gazelle_binary gazelle_generation_test = _gazelle_generation_test