Compiler & Linker Flags — Specification¶

Focus: Precise reference for -gcflags, -ldflags, -asmflags, -gccgoflags, and related toolchain knobs passed via go build.

Sources: - go help build, go help buildflags - cmd/compile: https://pkg.go.dev/cmd/compile - cmd/link: https://pkg.go.dev/cmd/link

1. The flag families¶

Multiple -gcflags/-ldflags can be combined with package patterns.

2. Package patterns¶

go build -gcflags='all=-N -l' ./...                 # all packages
go build -gcflags='main=-N -l' ./...                # only main package
go build -gcflags='example.com/...=-m' ./...        # path pattern
go build -gcflags='runtime=-d=foo' ./...            # a specific package

The <pattern>=<flags> form selects which packages get the flags. Without a pattern, the flags apply to the top-level package being built.

3. Common compile flags¶

Combine: -gcflags='all=-N -l' is the canonical "build for delve debugging".

4. Linker flags¶

go build -ldflags='-s -w -X main.version=1.2.3' ./...

The string injection (-X) only works with declared var of type string. Common pattern:

// main.go
var version = "dev"

func main() { fmt.Println("version:", version) }

go build -ldflags="-X main.version=$(git describe --tags)" ./cmd/app

5. Build modes (-buildmode)¶

c-shared and c-archive are the cgo flip side: Go code called from C.

6. Profile-guided optimization (-pgo)¶

go build -pgo=auto ./cmd/app                          # uses default.pgo if present
go build -pgo=/path/to/profile.pb.gz ./cmd/app        # explicit

The profile is a pprof CPU profile. The compiler uses it to make better inlining and devirtualization decisions. Typical gain: 2–10% CPU.

PGO support is GA in Go 1.21.

7. -trimpath¶

go build -trimpath ./...

Removes file system paths from the resulting binary. Effects:

• Stack traces show package paths instead of /Users/alice/work/proj/....
• Reproducible builds (same source → same binary across machines).
• DWARF and symbol table use canonical paths.

Almost always desirable for release builds; sometimes annoying for local development (worse "click to file" UX in some tools).

8. -race, -msan, -asan¶

go build -race ./...
go build -msan ./...   # memory sanitizer (Linux/amd64 + Linux/arm64)
go build -asan ./...   # address sanitizer

Each instruments the binary differently:

• -race: detects data races at runtime; 2–20× slowdown.
• -msan: detects use of uninitialized memory; requires cgo.
• -asan: detects out-of-bounds and use-after-free; requires cgo.

Test binaries (go test -race) is the common use; production builds are typically race-free.

9. Build cache and flags¶

The Go build cache keys on:

• Source content.
• Build flags (exact -gcflags/-ldflags/-tags/...).
• Toolchain version.
• Target platform.

Implication: changing flags invalidates the cache for affected packages but uses a separate cache entry, so switching back is fast.

10. -x and -work¶

go build -x ./...              # print every command go executes
go build -work -x ./...        # print and keep the work directory

-x shows the underlying compiler/linker invocations. Useful when debugging weird builds or learning how the toolchain assembles a binary.

-work keeps the temporary work directory after build. Combined with -x, you can inspect intermediate artifacts.

11. -buildvcs (Go 1.18+)¶

go build -buildvcs=true ./...    # embed VCS info
go build -buildvcs=false ./...   # don't

Embeds git commit hash, dirty flag, etc. into the binary. Visible via go version -m binary. Default is auto (embed if inside a VCS).

12. go env knobs¶

Some flags are settable via env vars and persist:

go env -w GOFLAGS='-trimpath -ldflags=-s\ -w'

Affects every subsequent go build. Useful for consistent CI defaults; dangerous for shared dev machines where preferences differ.

13. Important flag combinations¶

14. Inspection tools¶

15. Related references¶

• go help build, go help buildflags
• cmd/compile flags: go tool compile -h
• cmd/link flags: go tool link -h
• PGO docs: https://go.dev/doc/pgo