buf-tools

Rust API for resolving paths to the official Buf CLI and protoc-gen-buf-* plugins.

• crates.io/crates/buf-tools
• docs.rs/buf-tools

The repository overview is in the repo root README; this file ships in the published crate.

What this crate does

The crates.io tarball does not contain the executables (they exceed the registry size limit). On first build, build.rs downloads official release assets from bufbuild/buf on GitHub, verifies sha256.txt with minisign, and places binaries under Cargo’s OUT_DIR. The Buf release is pinned by this crate’s semver core (see CARGO_PKG_VERSION in build.rs).

Layout mode (BUF_RS_LAYOUT_MODE)

Compile-time selector for where binaries are exposed:

• cache (default): binaries under OUT_DIR, persistent cache for downloads.
• cache-link: cache plus symlinks (or copies) under target/buf-tools/<semver-core>/<TARGET>/bin.
• cache-verified-link: like cache-link, re-verifies cache contents before link/copy.
• target: artifacts under target/buf-tools/<semver-core>/<TARGET>/... without the shared cache layout.

Build output policy: default build_log=warn keeps happy paths quiet; set BUF_RS_BUILD_LOG=verbose or silent as needed.

BUF_RS_LAYOUT_MODE=cache-link cargo build -p buf-tools

Build-script logging (BUF_RS_BUILD_LOG)

• warn (default; true aliases this): warnings and failures only.
• verbose: full progress and diagnostics.
• silent (false aliases this): suppress warnings from the build script.

Build scripts only surface output via cargo:warning= lines.

Source-controlled configuration

Defaults can live in Cargo.toml metadata (overridden by env vars, highest precedence):

[workspace.metadata.buf-tools.config]
layout_mode = "cache-link"
build_log = "warn"
cache_dir = "target/buf-rs-cache"
# Example only — align with [workspace.package].version (authoritative).
release_base_url = "https://github.com/bufbuild/buf/releases/download/v1.40.0/"
source_base_url = "https://github.com/bufbuild/buf/archive/refs/tags/"

Per-package overrides use [package.metadata.buf-tools.config].

Supported keys: layout_mode, build_log, cache_dir, release_base_url, source_base_url. Resolution order: built-in defaults → workspace metadata → package metadata → environment (and optional .cargo/config.toml [env]).

Network

HTTPS GET to github.com only; no GitHub token required for release downloads.

Cache layout

Artifacts live under $BUF_RS_CACHE_DIR/<semver-core>/<TARGET>/ when set, otherwise under the platform cache dir (via the dirs crate), e.g. XDG_CACHE_HOME/buf-tools/.... A successful download survives cargo clean for that cache root.

Optional source tree (BUF_RS_INCLUDE_SOURCE)

When BUF_RS_INCLUDE_SOURCE=1, build.rs can fetch the tagged source archive from GitHub. Source tarballs are not covered by the same sha256.txt manifest as binaries; use for inspection, not as the primary integrity story.

URL overrides

• BUF_RS_RELEASE_BASE_URL — prefix for sha256.txt, signatures, and binaries (default https://github.com/bufbuild/buf/releases/download/v{X.Y.Z}/).
• BUF_RS_SOURCE_BASE_URL — prefix for optional source fetches (default https://github.com/bufbuild/buf/archive/refs/tags/).

Trailing slash optional.

Concurrent writers

build.rs uses a lock file under the cache slot so parallel builds do not corrupt downloads. With CARGO_NET_OFFLINE=true, a cold cache fails fast instead of downloading.

CI: online prewarm then offline build

BUF_RS_CACHE_DIR="$PWD/target/buf-rs-cache" cargo build -p buf-tools
BUF_RS_CACHE_DIR="$PWD/target/buf-rs-cache" CARGO_NET_OFFLINE=true \
  cargo build -p buf-tools

For supported targets and min_version metadata, see the crate API docs and buf-tools build_support sources in the repository.