zig-cross

Zig 交叉编译

目的

指导 Agent 使用 Zig 内置的交叉编译功能：选择目标三元组、指定 CPU 特性、使用 zig cc 交叉编译 C 项目、面向嵌入式裸机目标，以及输出 WASM——所有这些都无需系统交叉工具链。

触发条件

• “如何为 ARM 交叉编译 Zig 程序？”
• “如何为其他操作系统构建 Zig？”
• “如何使用 Zig 为其他平台交叉编译 C 代码？”
• “如何为嵌入式／裸机构建 Zig？”
• “如何使用 Zig 面向 WebAssembly？”
• “Raspberry Pi 应使用什么 Zig 目标三元组？”

工作流

1. Zig 原生交叉编译

Zig 内置交叉编译功能——编译纯 Zig 代码无需交叉工具链、Docker 或 sysroot：

# List all supported targets
zig targets | python3 -c "import sys,json; d=json.load(sys.stdin); [print(t) for t in d['libc']]"

# Build for a specific target
zig build-exe src/main.zig -target aarch64-linux-gnu -O ReleaseFast

# With build system (pass target as option)
zig build -Dtarget=aarch64-linux-gnu -Doptimize=ReleaseFast

# Cross-compile for Windows from Linux/macOS
zig build-exe src/main.zig -target x86_64-windows-gnu

# Cross-compile for macOS from Linux (requires macOS SDK)
zig build-exe src/main.zig -target aarch64-macos-none

2. 常见目标三元组

目标三元组	平台
x86_64-linux-gnu	Linux x86-64（glibc）
x86_64-linux-musl	Linux x86-64（musl，静态）
aarch64-linux-gnu	ARM64 Linux（Pi 4、AWS Graviton）
aarch64-linux-musl	ARM64 Linux 静态
armv7-linux-gnueabihf	ARM 32 位 Linux（Pi 2/3）
x86_64-windows-gnu	Windows x86-64
aarch64-macos-none	macOS Apple Silicon
x86_64-macos-none	macOS Intel
wasm32-freestanding	WASM（浏览器，无操作系统）
wasm32-wasi	使用 WASI 的 WASM
thumbv7m-freestanding-eabi	Cortex-M3 裸机
thumbv7em-freestanding-eabihf	带 FPU 的 Cortex-M4/M7
riscv32-freestanding	RISC-V 32 位裸机

3. CPU 特性指定

# Native CPU (auto-detect, only for native builds)
zig build-exe src/main.zig -mcpu native

# Baseline for architecture (most compatible)
zig build-exe src/main.zig -target x86_64-linux-gnu -mcpu baseline

# x86-64 with AVX2
zig build-exe src/main.zig -target x86_64-linux-gnu -mcpu x86_64+avx2+bmi2

# Raspberry Pi 4 (Cortex-A72)
zig build-exe src/main.zig -target aarch64-linux-gnu -mcpu cortex_a72

# Cortex-M4 with FPU
zig build-exe src/main.zig \
    -target thumbv7em-freestanding-eabihf \
    -mcpu cortex_m4+vfp4

# List CPU features for a target
zig targets | python3 -c "
import sys,json
d=json.load(sys.stdin)
for c in d['cpus']:
    if 'cortex' in c['name']:
        print(c['name'])
"

4. 使用 zig cc 交叉编译 C 代码

zig cc 无需系统交叉工具链即可交叉编译 C 代码：

# Cross-compile C for ARM64 Linux
zig cc -target aarch64-linux-gnu -O2 -o myapp-arm64 main.c

# Cross-compile C for Windows
zig cc -target x86_64-windows-gnu main.c -o myapp.exe

# Cross-compile C with static musl linking
zig cc -target x86_64-linux-musl -static main.c -o myapp-static

# Use in Makefile for all platforms
CC_LINUX_AMD64 = zig cc -target x86_64-linux-gnu
CC_LINUX_ARM64 = zig cc -target aarch64-linux-gnu
CC_WINDOWS     = zig cc -target x86_64-windows-gnu

5. 构建系统交叉编译

// build.zig — cross-build all targets
pub fn build(b: *std.Build) void {
    const targets = [_]std.Target.Query{
        .{ .cpu_arch = .x86_64, .os_tag = .linux, .abi = .gnu },
        .{ .cpu_arch = .aarch64, .os_tag = .linux, .abi = .gnu },
        .{ .cpu_arch = .x86_64, .os_tag = .windows, .abi = .gnu },
        .{ .cpu_arch = .aarch64, .os_tag = .macos },
    };

    for (targets) |t| {
        const target = b.resolveTargetQuery(t);
        const exe = b.addExecutable(.{
            .name = b.fmt("myapp-{s}", .{@tagName(t.cpu_arch.?)}),
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = .ReleaseFast,
        });
        b.installArtifact(exe);
    }
}

# Build all targets
zig build
# Creates: zig-out/bin/myapp-x86_64, myapp-aarch64, myapp-x86_64.exe, myapp-aarch64

6. 嵌入式（裸机）目标

# Cortex-M4 with FPU (STM32F4xx)
zig build-exe src/main.zig \
    -target thumbv7em-freestanding-eabihf \
    -mcpu cortex_m4+vfp4 \
    -O ReleaseSmall \
    --script linker.ld

// src/main.zig — bare metal entry point
const std = @import("std");

// Custom panic handler for embedded (no OS)
pub fn panic(msg: []const u8, _: ?*std.builtin.StackTrace, _: ?usize) noreturn {
    // Toggle LED or halt
    while (true) {}
}

// Entry point (matches linker script)
export fn _start() void {
    main() catch |err| {
        _ = err;
        while (true) {}
    };
}

fn main() !void {
    // Hardware initialization...
}

7. WebAssembly

# WASM freestanding (browser)
zig build-exe src/main.zig \
    -target wasm32-freestanding \
    -O ReleaseSmall \
    --export=init \
    --export=update \
    -fno-entry

# WASM WASI (wasmtime, wasmer)
zig build-exe src/main.zig \
    -target wasm32-wasi \
    -O ReleaseSafe
wasmtime myapp.wasm

# Optimize WASM size
wasm-opt -Oz myapp.wasm -o myapp.opt.wasm

有关目标三元组参考和嵌入式链接脚本设置，请参阅 references/zig-target-triples.md。

相关技能

• 单文件编译标志请使用 skills/zig/zig-compiler
• 多目标 build.zig 配置请使用 skills/zig/zig-build-system
• 在需要系统交叉工具链设置时，请使用 skills/compilers/cross-gcc
• Rust 交叉编译方法对比请使用 skills/rust/rust-cross