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

  1. Add a build date variable and stamp it from a shell command. Which quoting makes the date with a space survive?
  2. 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?
  3. 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.

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

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

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

  4. What does -s -w remove?

    Answer

    The symbol table and the debug information

    It makes the binary smaller and harder to debug.

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

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

  7. Which value can -X set?

    Answer

    A string variable at package level

    Only strings, and only variables the linker can address.

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

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

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

Banner image