rules_buf

Bazel rules for Buf. The rules work alongside the proto_library rule of rules_proto.

Status

This module is a beta, but we may make a few changes as we gather feedback from early adopters.

Setup

Bazel modules (MODULE.bazel)

rules_buf is published to the Bazel Central Registry. Add the following to your MODULE.bazel:

bazel_dep(name = "rules_buf", version = "0.5.2")

buf = use_extension("@rules_buf//buf:extensions.bzl", "buf")

# Pin the buf CLI version (optional; a default version is used otherwise).
buf.toolchains(version = "v1.68.4")

use_repo(buf, "rules_buf_toolchains")

Legacy WORKSPACE

For projects that have not yet migrated to Bazel modules:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_buf",
    sha256 = "4a024a411996967c3a3f49b04765bd016169a2c79be3dc78aa62bfa2643850ef",
    strip_prefix = "rules_buf-0.5.2",
    urls = [
        "https://github.com/bufbuild/rules_buf/releases/download/v0.5.2/rules_buf-0.5.2.tar.gz",
    ],
)

load("@rules_buf//buf:repositories.bzl", "rules_buf_dependencies", "rules_buf_toolchains")

rules_buf_dependencies()

rules_buf_toolchains(version = "v1.68.4")

# rules_proto
load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies")

rules_proto_dependencies()

load("@rules_proto//proto:setup.bzl", "rules_proto_setup")

rules_proto_setup()

Refer to the latest release notes for the exact sha256 and version to pin.

Refer to the docs or browse the examples on how to set up and use rules_buf in various scenarios.

List of rules

• buf_dependencies
• buf_lint_test
• buf_breaking_test
• buf_format

See docs/buf-rules.md for the full attribute reference, generated from the rule definitions.

Gazelle Extension

The repo also offers a Gazelle extension for generating the rules.

Please refer to the gazelle section in the docs.

Development

The repository follows the official recommendation on deploying bazel rules. All the rule definitions are in buf/internal.

Gazelle

Gazelle extension is in gazelle/buf. Before looking at the code it would be best to understand the architecture of gazelle. The file structure is loosely based on the go and proto extensions that are shipped with gazelle. They are also excellent to better understand the architecture.

The main entry point to the extension is via the NewLanguage function in gazelle/buf/buf.go. Gazelle mostly depends on Language interface. Apart from that one can also implement some optional interfaces.

We implement the following interfaces,

• Language: Required. Used for build/test rule generation and label resolutions for these rules.
• RepoImporter: Optional. Used to generate buf_dependencies rule from buf.yaml/buf.work.yaml.
• CrossResolver: Optional. Used to resolve dependencies across extensions/languages. We use it to resolve any proto files that are part of buf_dependencies rules.