Native Binaries & Cross-Compilation

Each toolchain documents its own cross-compilation story, and none documents the others. Four consequences follow.

Every project in this section ends with the same four stages, and the choices on this page decide what happens in the first one.

Building comes first because nothing downstream can fix a binary that links against the wrong library. Signing comes before packaging for tools that are signed individually (a Windows executable inside a zip) and after it for formats that are signed as a whole (a macOS .pkg); the signing page covers the order for each operating system.

A program can carry the code it needs, or it can name the libraries that must be present when it starts. Both models exist on every platform, but what is practical differs.

The trade-off is simple to state. Static linking buys portability: one file runs on any machine of the right operating system and processor. Dynamic linking buys maintainability: the platform vendor can fix the shared library without a new release of your tool. A command-line tool that users download from a release page and drop into a PATH directory almost always wants the first. A tool installed from a distribution package, where the package manager already tracks libraries, may reasonably prefer the second.

Static linking is not free. Name-service lookups, locale data and anything the C library loads at run time with dlopen (the glibc name-service switch is the classic case) behave differently or not at all in a static program, and the Swift Static Linux SDK documentation states that dlopen() does not work in its binaries. Test a static shelf against the features that touch the network and the locale before you ship it.

A binary built on a recent Linux distribution fails on an older one with a message such as version 'GLIBC_2.38' not found. The cause is symbol versioning: each glibc function the program uses is recorded together with the version of the library that introduced the symbol, and the dynamic loader refuses to start a program that asks for a version the installed glibc does not have. Versioning is forward-compatible only: a program built against glibc 2.17 runs on glibc 2.17 and every later release, but not the other way round.

Two practical rules follow.

The last line is the highest glibc version shelf needs. Compare it with the oldest distribution you support. The command is the standard binutils objdump; it was not run while this page was written because no Linux build was available.

Source: Linux man-pages (ld.so(8)) and the glibc manual.

musl avoids the problem by removing the dynamic dependency: a musl binary contains the C library and needs nothing from the host except the kernel. That is why every toolchain in this page that offers a "run anywhere on Linux" output offers it through musl.

Rust lists the musl targets as Tier 2 with host tools, meaning the project builds them automatically and guarantees they build, while the aarch64-apple-darwin, x86_64-pc-windows-msvc and aarch64-pc-windows-msvc targets are Tier 1. The Rust Reference adds that x86_64-unknown-linux-musl links the C runtime statically by default.

Source: Rust — Platform Support and Rust Reference — Linkage.

On Windows, "static or dynamic" is chiefly a question about the C runtime (the CRT), because Windows system calls always go through DLLs that exist on every machine. The MSVC compiler selects the runtime with a switch.

For a command-line tool distributed as a download, /MT is the usual choice: the executable contains the runtime and starts on a clean Windows installation without the Visual C++ Redistributable. Two rules apply. All modules passed to one linker invocation must use the same runtime option, and mixing /MT with a dependency built /MD produces link errors or two separate copies of the runtime in one process. Use /MD when shelf loads plug-in DLLs that must share the same heap and the same errno as the host program.

Source: Microsoft — /MD, /MT, /LD (Use runtime library).

The CMake variable CMAKE_MSVC_RUNTIME_LIBRARY is documented by CMake and not by Microsoft; the generator expression selects /MT for release and /MTd for debug builds. Neither Windows snippet was run, because no Windows host was available.

Other toolchains expose the same choice under their own name. Rust calls it the crt-static target feature:

Source: Rust Reference — Linkage.

The Reference states that x86_64-pc-windows-msvc and x86_64-unknown-linux-musl support both runtimes, and that targets which cannot switch runtimes ignore the flag, so check the result with dumpbin /dependents shelf.exe on Windows or ldd on Linux.

Apple Silicon (arm64) and Intel (x86_64) Macs both exist in the field, and a Mach-O file can contain code for both. Two settings control compatibility.

Source: Apple — Building a universal macOS binary.

The session above was run with Apple clang 21 on macOS 27. Apple’s page documents the Xcode build settings; the command-line forms shown here are the clang and lipo equivalents, and lipo -info and otool -l are the standard inspection commands from the Xcode command line tools. otool prints one minos per slice, which is why it appears twice.

SwiftPM builds a universal executable with repeated --arch options:

Running it for a one-line shelf package printed x86_64 arm64. On a macOS 27 toolchain the build also printed a warning that the x86_64 architecture is deprecated for that deployment target, which is a reminder that the Intel slice will not be supported forever: decide when your support window for Intel Macs ends, and drop the slice then, because it doubles the size of the download.

