Zig Cross-Compilation

Zig交叉编译

Purpose

用途

Guide agents through Zig's built-in cross-compilation: target triple selection, CPU feature targeting,

zig cc

for cross-compiling C projects, embedded bare-metal targets, and WASM output — all without requiring a system cross-toolchain.

指导开发者通过Zig内置的交叉编译功能完成操作：包括目标三元组选择、CPU特性指定、使用

zig cc

交叉编译C项目、嵌入式裸机目标平台编译以及WASM输出——所有操作均无需依赖系统交叉工具链。

Triggers

触发场景

"How do I cross-compile a Zig program for ARM?"
"How do I build Zig for a different OS?"
"How do I use Zig to cross-compile C code for another platform?"
"How do I build Zig for embedded/bare-metal?"
"How do I target WebAssembly with Zig?"
"What Zig target triple do I use for Raspberry Pi?"

"如何为ARM平台交叉编译Zig程序？"
"如何为不同操作系统编译Zig程序？"
"如何使用Zig为其他平台交叉编译C代码？"
"如何为嵌入式/裸机环境编译Zig程序？"
"如何使用Zig针对WebAssembly进行编译？"
"针对树莓派应该使用什么Zig目标三元组？"

Workflow

操作流程

1. Zig's native cross-compilation

1. Zig原生交叉编译

Zig has cross-compilation built in — no cross-toolchain, no Docker, no sysroot needed for pure Zig code:

bash

undefined

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

bash

undefined

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

undefined

zig build-exe src/main.zig -target aarch64-macos-none

undefined

2. Common target triples

2. 常见目标三元组

Target triple	Platform
`x86_64-linux-gnu`	Linux x86-64 (glibc)
`x86_64-linux-musl`	Linux x86-64 (musl, static)
`aarch64-linux-gnu`	ARM64 Linux (Pi 4, AWS Graviton)
`aarch64-linux-musl`	ARM64 Linux static
`armv7-linux-gnueabihf`	ARM 32-bit 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 (browser, no OS)
`wasm32-wasi`	WASM with WASI
`thumbv7m-freestanding-eabi`	Cortex-M3 bare metal
`thumbv7em-freestanding-eabihf`	Cortex-M4/M7 with FPU
`riscv32-freestanding`	RISC-V 32-bit bare metal

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

3. CPU feature targeting

3. CPU特性指定

bash

undefined

bash

undefined

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']) "

undefined

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']) "

undefined

4. zig cc for C cross-compilation

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

zig cc

cross-compiles C without a system cross-toolchain:

bash

undefined

zig cc

可在无需系统交叉工具链的情况下交叉编译C代码：

bash

undefined

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

undefined

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

undefined

5. Build system cross-compilation

5. 构建系统交叉编译

zig

// 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);
    }
}

bash

undefined

zig

// 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);
    }
}

bash

undefined

Build all targets

zig build

Creates: zig-out/bin/myapp-x86_64, myapp-aarch64, myapp-x86_64.exe, myapp-aarch64

undefined

undefined

6. Embedded (bare-metal) targets

6. 嵌入式（裸机）目标平台

bash

undefined

bash

undefined

Cortex-M4 with FPU (STM32F4xx)

zig build-exe src/main.zig
-target thumbv7em-freestanding-eabihf
-mcpu cortex_m4+vfp4
-O ReleaseSmall
--script linker.ld


```zig
// 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...
}

zig build-exe src/main.zig
-target thumbv7em-freestanding-eabihf
-mcpu cortex_m4+vfp4
-O ReleaseSmall
--script linker.ld


```zig
// 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

bash

undefined

bash

undefined

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


For target triple reference and embedded linker script setup, see [references/zig-target-triples.md](references/zig-target-triples.md).

wasm-opt -Oz myapp.wasm -o myapp.opt.wasm


如需目标三元组参考及嵌入式链接脚本设置，请查看[references/zig-target-triples.md](references/zig-target-triples.md)。

zig-cross

Original

Translation

Zig Cross-Compilation

Zig交叉编译

Purpose

用途

Triggers

触发场景

Workflow

操作流程

1. Zig's native cross-compilation

1. Zig原生交叉编译

List all supported targets

List all supported targets

Build for a specific target

Build for a specific target

With build system (pass target as option)

With build system (pass target as option)

Cross-compile for Windows from Linux/macOS

Cross-compile for Windows from Linux/macOS

Cross-compile for macOS from Linux (requires macOS SDK)

Cross-compile for macOS from Linux (requires macOS SDK)

2. Common target triples

2. 常见目标三元组

3. CPU feature targeting

3. CPU特性指定

Native CPU (auto-detect, only for native builds)

Native CPU (auto-detect, only for native builds)

Baseline for architecture (most compatible)

Baseline for architecture (most compatible)

x86-64 with AVX2

x86-64 with AVX2

Raspberry Pi 4 (Cortex-A72)

Raspberry Pi 4 (Cortex-A72)

Cortex-M4 with FPU

Cortex-M4 with FPU

List CPU features for a target

List CPU features for a target

4. zig cc for C cross-compilation

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

Cross-compile C for ARM64 Linux

Cross-compile C for ARM64 Linux

Cross-compile C for Windows

Cross-compile C for Windows

Cross-compile C with static musl linking

Cross-compile C with static musl linking

Use in Makefile for all platforms

Use in Makefile for all platforms

5. Build system cross-compilation

5. 构建系统交叉编译

Build all targets

Build all targets

Creates: zig-out/bin/myapp-x86_64, myapp-aarch64, myapp-x86_64.exe, myapp-aarch64

Creates: zig-out/bin/myapp-x86_64, myapp-aarch64, myapp-x86_64.exe, myapp-aarch64

6. Embedded (bare-metal) targets

6. 嵌入式（裸机）目标平台

Cortex-M4 with FPU (STM32F4xx)

Cortex-M4 with FPU (STM32F4xx)

7. WebAssembly

7. WebAssembly

WASM freestanding (browser)

WASM freestanding (browser)

WASM WASI (wasmtime, wasmer)

WASM WASI (wasmtime, wasmer)

Optimize WASM size

Optimize WASM size

Related skills

相关技能