cross-compilation

building for platforms other than the one you're on. zig makes this unusually easy, but there are still patterns to know.

basic cross-compilation

zig can target any platform from any platform:

const target = b.standardTargetOptions(.{});  // from -Dtarget=...

user runs: zig build -Dtarget=aarch64-linux-gnu

that's it for pure zig. c dependencies complicate things.

cpu targeting

bun explicitly sets cpu models per platform:

pub fn getCpuModel(os: OperatingSystem, arch: Arch) ?Target.Query.CpuModel {
    if (os == .linux and arch == .aarch64) {
        return .{ .explicit = &Target.aarch64.cpu.cortex_a35 };
    }
    if (os == .mac and arch == .aarch64) {
        return .{ .explicit = &Target.aarch64.cpu.apple_m1 };
    }
    // x86_64 defaults to haswell for avx2
    return null;
}

and offers a "baseline" mode for maximum compatibility:

if (opts.baseline) {
    // target nehalem (~2008) instead of haswell (~2013)
    return .{ .explicit = &Target.x86_64.cpu.nehalem };
}

baseline builds run on older hardware but miss avx2 optimizations.

glibc version

linux binaries link against glibc. if you build against glibc 2.34, it won't run on systems with glibc 2.17.

pub fn getOSGlibCVersion(os: OperatingSystem) ?Version {
    return switch (os) {
        .linux => .{ .major = 2, .minor = 26, .patch = 0 },
        else => null,
    };
}

bun targets glibc 2.26 (from ~2017) for broad compatibility.

macos universal binaries

ghostty builds for both x86_64 and aarch64, then combines with lipo:

// build for both architectures
const x86_lib = try buildLib(b, deps.retarget(b, x86_64_macos));
const arm_lib = try buildLib(b, deps.retarget(b, aarch64_macos));

// combine into universal binary
const lipo_step = LipoStep.create(b, .{
    .input_a = x86_lib.getEmittedBin(),
    .input_b = arm_lib.getEmittedBin(),
    .out_name = "libghostty.a",
});

the deps.retarget() pattern creates a copy of SharedDeps pointing at a different target.

xcframework for apple platforms

for ios apps, you need an xcframework containing:

macos universal (x86_64 + arm64)
ios arm64
ios simulator (arm64 + x86_64)

const macos = try buildMacOSUniversal(b, deps);
const ios = try buildLib(b, deps.retarget(b, .{ .os_tag = .ios, .cpu_arch = .aarch64 }));
const ios_sim = try buildLib(b, deps.retarget(b, .{ .os_tag = .ios, .abi = .simulator }));

// xcodebuild -create-xcframework ...

minimum os versions

centralize version requirements:

pub fn osVersionMin(os: std.Target.Os.Tag) std.Target.Os.SemVer {
    return switch (os) {
        .macos => .{ .major = 13, .minor = 0, .patch = 0 },
        .ios => .{ .major = 17, .minor = 0, .patch = 0 },
        else => .{ .major = 0, .minor = 0, .patch = 0 },
    };
}

apply when creating targets:

const target = b.resolveTargetQuery(.{
    .os_tag = .macos,
    .os_version_min = Config.osVersionMin(.macos),
});

environment detection

helpful warnings for common mistakes:

fn checkNixShell(exe: *std.Build.Step.Compile, cfg: *const Config) !void {
    std.fs.accessAbsolute("/etc/NIXOS", .{}) catch return;  // not nixos
    if (cfg.env.get("IN_NIX_SHELL") != null) return;  // in nix shell, good

    try exe.step.addError(
        "Building on NixOS outside nix shell. " ++
        "Use: nix develop -c zig build",
        .{},
    );
}

sources: