Build System Organization

The build system is primarily implemented in the src/cmd/go/ and src/cmd/dist/ directories:

Sources: src/cmd/go/internal/work/exec.go1-120 src/cmd/go/internal/test/test.go1-100 src/cmd/go/internal/load/pkg.go1-100 src/cmd/go/internal/help/helpdoc.go1-100 src/cmd/go/alldocs.go1-100 src/cmd/dist/build.go1-100 src/cmd/dist/test.go1-100

Build System Files

The repository contains several files that control the build process:

File	Location	Purpose
go.mod	src/go.mod1-14	Defines the std module and its dependencies
go.sum	src/go.sum1-9	Checksums for std module dependencies
go.mod	src/cmd/go.mod1-22	Defines the cmd module and its dependencies
go.sum	src/cmd/go.sum1-29	Checksums for cmd module dependencies
modules.txt	src/vendor/modules.txt1-27	Lists vendored packages for std
modules.txt	src/cmd/vendor/modules.txt1-141	Lists vendored packages for cmd
VERSION	Repository root	Version string for releases (e.g., go1.25.0)

The build system is primarily implemented in src/cmd/dist/build.go1-280 for bootstrapping and src/cmd/go/internal/work/exec.go1-253 for regular builds.

Sources: src/go.mod1-14 src/go.sum1-9 src/cmd/go.mod1-22 src/cmd/go.sum1-29 src/vendor/modules.txt1-27 src/cmd/vendor/modules.txt1-141 src/cmd/dist/build.go1-280 src/cmd/go/internal/work/exec.go1-253

Repository Structure

Relevant source files

• .gitignore
• doc/go_mem.html
• doc/go_spec.html
• src/builtin/builtin.go
• src/cmd/compile/default.pgo
• src/cmd/compile/profile.sh
• src/cmd/dist/build.go
• src/cmd/dist/buildgo.go
• src/cmd/dist/buildtool.go
• src/cmd/dist/main.go
• src/cmd/dist/sys_windows.go
• src/cmd/dist/test.go
• src/cmd/dist/testjson.go
• src/cmd/dist/testjson_test.go
• src/cmd/dist/util.go
• src/cmd/go/internal/work/init.go
• src/cmd/internal/objabi/pkgspecial.go
• src/cmd/link/internal/ld/config.go
• src/cmd/pprof/doc.go
• src/encoding/gob/doc.go
• src/go/build/deps_test.go
• src/internal/coverage/pkid.go
• src/internal/goexperiment/exp_goroutineleakprofile_off.go
• src/internal/goexperiment/exp_goroutineleakprofile_on.go
• src/internal/platform/supported.go
• src/internal/platform/zosarch.go
• src/internal/platform/zosarch_test.go
• src/internal/types/testdata/fixedbugs/issue75883.go
• src/internal/types/testdata/fixedbugs/issue75885.go
• src/math/big/float_test.go
• src/net/http/cgi/child.go
• src/net/http/cgi/child_test.go
• src/net/http/cgi/host.go
• src/net/http/doc.go
• src/net/http/fcgi/child.go
• src/net/http/httptrace/trace.go
• src/net/http/pprof/pprof.go
• src/runtime/goroutineleakprofile_test.go
• src/runtime/memclr_arm.s
• src/runtime/panicnil_test.go
• src/runtime/testdata/testgoroutineleakprofile/goker/README.md
• src/runtime/testdata/testgoroutineleakprofile/goker/cockroach1055.go
• src/runtime/testdata/testgoroutineleakprofile/goker/moby27782.go

The Go repository ($GOROOT) is organized into distinct directories that separate source code, documentation, tests, and build outputs. This page describes the physical layout of the repository and how directories map to the major systems described elsewhere in this wiki.

Overview

The repository root ($GOROOT) is structured around several key principles:

1. Source Separation: All source code resides in src/, organized by module and package
2. Two-Module Design: The std module (standard library) and cmd module (toolchain) are separate with distinct dependencies
3. Build Artifacts: Generated outputs go to bin/ (binaries) and pkg/ (compiled packages, build cache)
4. Documentation: Language specs, API definitions, and documentation in doc/ and api/
5. Testing: Conformance tests in test/, plus per-package tests in src/

Top-Level Directory Structure

Directory	Purpose	Typical Contents
src/	All Go source code	Two Go modules with packages and commands
doc/	Language and API documentation	go_spec.html, go_mem.html, release notes
api/	API compatibility tracking	go1.txt, go1.1.txt, ..., next/ (proposed for next release)
test/	End-to-end conformance tests	fixedbugs/, codegen/, typeparam/ directories
misc/	Miscellaneous tools and scripts	cgo/, chrome/, wasm/ helpers
lib/	Runtime data files	time/zoneinfo.zip (embedded timezone database)
bin/	Compiled binaries (generated)	go, gofmt, compile, link, etc.
pkg/	Build artifacts (generated)	tool/, object files, build cache

