diff --git a/BUILD.bazel b/BUILD.bazel index 37175004b..856705cfc 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -32,7 +32,7 @@ nogo( visibility = ["//visibility:public"], ) -exports_files(["WORKSPACE", "repository.md"]) +exports_files(["WORKSPACE", "extend.md", "repository.md"]) filegroup( name = "all_files", diff --git a/README.rst b/README.rst index d01a402c0..220eea3e6 100644 --- a/README.rst +++ b/README.rst @@ -3,17 +3,17 @@ Gazelle build file generator .. All external links are here .. _Architecture of Gazelle: Design.rst -.. _Repository rules: repository.rst -.. _go_repository: repository.rst#go_repository +.. _Repository rules: repository.md +.. _go_repository: repository.md#go_repository .. _fix: #fix-and-update .. _update: #fix-and-update .. _Avoiding conflicts with proto rules: https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#avoiding-conflicts .. _gazelle rule: #bazel-rule .. _doublestar.Match: https://github.com/bmatcuk/doublestar#match -.. _Extending Gazelle: extend.rst -.. _Supported languages: extend.rst#supported-languages +.. _Extending Gazelle: extend.md +.. _Supported languages: extend.md#supported-languages .. _extended: `Extending Gazelle`_ -.. _gazelle_binary: extend.rst#gazelle_binary +.. _gazelle_binary: extend.md#gazelle_binary .. _import_prefix: https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library.import_prefix .. _strip_import_prefix: https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library.strip_import_prefix .. _buildozer: https://github.com/bazelbuild/buildtools/tree/master/buildozer diff --git a/WORKSPACE b/WORKSPACE index 5fcc89e68..6270c7e5b 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -15,10 +15,13 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "io_bazel_rules_go", - sha256 = "2b1641428dff9018f9e85c0384f03ec6c10660d935b750e3fa1492a281a53b0f", + sha256 = "e0c127187c63f96158a7fd609300e216f70b44912806f62f0d17c7d3a3872bc1", + strip_prefix = "rules_go-027d78bed3952d73c6fb7099b3247f903aa7318d", urls = [ - "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.zip", - "https://github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.zip", + # Need a prerelease version of rules_go to pick up bzl_library fixes + # https://github.com/bazelbuild/rules_go/pull/2942 + # Can go back to release artifact after 0.30 release + "https://github.com/bazelbuild/rules_go/archive/027d78bed3952d73c6fb7099b3247f903aa7318d.zip", ], ) diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index 3fb1594dd..e276ffdbf 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -10,6 +10,7 @@ load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") _DOC_SRCS = { "//internal:repository_docs": "repository.md", + "//internal:extend_docs": "extend.md", } [ diff --git a/extend.md b/extend.md new file mode 100644 index 000000000..129186b97 --- /dev/null +++ b/extend.md @@ -0,0 +1,155 @@ + + + +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 + + + + +## gazelle_binary + +
+gazelle_binary(name, languages)
+
+ +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 | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| languages | 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]. | List of labels | required | | + + diff --git a/extend.rst b/extend.rst index 3f23e5018..a1ede1754 100644 --- a/extend.rst +++ b/extend.rst @@ -1,191 +1,4 @@ Extending Gazelle ================= -.. Begin directives -.. _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_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 -.. _#803: https://github.com/bazelbuild/bazel-gazelle/issues/803 - -.. role:: cmd(code) -.. role:: flag(code) -.. role:: direc(code) -.. role:: param(kbd) -.. role:: type(emphasis) -.. role:: value(code) -.. |mandatory| replace:: **mandatory value** -.. End directives - -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). - -.. code:: bzl - - 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: - -.. code:: bzl - - 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** | -+======================+=====================+======================================+ -| :param:`languages` | :type:`label_list` | |mandatory| | -+----------------------+---------------------+--------------------------------------+ -| 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** | -+======================+=====================+======================================+ -| :param:`pure` | :type:`string` | :value:`auto` | -+----------------------+---------------------+--------------------------------------+ -| Same meaning as `go_binary`_. It may be necessary to set this to avoid | -| command flags that affect both host and target configurations. | -+----------------------+---------------------+--------------------------------------+ -| :param:`static` | :type:`string` | :value:`auto` | -+----------------------+---------------------+--------------------------------------+ -| Same meaning as `go_binary`_. It may be necessary to set this to avoid | -| command flags that affect both host and target configurations. | -+----------------------+---------------------+--------------------------------------+ -| :param:`race` | :type:`string` | :value:`auto` | -+----------------------+---------------------+--------------------------------------+ -| Same meaning as `go_binary`_. It may be necessary to set this to avoid | -| command flags that affect both host and target configurations. | -+----------------------+---------------------+--------------------------------------+ -| :param:`msan` | :type:`string` | :value:`auto` | -+----------------------+---------------------+--------------------------------------+ -| Same meaning as `go_binary`_. It may be necessary to set this to avoid | -| command flags that affect both host and target configurations. | -+----------------------+---------------------+--------------------------------------+ -| :param:`goos` | :type:`string` | :value:`auto` | -+----------------------+---------------------+--------------------------------------+ -| Same meaning as `go_binary`_. It may be necessary to set this to avoid | -| command flags that affect both host and target configurations. | -+----------------------+---------------------+--------------------------------------+ -| :param:`goarch` | :type:`string` | :value:`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. +`Moved to markdown <./extend.md>`_ diff --git a/internal/BUILD.bazel b/internal/BUILD.bazel index 6fa6c557e..d61873eb8 100644 --- a/internal/BUILD.bazel +++ b/internal/BUILD.bazel @@ -20,6 +20,7 @@ go_bazel_test( exports_files( [ "gazelle.bash.in", + "extend_docs.bzl", "repository_docs.bzl", "list_repository_tools_srcs.go", "repository_rules_test_errors.patch", @@ -123,4 +124,11 @@ bzl_library( ":overlay_repository", ], visibility = ["//:__subpackages__"], +) + +bzl_library( + name = "extend_docs", + srcs = ["extend_docs.bzl"], + deps = [":gazelle_binary"], + visibility = ["//:__subpackages__"], ) \ No newline at end of file diff --git a/internal/extend_docs.bzl b/internal/extend_docs.bzl new file mode 100644 index 000000000..d7cba1b9f --- /dev/null +++ b/internal/extend_docs.bzl @@ -0,0 +1,128 @@ +# 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. + +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 +""" + +load("gazelle_binary.bzl", _gazelle_binary = "gazelle_binary") + +gazelle_binary = _gazelle_binary diff --git a/internal/gazelle_binary.bzl b/internal/gazelle_binary.bzl index 0e1afb342..2517675fc 100644 --- a/internal/gazelle_binary.bzl +++ b/internal/gazelle_binary.bzl @@ -76,9 +76,25 @@ var languages = []language.Language{{ _gazelle_binary_kwargs = { "implementation": _gazelle_binary_impl, + "doc": """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. +""", "attrs": { "languages": attr.label_list( - doc = "A list of language extensions the Gazelle binary will use", + doc = """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].""", providers = [GoArchive], mandatory = True, allow_empty = False, diff --git a/internal/go_repository.bzl b/internal/go_repository.bzl index 27b8b0b84..406b5cff8 100644 --- a/internal/go_repository.bzl +++ b/internal/go_repository.bzl @@ -478,7 +478,7 @@ go_repository = repository_rule( ), }, ) -"""See repository.rst#go-repository for full documentation.""" +"""See repository.md#go-repository for full documentation.""" # Copied from @bazel_tools//tools/build_defs/repo:utils.bzl def patch(ctx):