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
- Build the program with -X main.version=dev and read the output. What does -X do to a value the linker does not find?
- 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?
- 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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
What does sha256sum -c SHA256SUMS verify?
Answer
That the files match the recorded hashes
It detects a truncated or altered download.
-
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.
-
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.
-
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.
-
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