Capstone 2: release and cross-builds
The last lesson of capstone 2 takes the command from the module and turns it into files a stranger can download: a version stamped by the linker, a binary per platform, an archive per target and a checksum file. The command already prints its version, so the stamp is the only thing the release adds to the source.
The version variable
version is a package-level string with a default of dev, and the version subcommand prints it with the program name. -X main.version=1.0.0 patches the string at link time; a build without the flag keeps the default, which is what a developer wants.
package main
import (
"flag"
"fmt"
"os"
"time"
"example.com/tasks/tasks"
)
var version = "dev"
go build -o dist/tasks-plain ./cmd/tasks && ./dist/tasks-plain version
tasks dev
go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o dist/tasks-linux-amd64 ./cmd/tasks && ./dist/tasks-linux-amd64 version
tasks 1.0.0
The flag has three parts: -s -w strips the symbol table and the debug data, -X sets the string, and -trimpath keeps the build directory out of the binary. They go in one quoted -ldflags value because the shell splits on spaces, which lesson 58 explained.
Plain and stripped
The plain binary carries the symbol table and the debug information, and the release one is a third smaller. The sizes below are this build on this machine.
stat -c '%n %s bytes' dist/tasks-plain dist/tasks-linux-amd64
dist/tasks-plain 3361374 bytes
dist/tasks-linux-amd64 2248866 bytes
The stripped binary is 1.1 MB smaller and still runs, and it is harder to debug: a stack trace loses the line numbers and a profiler loses the function names. A release keeps the full binary in the build archive for the day a user reports a crash.
Four targets
GOOS and GOARCH select the target and the toolchain carries the runtime and the system interface for each. The command imports only the standard library, so no target needs a cross-compiler.
GOOS=linux GOARCH=arm64 go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o dist/tasks-linux-arm64 ./cmd/tasks
GOOS=windows GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o dist/tasks-windows-amd64.exe ./cmd/tasks
GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o dist/tasks-darwin-arm64 ./cmd/tasks
stat -c '%n %s bytes' dist/tasks-linux-arm64 dist/tasks-windows-amd64.exe dist/tasks-darwin-arm64
dist/tasks-linux-arm64 2228386 bytes
dist/tasks-windows-amd64.exe 2372096 bytes
dist/tasks-darwin-arm64 2196418 bytes
The four sizes are close because the runtime dominates a program this small. A binary built on Linux for Windows is a real PE executable, and the arm64 one runs on a server only with the right CPU. A release that wanted a Linux 386 or a FreeBSD target adds one more line and nothing else.
Archives and checksums
Each binary is packed into a tar archive named after the target, and sha256sum writes one line per file. The checksums are what a user compares after downloading, and the archive keeps the binary and, in a real release, the README and the licence together.
cd dist && tar -czf tasks-linux-amd64.tar.gz tasks-linux-amd64 && tar -czf tasks-linux-arm64.tar.gz tasks-linux-arm64 && tar -czf tasks-windows-amd64.tar.gz tasks-windows-amd64.exe && tar -czf tasks-darwin-arm64.tar.gz tasks-darwin-arm64
stat -c '%n %s bytes' dist/*.tar.gz
dist/tasks-darwin-arm64.tar.gz 928021 bytes
dist/tasks-linux-amd64.tar.gz 990160 bytes
dist/tasks-linux-arm64.tar.gz 898269 bytes
dist/tasks-windows-amd64.tar.gz 1031178 bytes
sha256sum dist/*.tar.gz | tee dist/SHA256SUMS
43f44d8d09d9146afceea6edbc237c058243db9ede1ef0ea9a875f3131243955 dist/tasks-darwin-arm64.tar.gz
357fb4537e6e9bb7064b1a49ec02061192ace477b777b4b8b3d9f7bf57948f4f dist/tasks-linux-amd64.tar.gz
5273b5c0d6478fba4b2c893932296cc4acb543d19bc6e3f880bb216c620b826d dist/tasks-linux-arm64.tar.gz
d5312e99d03c7c9d1384b719403e381acb628233e282ed7111cc805c24fbafd7 dist/tasks-windows-amd64.tar.gz
A gzip archive carries the time it was made, so the hashes are a record of this build and not constants. The release is built once on one machine and published; a user checks the file against SHA256SUMS and a script fails on a mismatch. The command is small enough that the whole release is these six commands and a tag.
goreleaser
goreleaser runs the same build, archive and checksum steps from a configuration file, adds a changelog from the commits since the last tag and uploads the result. The tool is not installed in this container, so the file below is a sketch and its output is not shown here.
version: 2
builds:
- env: [CGO_ENABLED=0]
ldflags: [-s -w -X main.version={{.Version}}]
goos: [linux, darwin, windows]
goarch: [amd64, arm64]
archives:
- formats: [tar.gz]
format_overrides:
- goos: windows
formats: [zip]
checksum:
name_template: SHA256SUMS
The value of the tool is consistency, not the individual commands: the same steps on every tag, a changelog nobody types and a release that is reproducible from the repository. A command that ships twice a year can keep the script above.
A release a stranger can check
Four files make a release usable: the archives, the checksum file, a short README with the version and the platforms, and the source tag the binaries were built from. The version is in the binary, so a bug report names the build; the checksum is next to the download, so a user can prove the bytes; and the tag is the commit, so the source can be rebuilt. The next part is a service with a real deployment, and the last lesson of the course uses the same discipline.
Exercises
- Build with version. What does it print, and why is a default worth keeping?
- Add a Linux 386 target and check its binary with file. Which line of the release grows, and which files appear?
- Change one byte of an archive and run sha256sum -c SHA256SUMS. What does the check print, and why is that the file a user compares?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does -X main.version=1.0.0 do?
Answer
Sets the package-level string at link time
The linker patches the string.
-
What does -s -w strip?
Answer
The symbol table and the debug information
The binary gets smaller.
-
Why keep a plain binary too?
Answer
A stripped binary is harder to debug
Keep the full one in the build archive.
-
How is a Windows binary built here?
Answer
GOOS=windows GOARCH=amd64 go build
The toolchain has the target.
-
Why is the arm64 binary not run here?
Answer
The CPU is amd64 and needs an emulator for it
The build is real, the run needs the target.
-
What is SHA256SUMS for?
Answer
A user checks the download against it
sha256sum -c verifies it.
-
Why do the archive hashes change between builds?
Answer
gzip stores the time it was made
The published bytes are what matter.
-
What does goreleaser automate?
Answer
The build, archive, checksum and upload steps
It is a release runner.
-
Why is the version in the binary?
Answer
A bug report names the exact build
The user can quote it.
-
Which files make a release usable?
Answer
Archives, checksums, a README and the source tag
The tag lets a user rebuild.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev