Cross-compiling
Go compiles to a static executable for another operating system and CPU from any supported host: GOOS and GOARCH are environment variables read by the build, and the toolchain already contains the standard library for every pair. No virtual machine, cross compiler or container is needed, which is why a release script can produce all the binaries from one Ubuntu runner. The build tags lesson explained which files a target selects; this one changes the target.
Two variables and a binary
A build with the two variables set produces a binary for that pair, and the program prints the values it was compiled with at run time. The file command confirms the format, and the suffix in the output name is a convention, not something the toolchain adds: a Windows binary needs .exe because Windows wants it, and the rest is for the human reading the directory.
package main
import (
"fmt"
"runtime"
)
func main() {
fmt.Println("os:", runtime.GOOS, "arch:", runtime.GOARCH)
}
GOOS=linux GOARCH=arm64 go build -o app-linux-arm64 . && file -b app-linux-arm64 | cut -d, -f1-2
ELF 64-bit LSB executable, ARM aarch64
GOOS=windows GOARCH=amd64 go build -o app.exe . && file -b app.exe | cut -d, -f1-2
PE32+ executable for MS Windows 6.01 (console), x86-64
GOOS=darwin GOARCH=arm64 go build -o app-darwin . && file -b app-darwin | cut -d, -f1-2
Mach-O 64-bit arm64 executable, flags:<|DYLDLINK|PIE>
go tool dist list | head -6
aix/ppc64
android/386
android/amd64
android/arm
android/arm64
darwin/amd64
The first three lines name the format and the CPU the binaries were built for, and the last command lists the targets the toolchain supports. The build did not run the programs, because a binary for ARM64 or Windows cannot execute on this machine; a test of the behaviour on the target needs that target or an emulator.
What turns it off
A package that uses cgo cannot be cross-compiled without a C toolchain for the target, because the C part must be compiled by a compiler for that platform. The common answer is CGO_ENABLED=0 in the release build, which also produces a fully static binary that runs on any Linux without the matching C library. A dependency that needs cgo, such as a database driver over libsqlite3, forces a decision: build on the target, use a pure-Go alternative, or accept a dynamic binary for that platform only.
What still depends on the target
runtime.GOOS and runtime.GOARCH are constants baked into each build, and os.PathSeparator, the line ending a program writes and the availability of a syscall all differ by target. A path built with a forward slash works on Windows for most APIs but not all, and a file opened without O_BINARY on Windows corrupts binary data. The build flags do not change the code; the code has to be written for the target it runs on, with build tags where the difference is real.
Exercises
- Build for freebsd/amd64 and run file on the result. Which field of the output identifies the target?
- Add a dependency that uses cgo and try CGO_ENABLED=0 GOOS=windows go build. Read the error and name the package that stopped the build.
- Write a program that prints the path separator and the executable suffix for its target, then build it for Windows and Linux. Which values change?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which variables choose the target of a build?
Answer
GOOS and GOARCH
The pair selects the platform and the CPU.
-
Does a cross-compiled binary run on the build machine?
Answer
Only if the target matches the machine
A binary for another CPU cannot execute on the host.
-
What does CGO_ENABLED=0 give a release build?
Answer
A static binary without a C dependency
It also makes cross-compilation work without a target C compiler.
-
Why can a cgo program not be cross-compiled easily?
Answer
The C part needs a compiler for the target platform
The C toolchain is the missing piece, not Go itself.
-
What does the .exe suffix do?
Answer
It is a convention Windows expects, not something the toolchain adds
The build writes whatever name -o gives it.
-
What is runtime.GOARCH in a build?
Answer
The CPU architecture the binary was compiled for
It is a constant baked in at compile time.
-
Which command lists the supported targets?
Answer
go tool dist list
It prints the GOOS/GOARCH pairs the toolchain supports.
-
What does a static binary avoid?
Answer
A dependency on the C library of the machine it runs on
That is why CGO_ENABLED=0 helps in small containers.
-
What still has to be written for the target after a cross build?
Answer
Code that depends on paths, line endings or syscalls
The compiler cannot make a Windows-only API exist on Linux.
-
What does file -b report?
Answer
The format and architecture of a binary
It is the quick check that the build produced the right target.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev