Bazel rules

Today we're excited to release Bazel rules for buf, rules_buf.

Bazel is a scalable multi-language build tool for large projects that focuses on reproducibility and speed. This resonates strongly at Buf where we help teams develop robust, language agnostic, scalable APIs.

The rules work alongside the proto_library rule of rules_proto.

Managing dependencies

The buf_dependencies repository rule helps manage Protobuf dependencies using the Buf Schema Registry (BSR). Here's a small example that demonstrates using the rule to gather dependencies into a target called buf_deps.

WORKSPACE

load("@rules_buf//buf:defs.bzl", "buf_dependencies")

buf_dependencies(
    name = "buf_deps",
    modules = [
        "buf.build/envoyproxy/protoc-gen-validate:dc09a417d27241f7b069feae2cd74a0e",
        "buf.build/acme/petapis:84a33a06f0954823a6f2a089fb1bb82e",
    ],
)

This can now be used as part of the deps attribute in the proto_library rule like this,

BUILD

load("@rules_proto//proto:defs.bzl", "proto_library")

proto_library(
    name = "foo_proto",
    srcs = [
        "pet.proto" # imports "validate/validate.proto"
    ],
    deps = [
        "@buf_deps//validate:validate_proto"
    ],
)

You can read more about this in the docs.

Lint and Breaking Checks

buf lint and buf breaking are widely used to ensure quality standards of Protobuf APIs are met. Now, you can use them within Bazel. Here's an example,

Breaking rule

BUILD

load("@rules_buf//buf:defs.bzl", "buf_breaking_test")

exports_files(["buf.yaml"])

buf_breaking_test(
    name = "foo_proto_breaking",
    against = "//:image.bin", # The Image file to check against.
    targets = ["//foo/v1:foo_proto"], # The Protobuf library targets to check
    config = ":buf.yaml",
)

Running bazel test --test_output=errors //:foo_proto_breaking will print the errors,

...
Executing tests from //:foo_proto_breaking
-----------------------------------------------------------------------------
--buf-plugin_out: foo/v1/foo.proto:1:1:Field "3" with name "Bar" on message "Foo" changed option "json_name" from "bar" to "Bar".
foo/v1/foo.proto:1:1:Field "3" on message "Foo" changed name from "bar" to "Bar".

Lint rule

foo/v1/BUILD

load("@rules_buf//buf:defs.bzl", "buf_lint_test")
load("@rules_proto//proto:defs.bzl", "proto_library")

proto_library(
    name = "foo_proto",
    srcs = ["foo.proto"],
)

buf_lint_test(
    name = "foo_proto_lint",
    targets = [":foo_proto"],
    config = "//:buf.yaml",
)

Running bazel test --test_output=errors //foo/v1:foo_proto_lint will print the errors,

...
Executing tests from //foo/v1:foo_proto_lint
-----------------------------------------------------------------------------
--buf-plugin_out: foo/v1/foo.proto:1:1:Field name "Bar" should be lower_snake_case, such as "bar".

For more on these rules check out the docs for buf_lint_test and buf_breaking_test

Generate rules

At Buf we are strong believers of automation and hence we couldn't resist developing a Gazelle extension. The extension can be used to generate all of above rules! It understands both buf.work.yaml and buf.yaml configuration files.

Check out the Gazelle section of the docs for setup and usage instructions.

Next steps

Get started by setting up rules_buf or check out the examples illustrating various scenarios.

‍