Linker flags and build metadata
A release binary should be able to say which build it is. The linker can fill a string variable at link time with -X importpath.name=value, so the version comes from the build script and the source keeps a sensible default for a local build. The previous lesson reached into memory; this one reaches into the build.
Stamping a version
The two variables are package-level strings with defaults, and the program prints them. A plain build keeps the defaults; a build with -ldflags overwrites both. The flags go through the shell, so the whole string is quoted and each -X is separated by a space: one wrong quote and the linker treats the rest as a file name.
package main
import (
"fmt"
"runtime"
)
var (
version = "dev"
commit = "none"
)
func main() {
fmt.Printf("version %s commit %s\n", version, commit)
fmt.Println("built with", runtime.Version())
}
go build -o app . && ./app
version dev commit none
built with go1.26.10
go build -ldflags "-X main.version=1.2.3 -X main.commit=abc1234" -o app . && ./app
version 1.2.3 commit abc1234
built with go1.26.10
go version -m app
app: go1.26.10
path example.com/app
mod example.com/app (devel)
build -buildmode=exe
build -compiler=gc
build -ldflags="-X main.version=1.2.3 -X main.commit=abc1234"
build CGO_ENABLED=1
build CGO_CFLAGS=
build CGO_CPPFLAGS=
build CGO_CXXFLAGS=
build CGO_LDFLAGS=
build GOARCH=amd64
build GOOS=linux
build GOAMD64=v1
The first run printed the defaults and the second the stamped values. The go version -m output is the build info the toolchain records in every binary: the module path, the Go version, the flags and the dependencies. That record is why a binary can be identified after it left the build machine, even when the version string was not stamped.
Stripping and the size
-s -w removes the symbol table and the DWARF debug information, which makes the binary smaller and takes away the data a debugger and some profilers need. It is the usual flag for a release image and the wrong flag for a binary that will be debugged on a server. The two can be combined with -X in one -ldflags value.
go build -ldflags "-s -w -X main.version=1.2.3" -o app-small . && stat -c 'stripped: %s bytes' app-small
stripped: 1597602 bytes
go build -o app-full . && stat -c 'full: %s bytes' app-full
full: 2410509 bytes
go version -m app-small | head -4
app-small: go1.26.10
path example.com/app
mod example.com/app (devel)
build -buildmode=exe
The stripped binary is smaller and still carries the build info, which lives in its own section and is not removed by -w. That is the combination a release wants: a small binary that can still be identified.
What -X can and cannot do
-X only sets a string variable that the linker can find, at package level and without an initialiser that the compiler folded into a constant. It cannot set an int, a struct or a variable in a function, and it silently does nothing when the name does not match: a typo gives a binary with the default version, which is why a release script checks the output of ./app --version after the build. The import path in the flag is the full path of the package, not just its directory name, unless the variable is in main.
Exercises
- Add a build date variable and stamp it from a shell command. Which quoting makes the date with a space survive?
- Build with a typo in the -X package path and run the binary. What do you see, and how would a release script catch it?
- Compare the output of go version -m for a build inside and outside a git checkout. Which fields appear only when the VCS information is available?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does -X importpath.name=value do?
Answer
Sets a package-level string variable at link time
The linker can only patch a string variable it finds in the binary.
-
Why does the source keep a default value?
Answer
A local build works without the flags
The default is what a plain go build produces.
-
What does go version -m print?
Answer
The module, Go version, build flags and dependencies recorded in the binary
The build info section is written into every binary.
-
What does -s -w remove?
Answer
The symbol table and the debug information
It makes the binary smaller and harder to debug.
-
Why quote the whole -ldflags value?
Answer
The shell splits on spaces, and each -X must reach the linker as one argument
A missing quote turns the second -X into a file name.
-
What happens when the -X name does not exist?
Answer
The linker leaves the default silently
A typo produces a binary with the old version, so the script must check.
-
Which value can -X set?
Answer
A string variable at package level
Only strings, and only variables the linker can address.
-
Why is stripping wrong for a binary that will be debugged?
Answer
The debugger needs the symbols and DWARF data it removes
Keep a full binary for debugging and a stripped one for release.
-
What is the import path in -X?
Answer
The full package path of the variable
main.version works because the package is main; other packages need their full path.
-
Why stamp the commit as well as the version?
Answer
To identify the exact source the binary was built from
A version tag can be rebuilt; a commit hash cannot be guessed.
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