Source: Swift — Getting started with SwiftPM and swift-argument-parser.

A universal file is also what the signing step expects: sign and notarize the combined file, not the slices. Rust and Go build one slice per target and leave the combining to you, with the exception of cargo zigbuild --target universal2-apple-darwin, shown below.

Cross-compilation means building on one operating system or processor for another. Whether it works depends on three things: the compiler can emit code for the target, a linker can produce the target’s file format, and the target’s system libraries or headers are available. The toolchains differ mostly in how much of the third requirement they solve for you.

A release binary is the product users download thousands of times, and its size also affects startup, because the operating system maps and pages it in. Most of the gain comes from a few switches; none is documented as a size guarantee, so measure the effect on shelf before and after.

Source: The Cargo Book — Profiles and .NET — Native AOT.

The strip command exists on all three systems, but its flags differ: GNU strip --strip-unneeded on Linux and strip -x on macOS (the macOS tool rejects some GNU options). Run on a four-line macOS C file, strip -x did not shrink the file at all (49,816 bytes became 49,848), which shows how little a hello-world measurement says about a real tool; measure shelf itself. Executable packers such as UPX are outside the toolchains' documentation; they trade startup time for size and are known to interfere with code signing and some security scanners, so test them with your signing step before adopting them.

A build is reproducible when the same source and the same toolchain version produce the same bytes. Reproducibility lets a user or a package maintainer rebuild shelf and compare checksums. It also removes noise from release diffs. The Reproducible Builds project documents the standard convention: SOURCE_DATE_EPOCH is an environment variable holding the number of seconds since the Unix epoch, read as UTC, which tools use instead of the current time wherever they would embed a date.

Source: Reproducible Builds — SOURCE_DATE_EPOCH.

The usual sources of difference between two builds of the same commit are:

Reproducibility is verified by building twice, on two machines if possible, and comparing checksums with sha256sum (Linux) or shasum -a 256 (macOS). Mach-O files built by Apple’s toolchain embed identifiers and code signatures that vary between builds; the Reproducible Builds documentation covers only the convention, so assume a macOS build is not bit-for-bit reproducible until you have shown that it is. In a short experiment on the build machine used here, two plain clang -O2 builds of the same four-line C file were not byte-identical, so the claim has to be tested per toolchain rather than assumed.

The workflow below builds shelf on a native runner for each target, names the archives consistently, and uploads them to a GitHub Release when a version tag is pushed. It is the shape that dist and GoReleaser generate for you (next section), written out so the moving parts are visible. The SOURCE_DATE_EPOCH export applies the previous section; the runner labels are the standard GitHub-hosted labels for public repositories.

Source: GitHub — GitHub-hosted runners and actions/runner-images.

The workflow was not run; pin the action versions to the current releases (or to commit hashes, which the security page of the AI section recommends) before using it. Design points worth keeping:

Writing the workflow above by hand for every project is repetitive. Two tools generate or run it.

dist (formerly cargo-dist) is a release tool primarily for Rust projects. Its book describes it as distributing your binaries: dist init enables GitHub CI and generates release.yml, whose stages are plan (wait for a version tag and compute a manifest), build (binaries, tarballs and installers on each supported platform), publish (upload to package managers) and host and announce (create the GitHub Release with the artifacts and notes). The sidebar of the book lists shell, PowerShell, npm, Homebrew, MSI and updater installers, plus checksums and symbols. The book does not state the configuration file name on the page consulted, so run dist init and read the file it creates rather than relying on a name from memory.

Source: dist — Introduction.

Install the tool by the method the book gives; the book is also the authority on the project’s rename from cargo-dist, which its introduction page does not explain.

GoReleaser does the equivalent for Go, and the AI packaging page already documents its configuration, archive formats, checksums and signing in the GoReleaser section; that page is the reference for those options. What belongs here is the build matrix: the Go builder takes goos, goarch and an ignore list to remove combinations, env for CGO_ENABLED=0, flags for -trimpath, and mod_timestamp for reproducible file times.

Source: GoReleaser — Go builder.

By default the Go builder targets darwin, linux and windows on 386, amd64 and arm64; the example narrows it to the architectures the page supports. Validate with goreleaser check and rehearse with goreleaser release --snapshot --clean before the first tag, as the packaging page recommends.

For platform differences that are not about the binary itself, see Cross-Platform Portability.