|
|
---
|
|
|
draft: false
|
|
|
title: "Stamping Builds with Bazel"
|
|
|
aliases: ["Stamping Builds with Bazel"]
|
|
|
series: ["building-with-bazel"]
|
|
|
series_order: 3
|
|
|
date: "2024-05-15"
|
|
|
author: "Nick Dumas"
|
|
|
cover: ""
|
|
|
keywords: ["", ""]
|
|
|
description: "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."
|
|
|
showFullContent: false
|
|
|
tags:
|
|
|
- bazel
|
|
|
- golang
|
|
|
---
|
|
|
|
|
|
## What am I Doing?
|
|
|
In my [last post](/2024/09/the-joy-of-versioning/) 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](/2023/08/beautiful-builds-with-bazel/) 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](https://bazel.build/docs/user-manual#workspace-status) 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.
|
|
|
|
|
|
```bash {title="tools/workspace_status.sh"}
|
|
|
#! /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` |