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

  1. Build for freebsd/amd64 and run file on the result. Which field of the output identifies the target?
  2. 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.
  3. 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.

  1. Which variables choose the target of a build?

    Answer

    GOOS and GOARCH

    The pair selects the platform and the CPU.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. Which command lists the supported targets?

    Answer

    go tool dist list

    It prints the GOOS/GOARCH pairs the toolchain supports.

  8. 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.

  9. 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.

  10. 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