Zig Cross-Compilation: No More Toolchain Hell

Traditional cross-compilation means installing a different toolchain for every target. Building for Windows? Install MinGW and pray the linker doesn't shit itself. ARM targets? Download some vendor's custom GCC that may or may not work with your project.

Zig downloads as one file. Everything's included - libc for every platform, cross-compilation support, the whole deal.

Target Specification

Zig uses architecture-os-abi format. Simple enough:

zig build -Dtarget=x86_64-windows        # Windows
zig build -Dtarget=aarch64-linux         # ARM64 Linux
zig build -Dtarget=wasm32-freestanding    # WebAssembly
zig build -Dtarget=arm-linux-musleabihf  # ARM with musl

Run zig targets to see what's supported. The list is massive.

Where It Actually Breaks

CLI Tools for Multiple Platforms

Used to need separate CI runners for each OS. Now one Linux runner builds everything:

zig build -Dtarget=x86_64-windows
zig build -Dtarget=aarch64-macos
zig build -Dtarget=x86_64-linux

Except Windows Defender flags your static binaries as malware. macOS won't run unsigned binaries without scary warnings. ARM64 builds work in QEMU but crash on real ARM hardware - emulation hides memory access bugs.

WebAssembly

Skip Emscripten. Zig compiles to WASM directly:

zig build-lib src/main.zig -target wasm32-freestanding -dynamic

No 500KB runtime overhead. But debugging WASM still sucks - browser tools show assembly, not your source. printf() doesn't exist, memory model is restrictive.

Embedded

Traditional embedded toolchains are vendor-specific hell. Zig works bare metal:

zig build-exe src/main.zig -target thumb-freestanding -mcpu cortex_m4

Still need to fight linker scripts and memory layouts. Hardware debugging requires expensive probes.

What Actually Happens

When you run zig build -Dtarget=aarch64-linux, Zig picks the right libc, configures the linker, and generates the right machine code. Everything transparent.

Cross-Compiling C/C++ Code

Use zig cc as a GCC replacement:

export CC=\"zig cc -target aarch64-linux-gnu\"
export CXX=\"zig c++ -target aarch64-linux-gnu\"
./configure && make

Works for simple C projects. Complex ones with autotools break in new and exciting ways. You'll spend more time debugging configure scripts than actual code.

Cross-compilation beats the old toolchain nightmare, but it's not magic. Platform bugs still exist, Windows Defender still flags your binaries, and timing issues still only show up on real hardware.

Stuff that actually works in production, and how it breaks.

CLI Tool Build Setup

CLI tools need to work everywhere. Basic multi-platform build:

// build.zig
const release_targets = [_]ReleaseTarget{
    .{ .target = .{ .cpu_arch = .x86_64, .os_tag = .linux }, .name = "linux-x64" },
    .{ .target = .{ .cpu_arch = .x86_64, .os_tag = .windows }, .name = "windows-x64" },
    .{ .target = .{ .cpu_arch = .aarch64, .os_tag = .macos }, .name = "macos-arm64" },
};

pub fn build(b: *std.Build) void {
    const exe = b.addExecutable(.{
        .name = "mytool",
        .root_source_file = .{ .path = "src/main.zig" },
        .target = b.standardTargetOptions(.{}),
    });
    b.installArtifact(exe);

    const release_step = b.step("release", "Build for all platforms");
    for (release_targets) |release_target| {
        const release_exe = b.addExecutable(.{
            .name = "mytool",
            .root_source_file = .{ .path = "src/main.zig" },
            .target = b.resolveTargetQuery(release_target.target),
            .optimize = .ReleaseSafe,
        });
        const install_exe = b.addInstallArtifact(release_exe, .{
            .dest_dir = .{ .override = .{ .custom = release_target.name } },
        });
        release_step.dependOn(&install_exe.step);
    }
}

Windows Defender flags static binaries as malware. macOS warns about unsigned apps. ARM64 works in QEMU but crashes on real hardware - emulation hides memory alignment bugs.

WebAssembly + Native Builds

Build for both browser and native:

const builtin = @import("builtin");

pub fn main() !void {
    if (builtin.target.cpu.arch == .wasm32) {
        try wasmMain();
    } else {
        try nativeMain();
    }
}

fn nativeMain() !void {
    // Normal file system, network access
    const file = try std.fs.cwd().openFile("config.json", .{});
    defer file.close();
}

fn wasmMain() !void {
    // WASM constraints - no filesystem, limited memory
    var buffer: [4096]u8 = undefined;
    var fba = std.heap.FixedBufferAllocator.init(&buffer);
}

zig build -Doptimize=ReleaseFast                      # Native
zig build -Dtarget=wasm32-freestanding -Doptimize=ReleaseSmall  # WASM

WASM debugging sucks. "Memory access out of bounds" errors with no context. No threads. Browser dev tools show assembly, not your source.

Embedded Development

Use conditional compilation for hardware abstraction:

const builtin = @import("builtin");

pub const GPIO = if (builtin.target.cpu.arch == .thumb)
    EmbeddedGPIO
