forked from bazel-contrib/bazel-gazelle
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Stardoc generates extend.md (bazel-contrib#1128)
- Loading branch information
Showing
10 changed files
with
323 additions
and
199 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,155 @@ | ||
| <!-- Generated with Stardoc: http://skydoc.bazel.build --> | ||
|
|
||
|
|
||
| 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. | ||
|
|
||
| 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_python] has an extension for generating `py_library`, `py_binary`, and | ||
| `py_test` rules (currently pending in PR [#514]). | ||
| * [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). | ||
|
|
||
| ```starlark | ||
| 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: | ||
|
|
||
| ```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 | ||
| [rules_python]: https://github.com/bazelbuild/rules_python | ||
| [rules_r]: https://github.com/grailbio/rules_r | ||
| [rules_sass]: https://github.com/bazelbuild/rules_sass | ||
| [rules_haskell]: https://github.com/tweag/rules_haskell | ||
| [bazel_rules_nodejs_contrib]: https://github.com/ecosia/bazel_rules_nodejs_contrib#build-file-generation | ||
| [bazel-skylib]: https://github.com/bazelbuild/bazel-skylib | ||
| [@bazel_skylib//gazelle/bzl]: https://github.com/bazelbuild/bazel-skylib/tree/master/gazelle/bzl | ||
| [gazelle_cabal]: https://github.com/tweag/gazelle_cabal | ||
| [#75]: https://github.com/bazelbuild/rules_sass/pull/75 | ||
| [#514]: https://github.com/bazelbuild/rules_python/pull/514 | ||
| [#803]: https://github.com/bazelbuild/bazel-gazelle/issues/803 | ||
|
|
||
|
|
||
| <a id="#gazelle_binary"></a> | ||
|
|
||
| ## gazelle_binary | ||
|
|
||
| <pre> | ||
| gazelle_binary(<a href="#gazelle_binary-name">name</a>, <a href="#gazelle_binary-languages">languages</a>) | ||
| </pre> | ||
|
|
||
| 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. | ||
|
|
||
|
|
||
| **ATTRIBUTES** | ||
|
|
||
|
|
||
| | Name | Description | Type | Mandatory | Default | | ||
| | :------------- | :------------- | :------------- | :------------- | :------------- | | ||
| | <a id="gazelle_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | | ||
| | <a id="gazelle_binary-languages"></a>languages | A list of language extensions the Gazelle binary will use.<br><br> Each extension must be a [go_library] or something compatible. Each extension must export a function named <code>NewLanguage</code> with no parameters that returns a value assignable to [Language]. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | required | | | ||
|
|
||
|
|
Oops, something went wrong.