docs/custom_plugins.rst

:author: rules_proto_grpc
:description: Custom plugin support for protoc and Bazel proto_library targets
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Plugin, Protoc

.. _sec_custom_plugins:

Custom Plugins
==============

Custom plugins are supported by rules_proto_grpc, through the use of the ``proto_plugin`` Starlark
rule and creating of a rule that implements ``proto_compile_impl`` for the new plugin.

To add a new plugin, you can generally follow the pattern seen in the multiple language examples in
this repository. In short, the basic idea is:

1. Load the plugin rule: ``load("@rules_proto_grpc//:defs.bzl", "proto_plugin")``

2. Define the rule, giving it a ``name``, ``options`` (not mandatory), ``tool`` and ``outputs``.
   ``tool`` is a label that refers to the binary executable for the plugin itself and can be
   ``select()``'ed based on your platform, for example.

3. Choose your output type (pick one!):

   - ``outputs``: A list of strings patterns that predicts the pattern of files generated by the
     plugin. Use this type for plugins that produce one output file per input proto file.

   - ``out``: The name of a single output file generated by the plugin. Use this type for plugins
     that produce a single output file per call to protoc.

   - ``output_directory``: Set to true if your plugin generates files in a non-predictable way, for
     example if the output paths depend on the service names within the files.

4. Create a compilation rule and aspect using the following template, substituting the plugin label
   where indicated:

.. code-block:: python

   load("@rules_proto//proto:defs.bzl", "ProtoInfo")
   load(
       "@rules_proto_grpc//:defs.bzl",
       "ProtoPluginInfo",
       "proto_compile_attrs",
       "proto_compile_impl",
   )

   # Create compile rule
   example_compile = rule(
       implementation = proto_compile_impl,
       attrs = dict(
           proto_compile_attrs,
           _plugins = attr.label_list(
               providers = [ProtoPluginInfo],
               default = [
                   Label("//<LABEL OF YOUR PLUGIN>"),
               ],
               doc = "List of protoc plugins to apply",
           ),
       ),
       toolchains = [str(Label("@rules_proto_grpc//protobuf:toolchain_type"))],
   )