Developers

Contributions are very welcome on this project. Issues should be raised for bugs and feature requests. Pull requests should be targeted at the master branch and will run against CI.

Note

The rules in the repo are generated by the code in tools/rulegen and the output rules should therefore not be edited directly. However, if you are not comfortable editing this code, please submit a PR with just the output files edited and we’ll help update the generator to get the desired result.

Code Layout

Each language {lang} has a top-level subdirectory that contains:

  1. docs/{lang}.rst: Generated documentation for the language rules

  2. {lang}/repositories.bzl: Macro functions that declare repository rule dependencies for that language

  3. {lang}/{rule}.bzl: Rule implementations of the form {lang}_{kind}_{type}, where kind is one of proto|grpc and type is one of compile|library

  4. {lang}/BUILD.bazel: proto_plugin() declarations for the available plugins for the language

  5. example/{lang}/{rule}/: Generated WORKSPACE and BUILD.bazel demonstrating standalone usage of the rules

  6. {lang}/example/routeguide/: Example routeguide example implementation, if possible

Rule Generation

To help maintain consistency of the rule implementations and documentation, all of the rule implementations are generated by the tool //tools/rulegen. Changes in the main README.rst should be placed in tools/rulegen/README.header.rst or tools/rulegen/README.footer.rst`. Changes to generated rules should be put in the source files (example: tools/rulegen/java.go).

Developing Custom Plugins

Generally, follow the pattern seen in the multiple language examples in this repository. 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

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

    • outputs: A list of strings patterns that predicts the pattern of files generated by the plugin. For plugins that produce one output file per input proto file

    • out: The name of a single output file generated by the plugin

    • output_directory: Set to true if your plugin generates files in a non-predictable way. e.g. if the output paths depend on the service names within the files

  4. Create a compilation rule and aspect using the following template:

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"))],
)