The Linker — Specification¶

A reference card for cmd/link: every flag that matters, the linkmodes and buildmodes, the section list of a Go ELF binary, the deadcode rules, the runtime tables (.gopclntab, buildinfo), and the tooling. Keep this open while building release pipelines.

1. -ldflags reference¶

Flags are passed via go build -ldflags="...". The string is split and handed to cmd/link. Most-used flags:

go build -ldflags vs go tool link: go build is what you normally use; the raw go tool link object.o requires already-compiled objects.

2. Linkmodes (-linkmode)¶

External-link triggers: non-trivial cgo, -buildmode in {c-shared,c-archive,plugin,shared,pie (most platforms)}, explicit -linkmode=external, or -extldflags/-extld.

3. Buildmodes (-buildmode)¶

4. Sections of a Go ELF binary¶

(Listed with readelf -S app; Mach-O/PE have analogues.)

Key: the pointer/no-pointer split (.data vs .noptrdata, .bss vs .noptrbss) lets the GC skip scanning pointer-free regions.

5. Deadcode rules (summary)¶

Implemented in src/cmd/link/internal/ld/deadcode.go.

1. Roots: runtime entry, main.main/main.init, runtime-required symbols, exported symbols (for shared/c-shared builds).
2. A symbol is live iff reachable via relocations from a root.
3. Direct calls keep the callee.
4. Methods are kept when their type is converted to an interface and a reachable call site invokes an interface method of matching name+signature.
5. A method on a type never boxed into an interface and never called directly is dropped.
6. If reflect.Value.Method/MethodByName is reachable, method pruning is disabled — full method sets of reflectable types are retained.
7. Type metadata (names, fields, tags) is kept when reachable via reflection or needed for interface/itab construction.

6. Runtime tables¶

.gopclntab¶

• Generated by pcln.go. Maps PC → function, file:line, stack/GC pointer maps, inlining tree.
• Used by: panic unwinding, runtime.Callers/Caller/FuncForPC, GC stack scanning, profilers.
• Survives -s -w (runtime needs it).

.go.buildinfo¶

• Module path, main version, dependency versions, build settings, VCS info.
• Read with go version -m <binary> or debug/buildinfo.ReadFile.
• VCS stamping (vcs.revision, vcs.time, vcs.modified) added automatically since Go 1.18 when building from a clean VCS checkout (toggle with -buildvcs).

7. Tooling reference¶

8. Quick recipes¶

# Release: stripped, trimmed, version-stamped
go build -trimpath -ldflags="-s -w -X main.version=$(git describe --tags)" -o app ./cmd/app

# Reproducible (byte-identical)
go build -trimpath -ldflags="-s -w -buildid=" -o app ./cmd/app

# Static with cgo
CGO_ENABLED=1 go build -ldflags='-linkmode=external -extldflags=-static' -o app ./cmd/app

# Inspect
go version -m app
go tool nm -size -sort size app | tail -20
readelf -S app | grep -E 'gopclntab|buildinfo|debug'

Further reading¶

• cmd/link command docs (all flags)
• go help buildmode / build modes
• deadcode.go source
• debug/buildinfo
• go tool nm