Generated Directories

The bin/ and pkg/ directories are created during the build process:

• bin/: Contains executable binaries for the toolchain (go, gofmt, etc.)
• pkg/tool/$GOOS_$GOARCH/: Contains toolchain binaries used by go command (compile, link, asm, etc.)
• pkg/obj/: Temporary build objects and bootstrap artifacts (cleaned after build)

Sources: src/cmd/dist/build.go531-611 src/go.mod1-14 src/cmd/go.mod1-22

Source Directory Layout (src/)

The src/ directory contains all Go source code and is structured as two independent Go modules:

Key Source Subdirectories:

Path	Module	Description	Key Files
src/runtime/	std	Runtime system implementation	proc.go, mgc.go, malloc.go
src/net/	std	Networking packages	net/http/server.go, net/dial.go
src/internal/	std	Internal shared packages	internal/abi/, internal/cpu/
src/vendor/	std	Vendored std dependencies	Minimal: x/crypto, x/net
src/cmd/	cmd	Toolchain root directory	Contains separate go.mod
src/cmd/go/	cmd	Build system and package management	internal/work/exec.go
src/cmd/compile/	cmd	Go compiler	internal/ssa/compile.go
src/cmd/link/	cmd	Go linker	internal/ld/lib.go
src/cmd/dist/	cmd	Bootstrap build tool	build.go, test.go
src/cmd/vendor/	cmd	Vendored cmd dependencies	Extensive: x/tools, pprof

Sources: src/go.mod1-14 src/cmd/go.mod1-22 src/runtime/proc.go1-50 src/cmd/go/internal/work/exec.go1-50 src/cmd/compile/internal/ssa/compile.go1-50 src/cmd/dist/build.go1-50

Two-Module Architecture

The repository employs a two-module design where the standard library (std) and toolchain (cmd) are independent Go modules with separate dependency management.

Module Comparison

Aspect	std Module	cmd Module
Module Path	std	cmd
Location	src/go.mod1-14	src/cmd/go.mod1-22
Go Version	Declares current version (e.g., go 1.25)	Same as std
Contains	Runtime, standard library, internal packages	Compiler, linker, go command, tools
Dependencies	Minimal external (x/crypto, x/net)	Extensive (x/tools, pprof, telemetry)
Vendor Dir	src/vendor/ (~8 packages)	src/cmd/vendor/ (~100+ packages)
Update Policy	Conservative, stability-focused	Frequent, feature-focused
Builds When	Standard library changes	Toolchain changes

Why Two Modules?

1. Dependency Isolation: Standard library avoids heavy toolchain dependencies (static analysis, profiling tools)
2. Build Performance: Changes to toolchain don't require rebuilding standard library
3. Independent Evolution: Toolchain can adopt new analysis tools without affecting std stability
4. Clear Boundaries: Explicit separation between runtime/stdlib and development tools

Sources: src/go.mod1-14 src/cmd/go.mod1-22 src/vendor/modules.txt1-27 src/cmd/vendor/modules.txt1-141 src/go.sum1-9 src/cmd/go.sum1-29

Mapping Directories to Systems

This section maps physical directories to the logical systems described in other wiki pages.

Runtime System (src/runtime/)

The runtime directory contains the core runtime implementation with files organized by subsystem:

File	Subsystem	Key Symbols
proc.go	Scheduler	schedule(), findRunnable(), execute(), newproc()
runtime2.go	Data structures	type g, type m, type p, type schedt
malloc.go	Allocator	mallocgc(), newobject()
mheap.go	Heap manager	type mheap, alloc(), allocSpan()
mcache.go	Per-P cache	type mcache
mcentral.go	Central lists	type mcentral, cacheSpan()
mgc.go	GC controller	gcStart(), gcController, gcSetTriggerRatio()
mgcmark.go	GC marking	gcDrain(), scanobject(), markroot()
mgcsweep.go	GC sweeping	sweepone(), sweep()

Sources: src/runtime/proc.go1-332 src/runtime/runtime2.go401-498 src/runtime/malloc.go842-931 src/runtime/mheap.go1-100 src/runtime/mgc.go1-100 src/runtime/mgcmark.go1-100

Compiler (src/cmd/compile/)

The compiler is organized into pipeline stages from parsing to code generation:

