Build and Install

Purpose and Scope

This page explains the developer workflow behind building and installing Go programs and connects that workflow to the toolchain components present in this repository. In everyday use, the two most important commands are go build, which compiles packages and dependencies without installing the result, and go install, which compiles and places installable outputs where they can be run from a shell path. The distinction matters because go build is usually used for local iteration, while go install is used when the executable should become a reusable command.

The Go repository itself is both the source of the public language distribution and the implementation home for the commands that participate in builds. The repository README identifies Go as an open source programming language for building simple, reliable, and efficient software, points readers to official binary distributions, and directs source-install users to the source installation instructions. That framing is important: most users start from a downloaded distribution, but the build behavior they use is implemented by tools built from this same source tree. Sources: README.md

A Go build starts with packages. A package is a directory of Go source compiled as a unit, and a command package is a package named main that can produce an executable. When you invoke go build in a command package directory, the go command compiles the package and its dependencies and writes a binary in the working directory. When you invoke go install, the command performs the same compilation work but installs the resulting executable into the configured Go install target, commonly the directory reported by go list -f '{{.Target}}'.

Relevant Source Files

• README.md - Establishes the Go repository as the canonical source for the language implementation, points to official binary downloads, and distinguishes binary distribution installation from source installation.
• src/cmd/compile/internal/gc/main.go - Shows the compiler entry point that parses flags and Go source files, type-checks packages, compiles functions to machine code, and writes compiled package data.
• src/cmd/asm/main.go - Shows the assembler entry point used when builds include Go assembly files or architecture-specific runtime support.
• src/cmd/cgo/main.go - Defines the cgo command structures that collect Go files, C references, C compiler options, generated files, and exported functions when a package imports C.
• src/cmd/addr2line/main.go - Represents a bundled tool accessed through go tool addr2line; it maps program counters in binaries back to function and file-line information for profiling workflows.
• misc/go_android_exec/main.go - Provides an execution wrapper that the Go tool can use to run built binaries on Android devices through adb during tests and builder workflows.

Build Workflow

For a new command-line application, the practical workflow is intentionally short. From the directory containing the main package, run go build. The command resolves the current package, compiles dependencies, and leaves an executable that can be run directly from that directory, such as ./hello on Unix-like systems or hello.exe on Windows. This is the right command when you want a concrete binary for inspection, local execution, packaging, or integration testing but do not want to change your configured installation directory.

go build
./hello

Installing is the next step when you want to run the executable by name rather than by path. Official documentation recommends discovering the install destination with go list -f '{{.Target}}', adding that directory to the shell path if necessary, and then running go install. The result is still produced from the package and dependency graph, but the final artifact is copied into the Go install target instead of only appearing in the current directory. That makes go install a deployment step for developer tools and local commands.

go list -f '{{.Target}}'
go install
hello

The repository-level install story is related but separate. The README points most users to official binary distributions at https://go.dev/dl/ and then to installation instructions at https://go.dev/doc/install. It also identifies source installation instructions for operating system and architecture combinations that do not have a binary distribution. In other words, installing Go itself gives you the go command and toolchain; using go install later installs binaries built from your own packages or module-version package arguments. Sources: README.md

System-to-Code Mapping

The go build command is the public orchestration layer, but individual tools perform specialized parts of the work. The compiler entry point in src/cmd/compile/internal/gc/main.go describes its own main routine as parsing flags and Go source files, type-checking the parsed package, compiling functions to machine code, and writing the compiled package definition to disk. That sequence is the core transformation from Go source package to object and export data used by later build steps. Sources: src/cmd/compile/internal/gc/main.go

The assembler entry point in src/cmd/asm/main.go handles architecture-specific assembly inputs. It checks build configuration, selects the target architecture, configures link context flags such as shared, dynlink, and linkshared, parses assembly or symbol ABI inputs, and writes an object file. This is where build modes become visible below the go command: higher-level build choices are translated into tool flags and link context properties that affect generated objects and how they can be linked. Sources: src/cmd/asm/main.go

Packages that use cgo add another boundary to the build. The cgo command models a package with Go files, generated GCC output files, C compiler options, linker flags, collected preambles, exported functions, and references to C.xxx expressions. That structure explains why cgo builds involve both Go analysis and C toolchain interaction. A normal pure-Go package can flow directly through the compiler and assembler as needed; a cgo package first expands the Go/C boundary into generated Go and C artifacts that the rest of the build can consume. Sources: src/cmd/cgo/main.go

Tool binaries produced by the Go distribution are also part of the build-and-install mental model. src/cmd/addr2line/main.go documents a minimal go tool addr2line binary command used by pprof. It reads hexadecimal addresses from standard input and prints function and source file-line information. Although developers usually do not call it during go build, its presence shows that the installed Go distribution includes auxiliary tools used to inspect and diagnose binaries after they have been built. Sources: src/cmd/addr2line/main.go

Build Modes and Specialized Execution

Build modes are most visible to users as go build options, but the lower tools receive concrete configuration. The assembler code sets link context fields for dynamic linking, shared output, linkshared operation, package import path, standard-library status, and ABI metadata generation. This is a useful way to reason about advanced builds: the go command selects packages and high-level options, then invokes architecture-aware tools with enough context to produce compatible object files for the final link. Sources: src/cmd/asm/main.go, src/cmd/compile/internal/gc/main.go

Coverage-instrumented builds are another example of build configuration changing the produced binary. Official documentation describes go build -cover as the build step for integration-test coverage: it produces an application binary instrumented for coverage data collection, then the binary is run one or more times, and finally coverage data is reported. By default, packages in the main module are selected for instrumentation, while dependencies and standard library packages are not included unless configured. This reinforces that go build can produce ordinary binaries or specialized binaries for testing and diagnostics.

go build -cover

Some builds are followed immediately by execution in an environment different from the host. The Android execution wrapper is designed to be named as a go_android_GOARCH_exec helper for the Go tool. It serializes adb use with a file lock, waits for the device boot property, copies the Go root once per build script run, prepares temporary device directories, runs the binary through adb, parses an appended exit code, and cleans up. That source shows that build workflows can include platform-specific execution adapters without changing the package author's source layout. Sources: misc/go_android_exec/main.go

Compact Reference

Practical Next Steps

For day-to-day development, use go build first when you want to verify that a command package compiles and produces a runnable binary in place. Use go install when the command is ready to become part of your local toolset, and confirm that the install target is on your path before assuming the command name will resolve. If the package imports C, expect cgo and the platform C toolchain to participate; if it includes assembly, expect architecture-specific assembler behavior to matter.

When debugging or optimizing built programs, remember that build output is not the end of the workflow. Coverage builds, pprof symbolization, and platform execution helpers all rely on artifacts produced by the same toolchain. Read the go command reference for command-line flags, the testing and coverage pages for test-oriented build modes, and the cgo and toolchain command reference pages when a build involves C code, assembly, profiling, or cross-platform execution.