github.com/bazelbuild/bazel-gazelle@v0.36.1-0.20240520142334-61b277ba6fed/internal/extend_docs.bzl (about)

     1  # Module used by stardoc to generate API documentation.
     2  # Not meant for use by bazel-gazelle users.
     3  """
     4  Extending Gazelle
     5  =================
     6  
     7  Gazelle started out as a build file generator for Go projects, but it can be
     8  extended to support other languages and custom sets of rules.
     9  
    10  To 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  
    23  Tests
    24  -----
    25  
    26  To write tests for your gazelle extension, you can use [gazelle_generation_test](#gazelle_generation_test),
    27  which will run a gazelle binary of your choosing on a set of test workspaces.
    28  
    29  
    30  Supported languages
    31  -------------------
    32  
    33  Moved to [/README.rst](/README.rst#supported-languages)
    34  
    35  Example
    36  -------
    37  
    38  Gazelle itself is built using the model described above, so it may serve as
    39  an example.
    40  
    41  [//language/proto:go_default_library] and [//language/go:go_default_library]
    42  both implement the [Language]
    43  interface. There is also [//internal/gazellebinarytest:go_default_library],
    44  a stub implementation used for testing.
    45  
    46  `//cmd/gazelle` is a `gazelle_binary` rule that includes both of these
    47  libraries through the `DEFAULT_LANGUAGES` list (you may want to use
    48  `DEFAULT_LANGUAGES` in your own rule).
    49  
    50  ```starlark
    51  load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle_binary")
    52  
    53  gazelle_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  
    66  This binary can be invoked using a `gazelle` rule like this:
    67  
    68  ```starlark
    69  load("@bazel_gazelle//:def.bzl", "gazelle")
    70  
    71  # gazelle:prefix example.com/project
    72  gazelle(
    73      name = "gazelle",
    74      gazelle = "//:my_gazelle_binary",
    75  )
    76  ```
    77  
    78  You can run this with `bazel run //:gazelle`.
    79  
    80  Interacting with protos
    81  -----------------------
    82  
    83  The proto extension ([//language/proto:go_default_library]) gathers metadata
    84  from .proto files and generates `proto_library` rules based on that metadata.
    85  Extensions that generate language-specific proto rules (e.g.,
    86  `go_proto_library`) may use this metadata.
    87  
    88  For API reference, see the [proto godoc].
    89  
    90  To get proto configuration information, call [proto.GetProtoConfig]. This is
    91  mainly useful for discovering the current proto mode.
    92  
    93  To get information about `proto_library` rules, examine the `OtherGen`
    94  list of rules passed to `language.GenerateRules`. This is a list of rules
    95  generated by other language extensions, and it will include `proto_library`
    96  rules in each directory, if there were any. For each of these rules, you can
    97  call `r.PrivateAttr(proto.PackageKey)` to get a [proto.Package] record. This
    98  includes 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  
   112  load(
   113      "//internal/generationtest:generationtest.bzl",
   114      _gazelle_generation_test = "gazelle_generation_test",
   115  )
   116  load("gazelle_binary.bzl", _gazelle_binary = "gazelle_binary")
   117  
   118  gazelle_binary = _gazelle_binary
   119  
   120  gazelle_generation_test = _gazelle_generation_test