Directory	Pipeline Stage	Key Symbols
internal/noder/	Parsing	LoadPackages(), unified.go (unified IR)
internal/types2/	Type checking	(*Checker).checkFiles(), exprInternal()
internal/ir/	IR construction	type Func, type Node, NewFunc()
internal/ssagen/	SSA generation	buildssa(), state.stmt(), state.expr()
internal/ssa/	SSA optimization	Compile(), opt(), lower()
internal/ssa/	Optimization passes	prove.go, cse.go, deadcode.go
internal/ssa/	Arch lowering	rewriteAMD64.go, rewriteARM64.go
internal/ssa/gen/	Opcode definitions	AMD64Ops.go, ARM64Ops.go

Sources: src/cmd/compile/main.go1-50 src/cmd/compile/internal/noder/noder.go1-50 src/cmd/compile/internal/types2/check.go1-50 src/cmd/compile/internal/ir/node.go1-50 src/cmd/compile/internal/ssagen/ssa.go1-100 src/cmd/compile/internal/ssa/compile.go1-100 src/cmd/compile/internal/ssa/prove.go1-50

Build System (src/cmd/go/ and src/cmd/dist/)

The build system has two parts: dist for bootstrapping and go for regular builds:

Component	Directory	Key Symbols
Bootstrap	cmd/dist/	cmdbootstrap(), xinit(), bootstrapBuildTools()
Test orchestration	cmd/dist/	cmdtest(), registerTests()
Build execution	cmd/go/internal/work/	(*Builder).Do(), buildActionID()
Action graph	cmd/go/internal/work/	type Action, (*Builder).buildActionID()
Package loading	cmd/go/internal/load/	LoadPackages(), type Package
Test runner	cmd/go/internal/test/	runTest(), builderRunTest()
Module loading	cmd/go/internal/modload/	LoadModGraph(), LoadPackages()

Sources: src/cmd/dist/build.go109-279 src/cmd/dist/test.go27-84 src/cmd/dist/buildtool.go1-50 src/cmd/go/main.go1-50 src/cmd/go/internal/work/exec.go72-253 src/cmd/go/internal/work/action.go38-87 src/cmd/go/internal/load/pkg.go57-195 src/cmd/go/internal/test/test.go1-100

Standard Library Examples

Key standard library packages are organized functionally:

Package	Key Files	Main Symbols
net/http	server.go, transport.go	type Server, type Transport, ListenAndServe()
net	dial.go, sock.go	Dial(), socket(), type Conn
archive/zip	reader.go, writer.go	type Reader, type Writer, OpenReader()
encoding/json	encode.go, decode.go	Marshal(), Unmarshal(), type Encoder

Sources: src/net/http/server.go1-100 src/net/http/transport.go1-100 src/net/dial.go1-50 src/archive/zip/reader.go1-50 src/encoding/json/encode.go1-50

Internal Packages

The src/internal/ directory contains packages shared across the standard library but not importable by external code. These packages provide core functionality used by multiple standard library packages:

Internal Package Organization

Package	Purpose	Key Types/Functions	Used By
internal/abi	ABI definitions	FuncID, RegArgs, calling conventions	Runtime, compiler, linker
internal/runtime/sys	Architecture info	ArchFamily, Bswap32()	Runtime
internal/cpu	CPU feature detection	X86, ARM64, Initialize()	Runtime, crypto/aes, crypto/sha256
internal/goarch	Architecture constants	GOARCH, PtrSize, Is64bit	Runtime, compiler
internal/goos	OS constants	GOOS, IsWindows, IsLinux	Runtime, os package
internal/bytealg	Optimized byte operations	IndexByteString(), Compare()	strings, bytes
internal/coverage	Coverage instrumentation	CoverageMetaFileWriter	cmd/cover, testing
internal/trace	Runtime tracing	NewTask(), Log()	runtime/trace
internal/poll	I/O polling	FD, network polling	net, os
internal/fmtsort	Map sorting for fmt	Sort()	fmt package
internal/reflectlite	Minimal reflection	Reduced reflection API	encoding/json

Internal Package Dependency Example

Sources: src/internal/abi/abi.go1-50 src/internal/cpu/cpu.go1-50 src/internal/bytealg/bytealg.go1-30 src/internal/poll/fd.go1-50 src/internal/coverage/ src/runtime/proc.go7-18

Module Dependencies

Standard Library Module (std)

The standard library module has minimal external dependencies:

Module Attribute	Value
Module Path	std
Go Version	1.25
Location	src/go.mod1-14
External Dependencies	golang.org/x/crypto, golang.org/x/net

Vendored Dependencies for Standard Library:

