1# Module used by stardoc to generate API documentation.
2# Not meant for use by bazel-gazelle users.
3"""
4Extending Gazelle
5=================
6
7Gazelle started out as a build file generator for Go projects, but it can be
8extended to support other languages and custom sets of rules.
9
10To extend Gazelle, you must do three things:
11
12* Write a [go_library] with a function named `NewLanguage` that provides an
13 implementation of the [Language] interface. This interface provides hooks for
14 generating rules, parsing configuration directives, and resolving imports
15 to Bazel labels. By convention, the library's package name should match
16 the language (for example, `proto` or `bzl`).
17* Write a [gazelle_binary](#gazelle_binary) rule. Include your library in the `languages`
18 list.
19* Write a [gazelle] rule that points to your `gazelle_binary`. When you run
20 `bazel run //:gazelle`, your binary will be built and executed instead of
21 the default binary.
22
23Tests
24-----
25
26To write tests for your gazelle extension, you can use [gazelle_generation_test](#gazelle_generation_test),
27which will run a gazelle binary of your choosing on a set of test workspaces.
28
29
30Supported languages
31-------------------
32
33Moved to [/README.rst](/README.rst#supported-languages)
34
35Example
36-------
37
38Gazelle itself is built using the model described above, so it may serve as
39an example.
40
41[//language/proto:go_default_library] and [//language/go:go_default_library]
42both implement the [Language]
43interface. There is also [//internal/gazellebinarytest:go_default_library],
44a stub implementation used for testing.
45
46`//cmd/gazelle` is a `gazelle_binary` rule that includes both of these
47libraries through the `DEFAULT_LANGUAGES` list (you may want to use
48`DEFAULT_LANGUAGES` in your own rule).
49
50```starlark
51load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle_binary")
52
53gazelle_binary(
54 name = "gazelle",
55 languages = [
56 "@rules_python//gazelle", # Use gazelle from rules_python.
57 "@bazel_gazelle//language/go", # Built-in rule from gazelle for Golang.
58 "@bazel_gazelle//language/proto", # Built-in rule from gazelle for Protos.
59 # Any languages that depend on Gazelle's proto plugin must come after it.
60 "@external_repository//language/gazelle", # External languages can be added here.
61 ],
62 visibility = ["//visibility:public"],
63)
64```
65
66This binary can be invoked using a `gazelle` rule like this:
67
68```starlark
69load("@bazel_gazelle//:def.bzl", "gazelle")
70
71# gazelle:prefix example.com/project
72gazelle(
73 name = "gazelle",
74 gazelle = "//:my_gazelle_binary",
75)
76```
77
78You can run this with `bazel run //:gazelle`.
79
80Interacting with protos
81-----------------------
82
83The proto extension ([//language/proto:go_default_library]) gathers metadata
84from .proto files and generates `proto_library` rules based on that metadata.
85Extensions that generate language-specific proto rules (e.g.,
86`go_proto_library`) may use this metadata.
87
88For API reference, see the [proto godoc].
89
90To get proto configuration information, call [proto.GetProtoConfig]. This is
91mainly useful for discovering the current proto mode.
92
93To get information about `proto_library` rules, examine the `OtherGen`
94list of rules passed to `language.GenerateRules`. This is a list of rules
95generated by other language extensions, and it will include `proto_library`
96rules in each directory, if there were any. For each of these rules, you can
97call `r.PrivateAttr(proto.PackageKey)` to get a [proto.Package] record. This
98includes the proto package name, as well as source names, imports, and options.
99
100[Language]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language#Language
101[//internal/gazellebinarytest:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/internal/gazellebinarytest
102[//language/go:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/go
103[//language/proto:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/proto
104[gazelle]: https://github.com/bazelbuild/bazel-gazelle#bazel-rule
105[go_binary]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-binary
106[go_library]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-library
107[proto godoc]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto
108[proto.GetProtoConfig]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#GetProtoConfig
109[proto.Package]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#Package
110"""
111
112load("gazelle_binary.bzl", _gazelle_binary = "gazelle_binary")
113load(
114 "//internal/generationtest:generationtest.bzl",
115 _gazelle_generation_test = "gazelle_generation_test",
116)
117
118gazelle_binary = _gazelle_binary
119
120gazelle_generation_test = _gazelle_generation_test
View as plain text