Building Executables — Specification¶

Focus: Precise reference for the flags, environment, and embedded data that define a Go production binary.

Sources: - go help build, go help buildmode, go help buildflags, go help environment - cmd/link documentation: https://pkg.go.dev/cmd/link - runtime/debug.BuildInfo: https://pkg.go.dev/runtime/debug#BuildInfo - Modules reference: https://go.dev/ref/mod

1. Synopsis¶

go build [build flags] [-o output] [packages]

A production binary is the file cmd/link writes to -o, given a main package and a set of build flags chosen for size, attribution, portability, and reproducibility.

2. Common production flag set¶

CGO_ENABLED=0 \
go build \
  -trimpath \
  -mod=readonly \
  -buildvcs=true \
  -ldflags="-s -w -X main.version=${VERSION}" \
  -o bin/<name>-<version>-<os>-<arch> \
  ./cmd/<name>

3. -ldflags reference¶

Common flags accepted by cmd/link:

Multiple -X flags compose:

-ldflags="-s -w \
  -X 'main.version=${VERSION}' \
  -X 'main.commit=${COMMIT}' \
  -X 'main.buildDate=${DATE}'"

Quoting matters when values contain spaces.

4. -buildmode reference¶

Selection: use exe (default) for typical binaries, pie for hardened server deployments, c-archive/c-shared only when interoperating with non-Go runtimes.

5. Environment variables affecting builds¶

6. runtime/debug.BuildInfo schema¶

type BuildInfo struct {
    GoVersion string         // toolchain version, e.g. "go1.23.4"
    Path      string         // main module's import path
    Main      Module         // info about the main module
    Deps      []*Module      // dependencies
    Settings  []BuildSetting // build flags and VCS info
}

type Module struct {
    Path    string
    Version string
    Sum     string
    Replace *Module
}

type BuildSetting struct {
    Key   string
    Value string
}

Commonly populated Settings keys:

Inspect without running the binary:

go version -m ./api

7. Behavioral guarantees¶

• go build produces a persistent file at -o, in contrast to go run's temporary binary.
• The output binary is self-contained for pure-Go builds (CGO_ENABLED=0); no Go runtime install is needed on the target.
• .gopclntab (PC→function/line) is always embedded, even when -s -w strip the symbol table and DWARF. Panic traces and function-level pprof therefore keep working.
• runtime/debug.BuildInfo is embedded when building via standard go build from a module; reading it requires no allocation, no file I/O.
• The build cache (GOCACHE) is consulted by content hash; identical inputs yield cache hits.
• With -trimpath and -ldflags="-buildid=" plus a pinned toolchain and locked module graph, the resulting bytes are reproducible across machines.
• Signals, stdin/stdout, and exit codes of the built binary at run time are the same as any native executable on the platform; go build does not wrap the binary.

8. Non-goals / limitations¶

• go build does not produce installer packages (.deb, .rpm, .msi, .dmg). Use nfpm, goreleaser, or platform-specific tools.
• It does not sign binaries. Use cosign, codesign+notarytool, or signtool per platform.
• It does not generate SBOMs or SLSA provenance. Use syft and slsa-github-generator separately.
• It does not strip the runtime; even minimal binaries carry the Go runtime (~1–2 MB irreducible).
• -ldflags="-X" only sets string vars. Constants, ints, structs, and unexported variables cannot be set this way.
• -buildmode=plugin is fragile (must match toolchain version exactly between plugin and host) and only works on Linux/macOS. Treat as last-resort.
• go run is not appropriate for producing release binaries — use go build with -o.

9. Related references¶

• go help build, go help buildmode, go help buildflags, go help environment
• cmd/link: https://pkg.go.dev/cmd/link
• runtime/debug: https://pkg.go.dev/runtime/debug
• Modules reference: https://go.dev/ref/mod
• goreleaser: https://goreleaser.com/
• cosign: https://docs.sigstore.dev/
• Distroless images: https://github.com/GoogleContainerTools/distroless
• SLSA: https://slsa.dev/