• golang.org/x/crypto - ChaCha20, Poly1305, cryptobyte for crypto/ packages
• golang.org/x/net - HTTP/2 HPACK, DNS message parsing, HTTP proxy support
• golang.org/x/sys - CPU feature detection
• golang.org/x/text - Unicode normalization for net/http internationalization

All external dependencies are vendored in src/vendor/ to ensure reproducible builds.

Sources: src/go.mod1-14 src/go.sum1-9 src/vendor/modules.txt1-27

Command Module (cmd)

The toolchain module has extensive dependencies for development tools:

Module Attribute	Value
Module Path	cmd
Go Version	1.25
Location	src/cmd/go.mod1-22

Major Toolchain Dependencies:

• golang.org/x/tools - Static analysis framework, AST inspection
• github.com/google/pprof - Performance profiling and visualization
• golang.org/x/telemetry - Usage analytics collection
• golang.org/x/arch - Architecture-specific assembler support
• golang.org/x/mod - Module version handling

All dependencies are vendored in src/cmd/vendor/ for build reproducibility.

Sources: src/cmd/go.mod5-15 src/cmd/go.sum1-29 src/cmd/vendor/modules.txt1-141

Package Dependency Hierarchy

The Go standard library enforces a strict package dependency hierarchy to ensure clean architecture and prevent circular dependencies. This hierarchy is tested in src/go/build/deps_test.go through the depsRules variable.

Core Dependency Layers

Standard Library Dependency Hierarchy

Package Organization Rules

The dependency hierarchy enforces these critical constraints defined in src/go/build/deps_test.go38-798:

