# buf-tools

Rust API for resolving paths to the official
[Buf](https://github.com/bufbuild/buf) CLI and `protoc-gen-buf-*` plugins.

- [crates.io/crates/buf-tools][crates-buf-tools]
- [docs.rs/buf-tools][docs-buf-tools]

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

[crates-buf-tools]: https://crates.io/crates/buf-tools
[docs-buf-tools]: https://docs.rs/buf-tools
[repo-readme]: https://github.com/canardleteer/buf-rs#readme

## 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](https://jedisct1.github.io/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.

```bash
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):

```toml
[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

```bash
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.
