The Go build system encompasses the infrastructure that transforms Go source code into executable binaries, manages dependencies through the module system, and coordinates testing. This system is primarily implemented in the go command located in src/cmd/go/ and its internal packages, as well as the dist tool in src/cmd/dist/ used for bootstrapping the toolchain.
For details about the Go compiler and its optimization passes, see Go Compiler. For information about the runtime system that executes compiled programs, see Go Runtime.
The build system consists of several interconnected subsystems:
go command entry point that routes to specific subcommands via the base.Command structure src/cmd/go/internal/work/build.go29load.Package struct src/cmd/go/internal/load/pkg.go58-61go.mod and go.work files src/cmd/go/internal/modload/init.go264-272work.Action src/cmd/go/internal/work/exec.go5-7Builder.Do execution loop src/cmd/go/internal/work/exec.go76-258dist tool handles initial toolchain construction, moving from a bootstrap Go compiler to the current source src/cmd/dist/buildtool.go134-154The following diagram bridges the user-facing command space to the internal code entities that handle the build process.
Diagram: Build Command to Code Entity Mapping
Sources: src/cmd/go/internal/work/build.go29-32 src/cmd/go/internal/load/pkg.go58-61 src/cmd/go/internal/work/exec.go76-135 src/cmd/go/internal/work/gc.go56-65
The go command is the primary tool for managing Go source code src/cmd/go/alldocs.go8 Each subcommand, such as build, test, or list, is defined as a base.Command src/cmd/go/internal/work/build.go29
Major commands include:
go build: Compiles packages and dependencies src/cmd/go/internal/work/build.go29go test: Automates testing of packages src/cmd/go/internal/test/test.go49go list: Lists packages or modules src/cmd/go/internal/list/list.go37go mod: Module maintenance src/cmd/go/alldocs.go27For details, see The Go Command.
Package loading resolves patterns to load.Package instances src/cmd/go/internal/load/pkg.go58 This struct contains all metadata required for a build, including source files (GoFiles, CgoFiles, SFiles) src/cmd/go/internal/load/pkg.go98-109 and recursive dependency information (Imports, Deps) src/cmd/go/internal/load/pkg.go127-129 The build system enforces strict dependency rules to prevent cycles and unauthorized imports src/go/build/deps_test.go38-70
For details, see Module System and Package Loading.
The build process is modeled as a DAG of work.Action nodes. The work.Builder coordinates execution via Builder.Do src/cmd/go/internal/work/exec.go76
Diagram: Action Graph Execution Logic
Sources: src/cmd/go/internal/work/exec.go123-160 src/cmd/go/internal/work/gc.go35-54
The Builder.Do method uses worker goroutines limited by cfg.BuildP src/cmd/go/internal/work/exec.go223-230 to process actions. Each build action computes a buildActionID src/cmd/go/internal/work/exec.go264 to determine staleness and cache eligibility.
The go test command orchestrates testing by compiling test binaries that include *_test.go files src/cmd/go/internal/test/test.go64-73 It also manages result caching to avoid redundant runs src/cmd/go/internal/test/test.go120-131 Higher-level orchestration for the Go repository itself is handled by cmd/dist test src/cmd/dist/test.go27-56
For details, see Testing Infrastructure.
The Go linker (cmd/link) combines object files into executables. Within the build system, the gcToolchain src/cmd/go/internal/work/gc.go35 provides the interface to invoke the linker via base.Tool("link") src/cmd/go/internal/work/gc.go42 The build system passes ldflags and buildmode settings to the linker src/cmd/go/internal/work/build.go148-150
For details, see Linker.