Compile & Link

go build is a pipeline

go build orchestrates two tools: the compiler (go tool compile), which turns each package’s source into an object file, and the linker (go tool link), which combines all object files — yours, your dependencies’, and the runtime’s — into one executable. The compiler runs per package, in dependency order, and caches results (go build is incremental).

graph LR
S["source .go"] --> P["parse → AST"]
P --> T["type-check"]
T --> I["IR → SSA"]
I --> O["optimize<br/>(inline, escape, etc.)"]
O --> M["machine code<br/>(object file)"]
M --> L["linker"]
R["runtime + deps"] --> L
L --> B["static binary"]

Inside the compiler

For each package the compiler:

1. Lexes and parses the source into an abstract syntax tree (AST).
2. Type-checks — the AST gets types; this is where most of your errors surface.
3. Lowers to an IR and then SSA (static single assignment) — the form where optimizations are easy to express: inlining, escape analysis, dead-store elimination, bounds-check elimination, constant folding.
4. Generates machine code for the target GOARCH, written into an object archive.

Inside the linker

The linker resolves symbols across all objects, performs dead-code elimination (drops everything unreachable from main/init), lays out the final binary, and embeds the runtime and metadata. The result is statically linked by default — no shared Go library to ship.

What’s in the binary

A Go executable is a self-contained bundle:

• your compiled code and every imported package’s code,
• the runtime: the scheduler, garbage collector, and allocator,
• type metadata for reflection and interface dispatch,
• the symbol table and DWARF debug info (strippable),
• embedded files (//go:embed) and build info.

That’s why even “hello world” is a few megabytes — and why deployment is just copy the binary. You can read the embedded build info at runtime:

package main

import (
"fmt"
"runtime"
"runtime/debug"
)

func main() {
fmt.Println("compiler:", runtime.Compiler)
fmt.Println("go version:", runtime.Version())
fmt.Printf("target: %s/%s\n", runtime.GOOS, runtime.GOARCH)

if bi, ok := debug.ReadBuildInfo(); ok {
	fmt.Println("module path:", bi.Path)
	fmt.Println("go directive:", bi.GoVersion)
	fmt.Println("dependencies:", len(bi.Deps))
	// Build settings (e.g. -ldflags, vcs info) live in bi.Settings.
	for _, s := range bi.Settings {
		if s.Key == "GOARCH" || s.Key == "GOOS" || s.Key == "-ldflags" {
			fmt.Printf("  setting %s = %q\n", s.Key, s.Value)
		}
	}
}
}

debug.ReadBuildInfo is how tools like go version -m ./binary show the module graph and VCS stamp baked into any Go binary.

Useful build commands

# Cross-compile: a Linux/arm64 binary from any host, no C toolchain.
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o app .

# Smaller release binary: strip symbol table (-s) and DWARF (-w).
go build -ldflags="-s -w" -o app .

# Stamp a version into a variable at link time.
go build -ldflags="-X main.version=1.4.2" -o app .

# Inspect symbols and sizes.
go tool nm app | head           # symbol table
go version -m app               # module + build settings

# See what the compiler decided (escape/inline), without linking.
go build -gcflags='-m' ./...

Reference

See also

• reading assembly — the machine code this pipeline emits.
• runtime introspection — debug.ReadBuildInfo and runtime config.
• escape analysis — an SSA-stage decision you can inspect with -gcflags=-m.
• the go toolchain (stdlib) — go build, modules, and the wider command set.

Next: reading the machine code the compiler emits — reading assembly.

Related topics