else
    TestGPIO;

const EmbeddedGPIO = struct {
    pub fn setPin(pin: u8, value: bool) void {
        const gpio_base: *volatile u32 = @ptrFromInt(0x40020000);
        // register manipulation
    }
};

const TestGPIO = struct {
    pub fn setPin(pin: u8, value: bool) void {
        std.debug.print("GPIO pin {} = {}
", .{ pin, value });
    }
};

zig build test  # Mock hardware on dev machine
zig build -Dtarget=thumb-freestanding -Dcpu=cortex_m4  # Real hardware

Mock hardware works fine. Real hardware has timing bugs, power noise, and EMI that no test catches. You'll spend hours with an oscilloscope wondering why pin 7 glitches randomly.

CI/CD

One Linux runner builds for all platforms:

zig build -Dtarget=x86_64-windows
zig build -Dtarget=aarch64-macos
zig build -Dtarget=x86_64-linux

Works until GitHub runners hit disk space limits or Windows Defender quarantines your artifacts. QEMU in CI still misses bugs that only show on real ARM hardware.

Memory Management

Different targets need different allocators:

pub fn createAllocator() std.mem.Allocator {
    return switch (builtin.target.cpu.arch) {
        .wasm32 => blk: {
            var buffer: [1024 * 1024]u8 = undefined; // 1MB
            var fba = std.heap.FixedBufferAllocator.init(&buffer);
            break :blk fba.allocator();
        },
        .thumb => blk: {
            var buffer: [64 * 1024]u8 = undefined; // 64KB
            var fba = std.heap.FixedBufferAllocator.init(&buffer);
            break :blk fba.allocator();
        },
        else => blk: {
            var gpa = std.heap.GeneralPurposeAllocator(.{}){};
            break :blk gpa.allocator();
        },
    };
}

Debugging

For ARM64, use QEMU with GDB:

zig build -Dtarget=aarch64-linux -Doptimize=Debug
qemu-aarch64 -g 1234 -L /usr/aarch64-linux-gnu ./zig-out/bin/myapp &
gdb-multiarch ./zig-out/bin/myapp

Common Gotchas

Use compile-time branching, not runtime:

// Good
const socket_impl = if (builtin.target.os.tag == .windows)
    @import("socket_windows.zig")
else
    @import("socket_posix.zig");

Handle endianness for network protocols:

const big_endian = std.mem.nativeToBig(u32, value);

Plan for cross-compilation early. Retrofitting platform assumptions later sucks.

Cross-compilation works in development, breaks in production. Common problems and fixes.

Custom Targets

For hardware not in Zig's target list:

pub const custom_embedded_target = std.Target{
    .cpu = std.Target.Cpu{
        .arch = .arm,
        .model = &std.Target.arm.cpu.cortex_m4,
        .features = std.Target.arm.featureSet(&[_]std.Target.arm.Feature{
            .v7em, .has_v7, .thumb2,
        }),
    },
    .os = .freestanding,
    .abi = .eabihf,
    .ofmt = .elf,
};

Needed for custom hardware where default settings don't work.

Binary Size Optimization

Different targets have size limits. WASM needs small downloads, embedded has flash limits:

// Size optimization by target
if (target.result.cpu.arch == .wasm32) {
    exe.want_lto = true;
    exe.strip = true;
} else if (target.result.os.tag == .freestanding) {
    exe.bundle_compiler_rt = false;
    exe.strip = true;
    exe.setLinkerScriptPath(.{ .path = "linker.ld" });
}

Testing Cross-Compiled Code

Use QEMU for ARM64 testing:

zig build -Dtarget=aarch64-linux
qemu-aarch64 -L /usr/aarch64-linux-gnu ./zig-out/bin/myapp --version

For Windows, use Wine:

zig build -Dtarget=x86_64-windows
wine ./zig-out/bin/myapp.exe --version

For WASM, use wasmtime:

zig build -Dtarget=wasm32-freestanding
wasmtime ./zig-out/bin/myapp.wasm --version

Custom Linker Scripts

For embedded targets:

MEMORY {
    FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 1024K
    RAM (rwx)  : ORIGIN = 0x20000000, LENGTH = 128K
}

Use in build.zig:

if (target.result.os.tag == .freestanding) {
    exe.setLinkerScriptPath(.{ .path = "custom_linker.ld" });
}

Common Problems

Windows linking errors: Reinstall Zig from ziglang.org. Don't use distro packages.

WASM runtime crashes: Use wasmtime --debug to debug. Check for missing imports with wasm-objdump.

Embedded binary too large: Strip everything: exe.strip = true; exe.want_lto = true; exe.optimize = .ReleaseSmall

ARM64 emulation slow: QEMU is 10x slower than native. Get real ARM64 hardware or accept the pain.

Static linking OpenSSL fails: Try musl target: zig build -Dtarget=x86_64-linux-musl

Windows path limits: 260 character limit still hits in CI. Use shorter paths.

Cross-compilation in Zig beats traditional toolchain hell, but production still has platform-specific gotchas. Test on real hardware when possible.