The go Command, Builds and Cross-Compilation

Most commands take package patterns. A path starting with . or .. names a directory, an import path names a package, and ... is a wildcard. Four reserved patterns exist: std (the standard library), cmd (the toolchain’s own commands), all (the main module’s packages and everything they import) and, since Go 1.25, work (the packages of the work modules). Wildcard matching skips directories named testdata and those whose names begin with . or _, and, since Go 1.25, directories named by an ignore directive in go.mod. A pattern that matches nothing is only a warning for ... patterns but an error for a plain path.

Source: cmd/go: Package lists and patterns

go run builds the program into a temporary location, runs it with the remaining arguments, and removes it. Arguments after the package belong to the program; flags before the package belong to the build.

Three details matter in scripts. The exit status of go run is not that of the program: any non-zero status is reported as exit status N on standard error and go run itself exits with 1. The binary is compiled without the debugger information that go build writes, to save time, so build explicitly to debug. And -exec prog runs the binary through a wrapper (prog binary arguments); when GOOS or GOARCH differ from the host, go run looks on PATH for a program called go_$GOOS_$GOARCH_exec (for example go_js_wasm_exec) and uses it to run cross-compiled binaries in an emulator or runtime.

Source: cmd/go: Compile and run Go program

go install is go build followed by moving the result to a standard place: executables go to GOBIN, which defaults to $GOPATH/bin and GOPATH defaults to $HOME/go. Cross-compiled executables go to $GOBIN/$GOOS_$GOARCH subdirectories, and go install refuses to cross-compile at all while GOBIN is explicitly set:

