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

  1. Build with version. What does it print, and why is a default worth keeping?
  2. Add a Linux 386 target and check its binary with file. Which line of the release grows, and which files appear?
  3. 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.

  1. What does -X main.version=1.0.0 do?

    Answer

    Sets the package-level string at link time

    The linker patches the string.

  2. What does -s -w strip?

    Answer

    The symbol table and the debug information

    The binary gets smaller.

  3. Why keep a plain binary too?

    Answer

    A stripped binary is harder to debug

    Keep the full one in the build archive.

  4. How is a Windows binary built here?

    Answer

    GOOS=windows GOARCH=amd64 go build

    The toolchain has the target.

  5. 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.

  6. What is SHA256SUMS for?

    Answer

    A user checks the download against it

    sha256sum -c verifies it.

  7. Why do the archive hashes change between builds?

    Answer

    gzip stores the time it was made

    The published bytes are what matter.

  8. What does goreleaser automate?

    Answer

    The build, archive, checksum and upload steps

    It is a release runner.

  9. Why is the version in the binary?

    Answer

    A bug report names the exact build

    The user can quote it.

  10. 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