Package Group	Definition	Can Import	Cannot Import
NONE	unsafe, internal/cpu, internal/abi	Nothing	Anything
RUNTIME	runtime, sync, errors, internal/runtime/*	NONE packages	fmt, reflect, net, io
SYSCALL	syscall, internal/syscall/*	RUNTIME, unicode/utf8	io, os, external packages
TIME	time, context	RUNTIME, SYSCALL	fmt, net
STR	strings, bytes, strconv, unicode	TIME, MATH	fmt, os, io
IO	io, bufio	STR, SORT	fmt, net
FMT	fmt, log	OS, reflect	None (top layer for basic I/O)
NET	net, net/http	FMT, crypto (with restrictions)	log, regexp (in core)

Why These Rules Matter:

1. Runtime Independence: The runtime cannot import packages that might need the runtime itself (preventing initialization cycles)
2. Syscall Purity: syscall must remain independent of higher-level I/O to serve as foundation
3. Formatting Late: fmt comes after I/O primitives to support formatted output
4. Network on Top: net is high-level and can use most packages except those that create cycles

Example Violation That Would Break:

• If runtime imported fmt: Circular dependency since fmt needs reflect which needs runtime
• If syscall imported os: Would create cycle since os is built on syscall

Sources: src/go/build/deps_test.go38-798 src/runtime/proc.go1-50 src/runtime/malloc.go1-50 src/syscall/syscall.go1-30

Vendored Dependencies

Both modules use vendoring to ensure reproducible builds by including exact copies of dependencies:

Standard Library Vendoring

Located at src/vendor/, containing minimal external dependencies focused on cryptography and networking:

Package Usage in Standard Library:

• crypto/internal/ packages use vendored cryptographic primitives
• net/http uses vendored HTTP/2 support and internationalization
• net package uses vendored DNS message parsing

Sources: src/vendor/modules.txt1-27 src/net/http/h2_bundle.go1-30

Toolchain Vendoring

Located at src/cmd/vendor/, containing extensive development and analysis infrastructure:

Static Analysis Framework:

Key Toolchain Dependencies:

• cmd/vet uses analysis passes from golang.org/x/tools/go/analysis/passes/*
• cmd/compile uses architecture-specific assemblers from golang.org/x/arch/*
• cmd/go uses telemetry counters for usage analytics
• cmd/pprof uses github.com/google/pprof for performance analysis

Sources: src/cmd/vendor/modules.txt76-141 src/cmd/vendor/golang.org/x/tools/go/analysis/passes/printf/printf.go1-50 src/cmd/vendor/golang.org/x/tools/internal/analysisinternal/analysis.go1-30

Bootstrap and Build Process

The Go toolchain is self-hosting, built using its own compiler. The bootstrap process is managed by cmd/dist:

Bootstrap Process Steps:

Stage	Description	Implementation
1. dist	Build cmd/dist with bootstrap Go	src/cmd/dist/main.go1-50
2. toolchain1	Build compiler/linker with bootstrap Go	src/cmd/dist/buildtool.go133-272
3. Standard library 1	Compile standard library with toolchain1	src/cmd/dist/build.go680-798
4. toolchain2	Rebuild compiler with toolchain1	src/cmd/dist/build.go1257-1409
5. Standard library 2	Recompile stdlib with toolchain2	src/cmd/dist/build.go680-798
6. toolchain3	Final compiler rebuild (for convergence)	src/cmd/dist/build.go1257-1409
7. Final stdlib	Final standard library	src/cmd/dist/build.go680-798

Key Bootstrap Functions:

• cmdbootstrap() in src/cmd/dist/build.go1051-1230 - Main bootstrap orchestration
• bootstrapBuildTools() in src/cmd/dist/buildtool.go133-272 - Builds toolchain1
• xinit() in src/cmd/dist/build.go109-279 - Initializes build environment
• setup() in src/cmd/dist/build.go530-611 - Creates directory structure

The three-stage build ensures the compiler can compile itself correctly and converges to a stable output.

Sources: src/cmd/dist/build.go109-279 src/cmd/dist/build.go530-611 src/cmd/dist/build.go680-798 src/cmd/dist/build.go1051-1230 src/cmd/dist/build.go1257-1409 src/cmd/dist/buildtool.go133-272

Standard Library Organization

The standard library packages are organized functionally under src/:

Major Standard Library Categories

Key Package Locations

Package Category	Import Path	Main Files	Purpose
HTTP Server	net/http	src/net/http/server.go	Server, Handler, ServeMux
HTTP Client	net/http	src/net/http/transport.go	Transport, RoundTripper, connection pooling
ZIP Archives	archive/zip	src/archive/zip/reader.go	ZIP file reading/writing
TAR Archives	archive/tar	src/archive/tar/common.go	TAR file handling
JSON	encoding/json	src/encoding/json/	JSON encoding/decoding
TLS	crypto/tls	src/crypto/tls/	TLS 1.2/1.3 implementation

Sources: src/net/http/server.go1-100 src/net/http/transport.go1-100 src/net/http/serve_test.go1-100 src/net/http/transport_test.go1-100

Toolchain Commands (src/cmd/)

Each command in the Go toolchain has its own directory under src/cmd/:

Key Commands

Command	Directory	Purpose	Main Entry Point
go	cmd/go/	Build, test, install packages	src/cmd/go/main.go1-50
compile	cmd/compile/	Compile Go source to object files	src/cmd/compile/main.go1-50
link	cmd/link/	Link object files into executables	src/cmd/link/main.go1-50
asm	cmd/asm/	Assemble .s files	src/cmd/asm/main.go1-50
dist	cmd/dist/	Bootstrap and test orchestration	src/cmd/dist/main.go1-50
vet	cmd/vet/	Static analysis of Go code	src/cmd/vet/main.go1-50
pprof	cmd/pprof/	Profiling data analysis	src/cmd/pprof/
gofmt	cmd/gofmt/	Format Go source code	src/cmd/gofmt/gofmt.go1-50

cmd/go Internal Organization

The go command has the most complex internal structure:

Important cmd/go Packages:

Package Path	Purpose	Key Types/Functions
internal/work/	Build action execution	(*Builder).Do(), type Action
internal/load/	Package loading	LoadPackages(), type Package
internal/modload/	Module dependency resolution	LoadModGraph(), Init()
internal/test/	Test execution	runTest(), (*Builder).test()
internal/cache/	Build cache management	Default(), Get(), Put()

Sources: src/cmd/go/main.go1-50 src/cmd/go/internal/work/exec.go72-253 src/cmd/go/internal/work/build.go1-100 src/cmd/go/internal/work/action.go38-87 src/cmd/go/internal/load/pkg.go57-195 src/cmd/go/internal/modload/init.go1-50 src/cmd/go/internal/modload/load.go1-100 src/cmd/go/internal/test/test.go1-100 src/cmd/compile/main.go1-50 src/cmd/link/main.go1-50 src/cmd/dist/main.go1-50

Module Dependency Management

Version Pinning

Both modules use exact version pinning in their go.sum files to ensure reproducible builds:

Standard Library Stability:

• Minimal external dependencies
• Cryptography and networking focused
• Conservative version updates

Toolchain Flexibility:

• Extensive analysis tooling
• Regular updates for development features
• Telemetry and profiling integration

Vendoring Strategy

The repository employs comprehensive vendoring to eliminate external network dependencies during builds:

1. Source Control: All dependencies stored in repository
2. Build Isolation: No network access required for builds
3. Version Consistency: Exact dependency versions across environments
4. Security: Auditable dependency code within repository

Sources: src/cmd/vendor/modules.txt1-141 src/vendor/modules.txt1-27 src/cmd/go.sum1-29 src/go.sum1-9