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 [build flags] [packages]

Description:
Builds the specified packages. If no packages are given, builds the package in the current directory.

Examples:
go build
go build -o myapp ./cmd/myapp
go build -v github.com/my/repo/cmd/tool
GOOS=windows GOARCH=amd64 go build -o myapp.exe

-o output
    Write the resulting executable or object to the named output file. Default is the package name (for main packages) or an empty string (for non-main packages, meaning cached).

-v
    Print the names of packages as they are compiled.

-x
    Print the commands go toolchain executes during the build.

-n
    Print the commands but do not run them.

-a
    Force rebuilding of packages that are already up-to-date.

-ldflags 'flags'
    Arguments to pass on to the linker (e.g., for setting version info).

-gcflags 'flags'
    Arguments to pass on to the go compiler.

-tags 'taglist'
    A comma-separated list of build tags to consider satisfied during the build. Used for conditional compilation.

-race
    Enable data race detection. Only for supported systems.

-mod=mode
    Controls how Go modules are used. 'readonly' (default), 'vendor', 'mod'.

-trimpath
    Remove all file system paths from the compiled executable. Makes builds more reproducible.

-work
    Print the name of the temporary work directory and do not delete it when exiting.

-toolexec 'cmd args'
    A program to invoke before the Go toolchain's compiler, assembler, linker, or other tools.

-buildmode=mode
    Builds the packages in a specific build mode (e.g., 'exe', 'pie', 'shared', 'c-archive', 'c-shared').

-p N
    The number of programs that can be run in parallel. Defaults to the number of CPUs available.

The go build command compiles the Go source files or packages specified by the import path. If no package is specified, it compiles the package in the current directory. When compiling a main package, it produces an executable binary. For other packages, it compiles them into a cached archive that can be used by other Go commands. It handles dependency resolution automatically and uses Go modules for managing dependencies, making the build process robust and reproducible. The command leverages the Go toolchain's cross-compilation capabilities, allowing binaries for different operating systems and architectures to be built from a single machine.

When building a main package, go build creates an executable. If building a non-main package, it only compiles and caches the package for future use by other Go commands; it does not produce a standalone output file unless specified with -o and a buildmode that supports it (e.g. c-archive).
Cross-compilation requires setting the GOOS and GOARCH environment variables. Building for specific architectures or operating systems that are not the host system may require additional C compilers or libraries if CGO is involved.
Dependency resolution relies on Go modules. If modules are not initialized or go.mod is incorrect, the build might fail or use unexpected dependencies.

GOOS: The target operating system (e.g., linux, windows, darwin).
GOARCH: The target architecture (e.g., amd64, arm, arm64).
These variables are crucial for cross-compilation. For example: GOOS=windows GOARCH=amd64 go build.
GOPATH: (Legacy/Module-aware Fallback) Defines the root of workspaces. Less critical with Go Modules, but still used for some legacy setups or specific go get behaviors.
GOROOT: The installation directory of the Go toolchain.

Beyond creating executables, go build can produce shared libraries (-buildmode=shared, -buildmode=c-shared), static archives (-buildmode=c-archive), and position-independent executables (-buildmode=pie), facilitating integration with other languages and environments.

The go build command is a fundamental part of the Go programming language's toolchain, introduced early in Go's development to provide a simple, opinionated, and efficient way to compile Go programs. Its design reflects Go's philosophy of simplicity and built-in tooling. With the introduction of Go Modules in Go 1.11 (and becoming the default in Go 1.16), go build seamlessly integrated module-aware dependency resolution, enhancing reproducibility and project management without significant changes to its core usage. This evolution has made it a robust and widely-used command for Go developers.

go run(1): Compiles and runs the specified Go package., go install(1): Compiles and installs packages and commands., go clean(1): Removes object files and cached files., go test(1): Automates testing of Go packages., go mod(1): Manages module dependencies.