go-build

Compile a 'package main' file (output will be the filename without extension)

$ go build [path/to/main.go]

$ go build -o [path/to/binary] [path/to/source.go]

$ go build -o [path/to/binary] [path/to/package]

$ go build -race -o [path/to/executable] [path/to/main_package]

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

-a
    Force rebuild of all packages, ignoring cache.

-c
    Compile only; do not link into executable.

-i
    Install dependencies before building.

-o output
    Specify output file or directory name.

-race
    Enable race detector (adds instrumentation).

-gcflags args
    Arguments for compiler (gc).

-ldflags args
    Arguments for linker.

-tags tag,list
    Build with given tags for conditional compilation.

-trimpath
    Remove directory info from debug info.

-v
    Print verbose action messages.

-work
    Print temporary work directory (keep after build).

-x
    Print all command lines while building.

-asmflags args
    Arguments for assembler.

-buildvcs=bool
    Include VCS info in binaries (default true).

-buildmode mode
    Build mode (e.g., exe, pie, plugin).

-compiler gc|gccgo
    Specify compiler to use.

-installsuffix suffix
    Modify package path for installs.

-linkshared
    Link against shared libraries.

-mod=mod
    Module download mode (auto, readonly, vendor).

-modfile=file
    Use alternate go.mod file.

-msan
    Enable MSan instrumentation.

-mutexprofile file
    Output mutex profile.

-n
    Print commands without executing.

-p n
    Parallelism level (default based on CPUs).

-toolexec cmd
    Invoke tool with custom command.

The go build command is a core tool in the Go programming language toolchain, used to compile Go source code packages along with their dependencies into standalone executable binaries. It processes the specified packages (or the main package in the current directory if none are provided), invoking the appropriate compilers and linker to produce platform-specific executables.

By default, go build creates an executable named after the directory containing the package's main.go file, placing it in the current working directory on Unix-like systems (or the parent directory on Windows). For non-main packages, it builds intermediate objects but does not produce a final executable unless linking is implied.

It supports cross-compilation via GOOS and GOARCH environment variables, enabling binaries for different operating systems and architectures without changing source code. Build caching optimizes recompilation by reusing unchanged artifacts. Flags allow fine-grained control over the process, including race detector integration, build tags for conditional compilation, and custom linker/compiler flags.

Essential for Go development workflows, it precedes deployment or testing, ensuring binaries are optimized and self-contained—no Go runtime installation required on target machines.

Does not install binaries (use go install); builds in current directory by default; cross-compilation requires toolchain for target OS/arch; large projects may need -mod=vendor for reproducibility.

go build
Builds main package in current directory.

go build -o myapp ./cmd/myapp
Builds with custom output name.

GOOS=linux GOARCH=amd64 go build
Cross-compiles for Linux AMD64.

GOOS, GOARCH: Target OS/arch.
GOPATH: Workspace paths (legacy).
GOCACHE: Build cache location.
GOFLAGS: Default flags for all commands.

0 on success; non-zero on error (e.g., 1 for compile failure, 2 for usage error).

Introduced with Go 1.0 release in March 2012 as part of the standard toolchain. Evolved from early Go compilers (6g, 8g); build system rewritten in Go 1.5 (2015) for self-hosting; caching added in Go 1.10 (2018); module support in Go 1.11 (2018) enhanced dependency handling.

go install(1), go run(1), go clean(1), gcc(1)