github.com/stackb/rules_proto@v0.0.0-20240221195024-5428336c51f1/docs/configuration.md (about)

     1  ---
     2  layout: default
     3  title: Configuration
     4  permalink: guides/configuration
     5  parent: Guides
     6  nav_order: 2
     7  ---
     8  
     9  If you haven't done so already, [install gazelle](installation).
    10  
    11  Configuration of the `protobuf` gazelle language involves adding *gazelle
    12  directives* to your build files.  Directives in a package are inherited by child
    13  packages, so the typical place to put common directives is in the root
    14  `BUILD.bazel` file.  However, if you have a common subdirectory for your protos
    15  like `./proto/BUILD.bazel`, that would be an appropriate place as well.
    16  
    17  There are three directives you'll want to become familiar with:
    18  
    19  1. `gazelle:proto_rule`
    20  2. `gazelle:proto_plugin`
    21  3. `gazelle:proto_language`
    22  
    23  A simple setup could be:
    24  
    25  ```python
    26  # gazelle:proto_rule proto_compile implementation stackb:rules_proto:proto_compile
    27  # gazelle:proto_plugin python implementation builtin:python
    28  # gazelle:proto_language python rule proto_compile
    29  # gazelle:proto_language python plugin python
    30  # gazelle:proto_language python enabled true
    31  ```
    32  
    33  Let's break this down a bit:
    34  
    35  1. The `proto_rule` directive reads as "create a new rule configration named
    36     "proto_compile" whose golang implementation is registered as
    37     `stackb:rules_proto:proto_compile`".  The `protobuf` gazelle extension
    38     maintains a global registry of rule implementations; see
    39     [rules](/rules_proto/rules) for a list of pre-registered rules, or
    40     [custom rules](/rules_proto/rules/custom) for a guide to implementing your own.  The config
    41     name is just a string identifier, choose whatever suits your preference.
    42  1. The `proto_plugin` directive reads as "create a new plugin configration named
    43     'python' whose golang implementation is registered as `builtin:python`".  The
    44     `protobuf` gazelle extension maintains a global registry of plugin
    45     implementations; see [plugins](/rules_proto/plugins) for a list of
    46     pre-registered plugins, or [custom plugins](/plugins_proto/plugins/custom)
    47     for a guide to implementing your own.  The config name is just a string
    48     identifier, choose whatever suits your preference.
    49  1. The `proto_language` directive reads as "create a new language configuration
    50     and add the 'proto_compile' rule config".  The next line says "add the
    51     'python' plugin to the 'python' language config.  Finally, the last line
    52     flips the language to be enabled.  
    53  
    54  ## proto_rule
    55  
    56  The `gazelle:proto_rule` directive is a tuple of strings `NAME KEY VALUE`.
    57  `NAME` is just an identifier.  The list of available keys are (see
    58  [language_rule_config.go] for more info):
    59  
    60  | proto_rule key   | description                                                           |
    61  | ---------------- | --------------------------------------------------------------------- |
    62  | `implementation` | Identifier for a rule that has been installed into the rule registry. |
    63  | `visibility`     | Default visibility for the generated rule.                            |
    64  | `dep`            | Bazel label to be added to the list of `deps` for the generated rule. |
    65  | `enabled`        | Toggle to enable/disable rule generation on a per-package basis.      |
    66  
    67  `proto_rule` creates/updates a configuration for an entity that knows how to
    68  generate a build rule based on a single `proto_library` rule.
    69  
    70  ## proto_plugin
    71  
    72  The `gazelle:proto_plugin` directive is a tuple of strings `NAME KEY VALUE`.
    73  `NAME` is just an identifier.  The list of available keys are (see
    74  [language_plugin_config.go] for more info):
    75  
    76  | proto_plugin key | description                                                                         |
    77  | ---------------- | ----------------------------------------------------------------------------------- |
    78  | `implementation` | Identifier for a plugin that has been installed into the plugin registry.           |
    79  | `option`         | plugin option to be passed to the compiler invocation (e.g. `import_style=closure`) |
    80  | `label`          | Bazel label for the `ProtoPluginInfo` provider. ^1                                    |
    81  | `enabled`        | Toggle to enable/disable the plugin on a per-package basis.                         |
    82  
    83  ^1: Each `proto_plugin` implementation must also have a corresponding
    84  `proto_plugin` rule (see [proto_plugin.bzl]).  The primary purpose of the
    85  `proto_plugin` rule is to associate the binary `tool` for the plugin.  For
    86  example the tool for `protoc-gen-go` tool is
    87  `@com_github_grpc_grpc_go//cmd/protoc-gen-go`.  Use `label` value to override
    88  the default that is provided by the implementation.
    89  
    90  `proto_plugin` creates/updates a configuration for an entity that works with a
    91  rule.  The primary job of a plugin is to predict what output files are going to
    92  be produced by a protoc plugin binary.  For example, the gazelle proto_plugin
    93  implementation for `protoc-gen-go` knows that for any file `foo.proto` with
    94  `package a.b.c`, a file `{EXECROOT}/a/b/c/foo.pb.go` will be generated *unless*
    95  that file also has a go_package option like `go_package github.com/bar/baz:baz`;
    96  in this case the output file will be `{EXECROOT}/github.com/bar/baz/foo.pb.go`.
    97  
    98  ## proto_language
    99  
   100  The `gazelle:proto_language` directive is a tuple of strings `NAME KEY VALUE`.
   101  `NAME` is just an identifier.  The list of available keys are (see
   102  [language_config.go] for more info):
   103  
   104  `proto_language` creates/updates a configuration for an entity that associates
   105  rules and plugins together, and can be enabled/disabled on a per-package basis.
   106  
   107  [language_rule_config.go]: https://github.com/stackb/rules_proto/language_rule_config.go
   108  [language_plugin_config.go]: https://github.com/stackb/rules_proto/language_plugin_config.go
   109  [language_config.go]: https://github.com/stackb/rules_proto/language_config.go
   110  [proto_plugin.bzl]: https://github.com/stackb/rules_proto/rules/proto_plugin.bzl
   111  
   112  ## intents
   113  
   114  For directives `gazelle:proto_*` whose form is `NAME KEY VALUE`, the `KEY` can
   115  take an "intent modifier" `+KEY` or `-KEY` to express positive or negative
   116  intent (by default, intent is positive so `KEY` and `+KEY` are equivalent).
   117  Examples:
   118  
   119  "Remove the mypy plugin from the python language in this BUILD file":
   120  
   121  ```
   122  # gazelle:proto_language python -plugin mypy
   123  ```
   124  
   125  "Turn off gRPC for the gogofast plugin in this BUILD file":
   126  
   127  ```
   128  # gazelle:proto_plugin gogofast -option plugins=grpc
   129  ```
   130