With a version suffix, go install installs a command from a module, ignoring any go.mod in the current directory, so installing a tool never changes the dependencies of the project you are standing in. This is the form that replaced go get for installing programs (go get stopped building and installing in Go 1.18). The arguments must be main packages, all with the same version query, all from one module. @latest and any other module query such as @v1.4.0, @main or a commit hash work. To show it offline, the following was run against a throwaway module proxy holding example.com/shelf at v1.4.0 and v1.5.0 (set up with GOPROXY=file://...); against the public proxy the commands are identical:

go run pkg@version works the same way, which is how one-off tools are run without installing them. Use the tool directive in go.mod (Go 1.24) for tools a project depends on, covered in Modules and Dependency Management.

Source: cmd/go: Compile and install packages and dependencies and Go Modules Reference: go install

go clean removes what builds leave behind. Run without arguments inside a main package directory it deletes the executable go build wrote there; the flags widen the reach:

go clean -modcache is the right way to empty the module cache; deleting it by hand fails because the module cache is read-only. Source: cmd/go: Remove object files and cached files

go build -json (and go install -json, go test -json) emits one JSON object per line instead of text, for tools and CI systems. Each event has an ImportPath, an Action (build-output or build-fail) and, for output, the text. Concatenating the Output fields gives the usual text. Here is a deliberately broken program:

Source: cmd/go: Build -json encoding and Go 1.24 release notes

-X importpath.name=value sets the value of a string variable at link time. For package main the import path is literally main, even though the package has a longer path in go list. Other packages use their full import path.

Source: cmd/link

The rules visible in that run: the variable must be a package-level string variable; it must be initialized with a constant (or not at all) — Channel silently kept stable because its initializer is a function call that runs at program start and overwrites the linker’s value; a non-string variable is a link error; a name that does not exist is silently ignored, so a typo in the import path produces a binary that still says dev. A constant cannot be set at all (it is not a variable). -X takes importpath.name=value, and the whole argument must be quoted when the value contains spaces. Because a wrong path is silent, check the result in CI, for example by running the built binary with --version.

Other linker flags used in release builds: -s omits the symbol table and -w omits DWARF debug information. Together they shrink this program by about a third and make stack traces and debuggers less useful:

Source: cmd/link

Whatever flags are used, the go command records build information in the executable: the Go version, the main module and its dependencies with versions and checksums, and the build settings that affect the result. Programs read it with runtime/debug.ReadBuildInfo; people read it with go version -m, which works on any Go binary without source.

Reading the lines: path is the main package, mod the main module (with (devel) when no version is known), and each build line one setting. Settings appear when they were set or when they matter: -tags, -ldflags, -gcflags, CGO_ENABLED and the C flags, GOOS, GOARCH, the microarchitecture variable of the target (GOARM64 here), and vcs.*. Dependencies add dep lines (with => lines for replacements) when there are any. go version has more forms:

Pass -v to report non-Go files found while walking. Because everything in go version -m is data inside the binary, it is also what vulnerability scanners such as govulncheck read to decide which dependency versions a deployed file contains.

By default (-buildvcs=auto) the go command adds the version-control revision, commit time and a modified flag to the build information when the main package, its module and the current directory are in one repository. Go 1.18 added the vcs.* settings; Go 1.24 additionally uses the same information to set the main module’s version, which used to be (devel) for every local build:

Here is the same module built four ways, in a Git repository whose first commit carries the tag v1.6.0. The output is filtered from go version -m:

go run never stamps version-control data, and neither does a directory that is not under version control. -buildvcs=true turns the quiet skipping into an error when the data exists but cannot be included (for example because the git program is missing from a build container), which is a good setting for CI. -buildvcs=false is needed for reproducible builds across different checkouts. A frequent surprise is a build inside a Docker image: when .git is not copied into the build context the binary says (devel), and when it is copied but git is not installed -buildvcs=auto silently omits the data. The simplest robust recipe is to compute the version in the pipeline and pass it with -X, and to also leave -buildvcs on so both are recorded.

Source: cmd/go: Compile packages and dependencies and Go 1.24 release notes: Go command

A normal binary contains the absolute path of every source file (for stack traces and debuggers). That makes two builds of identical source differ if the checkouts are in different directories. -trimpath rewrites those paths to module paths (example.com/shelf/cmd/shelf/main.go), and records -trimpath=true in the build information. Combined with -buildvcs=false (or identical repository state), the same source, toolchain and flags then give the same bytes regardless of where the build runs:

(The second pair differs because the working directory is embedded.) One more consequence of -trimpath: the go command then omits the -ldflags setting from the recorded build information, because linker flags can themselves contain absolute paths (-extld, -extar, -extldflags); a binary built with -trimpath -ldflags "-s -w" shows only -trimpath=true. Reproducibility also needs a fixed toolchain: the go line plus GOTOOLCHAIN selects it (see Toolchain Versions and Compatibility), and the Go project itself publishes toolchains that anyone can rebuild bit for bit.

Source: Perfectly Reproducible, Verified Go Toolchains and cmd/go: Compile packages and dependencies

The line is //go:build followed by an expression using tags, !, &&, || and parentheses, with the usual precedence (&& binds tighter than ||). It must appear before the package clause, preceded only by blank lines and other line comments, and followed by a blank line. These files are the watch package of a second example module:

Source: cmd/go: Build constraints

Source: cmd/go: Build constraints

The package also has watch_linux.go and watch_windows.go with no constraint line (their names are enough), unix.go guarded by //go:build unix and notunix.go by //go:build !unix, fast_generic.go with the negation of the constraint of fast_amd64.go, and a gen.go guarded by //go:build ignore that is a stand-alone generator. Which files make it into the package for each target is visible with go list, without compiling anything:

go run gen.go still works for the ignore file because a file named on the command line is built whatever its constraint says (go run cmdfile/m.go runs a //go:build linux file on macOS, while go run ./cmdfile reports that the constraints exclude every file). The convention is ignore for files meant to be run by hand and a project tag (purego, integration, shelfdebug) for optional behavior. purego is the community name for "use no assembly"; many libraries switch their optimized files off with it.

Source: cmd/go: Build constraints and go/build/constraint

A file whose name, before .go, ends in _GOOS, _GOARCH or _GOOS_GOARCH is constrained to that target, with no constraint line needed: lock_linux.go, fast_arm64.go, syscall_windows_amd64.go. A file named exactly like a known value (linux.go) is not constrained — the underscore is required — and the suffix is only recognized for operating systems and architectures that Go knows. The trailing _test is checked first, so x_linux_test.go is a Linux-only test file. It also works in the other direction, which surprises people: x_test_linux.go is a normal Linux file, not a test file, because the name ends in _linux:

Choose names with care: dns_android.go is a different thing from a file about Android devices if your package has no Android story, and a new operating system or architecture added to Go can retroactively constrain a file whose name happens to end with it. Prefer a constraint line for anything that is not clearly a platform file.

Every go1.N up to the compiler’s version is true, so //go:build go1.27 includes a file only when built with Go 1.27 or later, and //go:build !go1.27 provides the fallback. Two notes. The tag follows the toolchain, not the go line of go.mod; the go line decides which language features are allowed. A library that must also build with older compilers can use release tags to offer a fallback implementation, as in the example that follows.

(A tag given with -tags is simply set; real release tags are only up to the compiler’s version, so go1.99 is false unless forced.)

For the architectures with microarchitecture levels, the level is a tag too: amd64.v1..amd64.v4 (Go 1.18), the matching forms arm64.v8.1 to arm64.v9.5 and riscv64.rva22u64, and so on. A higher level also satisfies the lower tags, so with GOAMD64=v3 the tags amd64.v1, amd64.v2 and amd64.v3 all hold:

Here base.go is constrained by !amd64.v3 and v3.go by amd64.v3.

A constraint after the package clause is silently ignored by the build, which is why the buildtag analyzer of go vet reports it. The same analyzer checks the legacy form. Before Go 1.17 the syntax was // +build linux darwin (space is OR, comma is AND, separate lines are AND). Go 1.17 introduced //go:build; gofmt adds the equivalent new line above an old one and keeps the two in sync. A file that has only the old line is still honoured by the build, so old code keeps working; once both lines exist, the old one can be deleted in a module with go 1.27. If both are present and disagree, go vet complains:

When every file of a package is excluded for the target, building it is an error naming the package; wildcard patterns quietly skip such packages:

Always test the other targets: GOOS=windows go vet ./... and GOOS=linux go vet ./... compile and analyze the files your own platform excludes, which is the cheapest way to catch a missing file for a new platform.

Putting the flags together gives the usual release recipe: no cgo, paths trimmed, symbols stripped, the version set by the linker, and the checksum file next to the binaries. The script was run for real:

For tagged releases with archives, signing, a Homebrew tap and container images, do not hand-write this script: GoReleaser drives exactly these go build calls from a configuration file, and the Packaging and Distribution page of the command-line guide covers it together with checksums and attestations. The Go side to remember is -trimpath plus a recorded version so that a user can run go version -m on the file they downloaded.

Within one architecture the compiler can target newer instruction sets for speed, at the price of not running on older processors. The setting is an environment variable read at build time and recorded in the build information:

Which level to pick is a deployment decision: v3 is a safe floor for servers bought in the last decade and meaningfully faster for numeric code, but a binary built with it exits with an illegal-instruction error on an older CPU, so it needs the same care as an operating-system minimum version.