Cross-compiling and build flags

What cross-compiling means

Normally a compiler builds for the machine it runs on. Cross-compiling means building on one system for another: on your Windows laptop you build a Linux binary for the server, or an ARM binary for a Raspberry Pi or an AWS Graviton machine. With Go this needs no extra tools for pure Go code.

# Linux / macOS / Git Bash
GOOS=linux GOARCH=arm64 go build -o bin/api-linux-arm64 .
GOOS=windows GOARCH=amd64 go build -o bin/api.exe .

go tool dist list   # every supported GOOS/GOARCH pair

# Windows PowerShell
$env:GOOS = "linux"; $env:GOARCH = "amd64"
go build -o bin/api-linux-amd64 .
Remove-Item Env:GOOS, Env:GOARCH   # back to normal builds

cgo and static binaries

cgo lets Go code call C libraries. When cgo is used, the binary may depend on the system C library (libc) and cross-compiling needs a C cross-compiler. Most backend services do not need cgo. Setting CGO_ENABLED=0 forces a pure-Go, fully static binary: it runs on any Linux of that architecture, including empty "scratch" and "distroless" container images. Go already disables cgo by default when cross-compiling.

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o api .

Build flags worth knowing

package main

import "fmt"

var version = "dev" // overwritten at build time

func main() {
	fmt.Println("expense-api", version)
}

// go build -ldflags="-X main.version=1.4.0" -o api .
// ./api   → expense-api 1.4.0

Code for one OS only

Files ending in _linux.go, _windows.go or _darwin.go are only compiled for that system. A //go:build line at the top of a file gives finer control, such as //go:build linux && arm64. Use this for small OS-specific pieces, like file paths or system calls.