forked from bazel-contrib/bazel-gazelle
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathextend_docs.bzl
120 lines (93 loc) · 4.7 KB
/
extend_docs.bzl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# 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