Releasing a Go program

A release is a version a user can quote, a binary per platform, and a checksum that proves the download arrived intact. Go makes the last two cheap: one source cross-compiles to any target without a toolchain for it, and the linker stamps the version into the binary. This lesson takes the module from the previous lesson and turns it into files a stranger can download.

The program and its version

The version is a package-level string with a local default, so a build from a checkout says dev and a release build says the tag. The program prints it together with the platform and the toolchain, which is what a bug report needs. The linker flags lesson explained -X; here it is part of a build command.

package main import ( "fmt" "runtime" ) var version = "dev" func main() { fmt.Printf("notes %s (%s/%s, %s)\n", version, runtime.GOOS, runtime.GOARCH, runtime.Version()) }

go build -o plain . && ./plain && stat -c 'plain: %s bytes' plain

notes dev (linux/amd64, go1.26.10)
plain: 2409824 bytes

go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o notes . && ./notes && stat -c 'stripped: %s bytes' notes

notes 1.0.0 (linux/amd64, go1.26.10)
stripped: 1593506 bytes

The release build is a third smaller and prints the version, platform and toolchain of the machine it was built on. -trimpath removes the build directory from the binary, which keeps a path on your laptop out of a public download and makes two builds from the same source more likely to match byte for byte.

One source, four targets

GOOS and GOARCH select the target, and the toolchain carries the runtime and the system interface for every pair in go tool dist list, which printed 47 combinations in this image. The four builds below cover a desktop Linux, a server on ARM and the two laptop systems; each is one command with no cross-compiler to install.

GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o dist/notes-linux-amd64 .
GOOS=linux GOARCH=arm64 go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o dist/notes-linux-arm64 .
GOOS=windows GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o dist/notes-windows-amd64.exe .
GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o dist/notes-darwin-arm64 .
stat -c '%n %s bytes' dist/notes-*

dist/notes-darwin-arm64 1657890 bytes
dist/notes-linux-amd64 1593506 bytes
dist/notes-linux-arm64 1573026 bytes
dist/notes-windows-amd64.exe 1677824 bytes

The sizes are close because the program is small and the runtime dominates. file names the result: the Linux binary is a statically linked ELF that needs no libc, and the Windows one is a PE executable. A package that imports "C" gives that up: cgo needs a C compiler for the target, and a cross-build of it is a separate project rather than one environment variable.

Archives and checksums

People download archives, not bare binaries, because an archive keeps the name, the licence and the README together. The tar command below packs each binary under the name it already has, and sha256sum writes one line per file; that file is what a user compares after downloading.

cd dist && tar -czf notes-linux-amd64.tar.gz notes-linux-amd64 && tar -czf notes-linux-arm64.tar.gz notes-linux-arm64 && tar -czf notes-windows-amd64.tar.gz notes-windows-amd64.exe && tar -czf notes-darwin-arm64.tar.gz notes-darwin-arm64

stat -c '%n %s bytes' *.tar.gz

notes-darwin-arm64.tar.gz 707314 bytes
notes-linux-amd64.tar.gz 713877 bytes
notes-linux-arm64.tar.gz 651377 bytes
notes-windows-amd64.tar.gz 741814 bytes

sha256sum *.tar.gz | tee SHA256SUMS

e7e24b81540777c3add5c6196348790f9c737af484b17d3a31af68ab505a59c8 notes-darwin-arm64.tar.gz
2332df1eaf217aaed3243088e0da990a9a4e866c26af3928541f499f45b705ff notes-linux-amd64.tar.gz
12bdce5383f20c33a7944e6fe84799997c1f1bde647f382ab2e23c27d35923cf notes-linux-arm64.tar.gz
ba5aba5942724767ecdae6fe24280bcc7a5d94392a27e1a50420f2c56393eda6 notes-windows-amd64.tar.gz

A gzip archive carries the time it was made, so two runs over identical binaries produce different hashes and the file above is a record of this run rather than a constant. That is why a release is built once on one machine and uploaded, not rebuilt by every user: the checksum is only meaningful for the bytes that were published. The release notes carry the version, the four archive names and the checksum file.

goreleaser and what it automates

goreleaser runs the same build, archive and checksum steps from a configuration file, adds the changelog from the commits since the last tag, and uploads the result to a release. Its configuration repeats the commands above with the targets as a matrix, and a hook injects the version from the git tag. The tool is not installed in this container, so the file below is a configuration 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: - format: tar.gz format_overrides: - goos: windows format: zip checksum: name_template: SHA256SUMS

The value is not the tool but the consistency: the same steps on every tag, a changelog nobody types, and a release that is reproducible from the repository. A project that ships once a year can keep the shell script; a project that tags every week should not.

Exercises

  1. Build the program with -X main.version=dev and read the output. What does -X do to a value the linker does not find?
  2. Cross-build for linux/arm64 and run file on the result. How does the output differ from the amd64 binary, and why does it still run on this machine only with an emulator?
  3. Check one archive against the checksum file with sha256sum -c SHA256SUMS after renaming it. What exactly does the failure line name?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does a plain go build print for the version variable?

    Answer

    The local default, here dev

    Without -X the linker leaves the value the source declares.

  2. What does -trimpath remove?

    Answer

    The build directory path from the binary

    It keeps a path on the build machine out of a public download.

  3. How is a Windows binary built on Linux?

    Answer

    GOOS=windows GOARCH=amd64 go build

    The toolchain carries every target in go tool dist list.

  4. What breaks a cross-build of a cgo package?

    Answer

    It needs a C compiler for the target platform

    That is why release builds often set CGO_ENABLED=0.

  5. Why publish archives rather than bare binaries?

    Answer

    Archives keep the binary, the licence and the README together

    A download is a bundle of files, not one executable.

  6. What does sha256sum -c SHA256SUMS verify?

    Answer

    That the files match the recorded hashes

    It detects a truncated or altered download.

  7. Why can the same binaries produce a different archive hash on a second run?

    Answer

    gzip stores the time it was made

    The archive bytes include the timestamp.

  8. What does goreleaser add to the commands above?

    Answer

    The same steps on every tag, a changelog and the upload

    It automates the release procedure rather than the build.

  9. Which toolchain value does the program print besides the version?

    Answer

    The GOOS, GOARCH and the Go version

    runtime reports the platform it was built for.

  10. What is shown for goreleaser on this page?

    Answer

    A configuration sketch, not run here

    The tool is not installed in the image, and the page says so.

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