blog.ndumas.com/content/posts/stamping-builds-with-bazel/index.md

draft	title	aliases	series	series_order	date	author	cover	keywords	summary	summary	showFullContent	tags
false	Stamping Builds with Bazel	Stamping Builds with Bazel	building-with-bazel	3	2024-05-15	Nick Dumas			Versioning is a critical part of delivering software to users. With bazel, you can derive per-build values and inject them anywhere in your build process.	Versioning is a critical part of delivering software to users. With bazel, you can derive per-build values and inject them anywhere in your build process.	false	bazel golang

What am I Doing?

In my last post I spent some time talking about how more rigorous versioning helped reduce wasted time debugging and upgrading code as it started getting broken into lots of little pieces.

That post was pretty light on direct bazel usage but I promise, it'll pay off. Here, we're going to cover how to use these tags in your builds to tag docker images or inject build information into compiled binaries.

I'm assuming that you've read the first bazel post in this series, or that you've already got your bazel + bzlmod setup going.

Stamping and you

Bazel includes functionality that it calls "stamping". Bazel has to separate this into its own conceptual space because one of the core design principles is build reproducibility: for bazel's caching to work, inputs have to be deterministic and ideally change infrequently between runs.

Bazel's documentation covers the bare essentials, with a small caveat. Stamping requires a script , the "workplace status" script, that emits space-separated key-value pairs, e.g. STABLE_KEY_NAME VALUE. An example script is included below.

#! /usr/bin/env bash

set -o errexit
set -o nounset
set -o pipefail

echo "STABLE_STAMP_VERSION $(git describe --tags --dirty=-dev)"
echo "STABLE_STAMP_COMMIT $(git rev-parse HEAD)"
echo "STABLE_STAMP_BRANCH $(git rev-parse --abbrev-ref HEAD)"

One important detail that the documentation doesn't cover is that your workspace status script cannot live in the root of your bazel project. You have two options:

• Place the status script somewhere in your $PATH
• Place the status script in a subdirectory

Still not sure why, but if you simply do bazel --workplace_status_command=status.sh, bazel will only look for it in your $PATH.

Build Injection

Using the variables created by your workspace status script ends up being incredibly simple, if you're using rules_go. the x_defs parameter lets you override values at compile-time, exactly for cases like this.

x_defs = {
       "Version": "{STABLE_STAMP_VERSION}",
       "Build": "{STABLE_STAMP_COMMIT}",
   },

This is equivalent to the Go build flag -ldflags "-X PACKAGENAME.Version=whatever -X PACKAGENAME.BUILD=whatever". It's important to note that the raw Go flags require a fully qualified package name be specified. Bazel is smart enough to derive the necessary package name on its own, all you have to do is tell it which variable needs to be overriden with what value.

Putting it all together

The final, full invocation for stamping your builds should look something like this.

wikilink-obsidian-resolver on  main [⇡] via 🐹 v1.22.2
❯ bazel run --stamp --workspace_status_command=tools/workspace_status.sh //cmd/version
INFO: Analyzed target //cmd/version:version (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
Target //cmd/version:version up-to-date:
dist/bin/cmd/version/version_/version
INFO: Elapsed time: 1.262s, Critical Path: 1.10s
INFO: 2 processes: 1 internal, 1 darwin-sandbox.
INFO: Build completed successfully, 2 total actions
INFO: Running command line: dist/bin/cmd/version/version_/version
Version: v0.1.4-1-g5792d62
Build: 5792d623fc9fc1852aeb09dd008eabb640cb6711

Bazel runs your binary, injects variables generated by your workspace_status script, and it all finally comes together.

The stamping also works for builds:

wikilink-obsidian-resolver on  main [⇡] via 🐹 v1.22.2
❯ bazel build --stamp --workspace_status_command=tools/workspace_status.sh //cmd/version
INFO: Analyzed target //cmd/version:version (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
Target //cmd/version:version up-to-date:
dist/bin/cmd/version/version_/version
INFO: Elapsed time: 0.246s, Critical Path: 0.06s
INFO: 1 process: 1 internal.
INFO: Build completed successfully, 1 total action

wikilink-obsidian-resolver on  main [⇡] via 🐹 v1.22.2
❯ ./dist/bin/cmd/version/version_/version
Version: v0.1.4-1-g5792d62
Build: 5792d623fc9fc1852aeb09dd008eabb640cb6711

What next?

Stamping is not going to accomplish any of my goals on its own, but it was an important part of preparing my toolkit. If I'm going to release software for other people to consume, I need versioning. Injecting a git tag into a Go binary is a trivial proof of concept; I'll be using this to automatically tag and push OCI images and probably other stuff I haven't come up with yet.

Notes, Warnings, Caveats

• Important: the workspace-status-script cannot live in the root of the bazel project. It has to be in a subdirectory for some reason.
• If you're defining x_defs on a rules_go go_library, you cannot fully qualify the variable names.
• To find where bazel places artifacts, use bazel cquery --output=files