Back to Details

rust-cross

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rust Cross-Compilation

Rust交叉编译

Purpose

用途

Guide agents through Rust cross-compilation: adding rustup targets, using 
cross
for hermetic Docker-based cross-builds, 
cargo-zigbuild
for zero-setup cross-compilation, 
.cargo/config.toml
configuration, and embedded bare-metal targets.
指导开发者完成Rust交叉编译的全流程：添加rustup目标、使用
cross
基于Docker实现封闭环境交叉构建、使用
cargo-zigbuild
实现零配置交叉编译、配置
.cargo/config.toml
，以及针对嵌入式裸机目标的构建。

Triggers

触发场景

  • "How do I cross-compile Rust for ARM/aarch64?"
  • "How do I build a Rust binary for a different OS?"
  • "How do I use the cross tool for Rust cross-compilation?"
  • "How do I build Rust for embedded (no_std) targets?"
  • "How do I use cargo-zigbuild?"
  • "My cross-compiled Rust binary won't run on the target"
  • "如何为ARM/aarch64交叉编译Rust代码？"
  • "如何为不同操作系统构建Rust二进制文件？"
  • "如何使用cross工具进行Rust交叉编译？"
  • "如何为嵌入式（no_std）目标构建Rust代码？"
  • "如何使用cargo-zigbuild？"
  • "我交叉编译的Rust二进制文件在目标系统上无法运行"

Workflow

操作流程

1. Add a rustup target

1. 添加rustup目标

bash
undefined
bash
undefined

List installed targets

列出已安装的目标

rustup target list --installed
rustup target list --installed

List all available targets

列出所有可用目标

rustup target list
rustup target list

Add a target

添加目标

rustup target add aarch64-unknown-linux-gnu rustup target add x86_64-unknown-linux-musl # static Linux rustup target add wasm32-unknown-unknown # WASM rustup target add thumbv7m-none-eabi # Cortex-M
rustup target add aarch64-unknown-linux-gnu rustup target add x86_64-unknown-linux-musl # 静态链接Linux目标 rustup target add wasm32-unknown-unknown # WASM目标 rustup target add thumbv7m-none-eabi # Cortex-M目标

Build for target

为目标构建

cargo build --target aarch64-unknown-linux-gnu --release
undefined
cargo build --target aarch64-unknown-linux-gnu --release
undefined

2. Common target triples

2. 常见目标三元组

TargetUse case
x86_64-unknown-linux-gnu
Linux x86-64 (glibc)
x86_64-unknown-linux-musl
Linux x86-64 (musl, static)
aarch64-unknown-linux-gnu
ARM64 Linux (Raspberry Pi 4, AWS Graviton)
aarch64-unknown-linux-musl
ARM64 Linux static
x86_64-pc-windows-gnu
Windows x86-64 (MinGW)
x86_64-pc-windows-msvc
Windows x86-64 (MSVC)
x86_64-apple-darwin
macOS x86-64
aarch64-apple-darwin
macOS Apple Silicon
wasm32-unknown-unknown
WASM (browser)
wasm32-wasi
WASM with WASI
thumbv7m-none-eabi
Cortex-M3 bare metal
thumbv7em-none-eabihf
Cortex-M4/M7 with FPU
riscv32imac-unknown-none-elf
RISC-V 32-bit bare metal
目标使用场景
x86_64-unknown-linux-gnu
Linux x86-64（glibc）
x86_64-unknown-linux-musl
Linux x86-64（musl，静态链接）
aarch64-unknown-linux-gnu
ARM64 Linux（树莓派4、AWS Graviton）
aarch64-unknown-linux-musl
ARM64 Linux静态链接
x86_64-pc-windows-gnu
Windows x86-64（MinGW）
x86_64-pc-windows-msvc
Windows x86-64（MSVC）
x86_64-apple-darwin
macOS x86-64
aarch64-apple-darwin
macOS Apple Silicon
wasm32-unknown-unknown
WASM（浏览器）
wasm32-wasi
带WASI的WASM
thumbv7m-none-eabi
Cortex-M3裸机
thumbv7em-none-eabihf
带FPU的Cortex-M4/M7
riscv32imac-unknown-none-elf
RISC-V 32位裸机

3. cross tool (Docker-based, easiest)

3. cross工具（基于Docker，最简单）

cross
uses pre-built Docker images with the correct cross-toolchain:
bash
undefined
cross
使用预构建的Docker镜像，内含正确的交叉编译工具链：
bash
undefined

Install

安装

cargo install cross
cargo install cross

Build (drop-in replacement for cargo)

构建（可直接替代cargo）

cross build --target aarch64-unknown-linux-gnu --release cross test --target aarch64-unknown-linux-gnu
cross build --target aarch64-unknown-linux-gnu --release cross test --target aarch64-unknown-linux-gnu

Cross.toml — project configuration

Cross.toml — 项目配置文件


```toml

```toml

Cross.toml

Cross.toml

[target.aarch64-unknown-linux-gnu] image = "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main" pre-build = [ "apt-get update && apt-get install -y libssl-dev:arm64" ]
[build.env] passthrough = ["PKG_CONFIG_PATH", "OPENSSL_DIR"]
undefined
[target.aarch64-unknown-linux-gnu] image = "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main" pre-build = [ "apt-get update && apt-get install -y libssl-dev:arm64" ]
[build.env] passthrough = ["PKG_CONFIG_PATH", "OPENSSL_DIR"]
undefined

4. cargo-zigbuild (zero-setup, uses zig cc)

4. cargo-zigbuild（零配置，使用zig cc）

zig cc
ships a complete C cross-toolchain — no system cross-compiler needed:
bash
undefined
zig cc
自带完整的C交叉编译工具链 — 无需系统级交叉编译器：
bash
undefined

Install

安装

cargo install cargo-zigbuild
cargo install cargo-zigbuild

Also needs zig installed: https://ziglang.org/download/

还需要安装zig：https://ziglang.org/download/

Build (no Docker, no system cross-compiler)

构建（无需Docker，无需系统交叉编译器）

cargo zigbuild --target aarch64-unknown-linux-gnu --release cargo zigbuild --target x86_64-unknown-linux-musl --release
cargo zigbuild --target aarch64-unknown-linux-gnu --release cargo zigbuild --target x86_64-unknown-linux-musl --release

Target with glibc version (important for compatibility)

指定glibc版本的目标（兼容性很重要）

cargo zigbuild --target aarch64-unknown-linux-gnu.2.17 --release
cargo zigbuild --target aarch64-unknown-linux-gnu.2.17 --release

This builds against glibc 2.17 (very compatible)

这会针对glibc 2.17构建（兼容性极强）

Windows from Linux/macOS

从Linux/macOS构建Windows目标

cargo zigbuild --target x86_64-pc-windows-gnu --release

`cargo-zigbuild` advantages over `cross`:

- No Docker required
- Faster (no container startup)
- Works for most targets out of the box
- Supports precise glibc version targeting
cargo zigbuild --target x86_64-pc-windows-gnu --release

`cargo-zigbuild`相对`cross`的优势：

- 无需Docker
- 速度更快（无需容器启动时间）
- 开箱即用支持大多数目标
- 支持精确指定glibc版本

5. .cargo/config.toml for cross targets

5. 为交叉目标配置.cargo/config.toml

toml
undefined
toml
undefined

.cargo/config.toml

.cargo/config.toml

[target.aarch64-unknown-linux-gnu] linker = "aarch64-linux-gnu-gcc" # System cross-linker
[target.aarch64-unknown-linux-gnu] linker = "aarch64-linux-gnu-gcc" # 系统交叉链接器

or with zig:

或者使用zig：

linker = "zig"

linker = "zig"

rustflags = ["-C", "link-arg=cc", "-C", "link-arg=-target", "-C", "link-arg=aarch64-linux-gnu"]

rustflags = ["-C", "link-arg=cc", "-C", "link-arg=-target", "-C", "link-arg=aarch64-linux-gnu"]

[target.x86_64-unknown-linux-musl] linker = "x86_64-linux-musl-gcc" rustflags = ["-C", "target-feature=+crt-static"]
[target.wasm32-unknown-unknown] runner = "wasmtime" # Run WASM tests with wasmtime
[target.thumbv7m-none-eabi] runner = "qemu-arm -cpu cortex-m3"
undefined
[target.x86_64-unknown-linux-musl] linker = "x86_64-linux-musl-gcc" rustflags = ["-C", "target-feature=+crt-static"]
[target.wasm32-unknown-unknown] runner = "wasmtime" # 使用wasmtime运行WASM测试
[target.thumbv7m-none-eabi] runner = "qemu-arm -cpu cortex-m3"
undefined

6. Static binaries with musl

6. 使用musl构建静态二进制文件

bash
undefined
bash
undefined

Add musl target

添加musl目标

rustup target add x86_64-unknown-linux-musl
rustup target add x86_64-unknown-linux-musl

Build statically linked binary

构建静态链接二进制文件

cargo build --target x86_64-unknown-linux-musl --release
cargo build --target x86_64-unknown-linux-musl --release

Verify it's static

验证是否为静态链接

file target/x86_64-unknown-linux-musl/release/myapp
file target/x86_64-unknown-linux-musl/release/myapp

→ ELF 64-bit, statically linked, not stripped

→ ELF 64-bit, statically linked, not stripped

Or with cargo-zigbuild (easier musl)

或者使用cargo-zigbuild（更简单的musl构建方式）

cargo zigbuild --target x86_64-unknown-linux-musl --release
undefined
cargo zigbuild --target x86_64-unknown-linux-musl --release
undefined

7. Embedded bare-metal (#[no_std])

7. 嵌入式裸机（#[no_std]）

toml
undefined
toml
undefined

.cargo/config.toml

.cargo/config.toml

[build] target = "thumbv7em-none-eabihf" # Set default target
[target.'cfg(target_arch = "arm")'] runner = "probe-run --chip STM32F411CE"

```rust
// src/main.rs
#![no_std]
#![no_main]

use core::panic::PanicInfo;

#[cortex_m_rt::entry]
fn main() -> ! {
    loop {}
}

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}
toml
undefined
[build] target = "thumbv7em-none-eabihf" # 设置默认目标
[target.'cfg(target_arch = "arm")'] runner = "probe-run --chip STM32F411CE"

```rust
// src/main.rs
#![no_std]
#![no_main]

use core::panic::PanicInfo;

#[cortex_m_rt::entry]
fn main() -> ! {
    loop {}
}

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}
toml
undefined

Cargo.toml

Cargo.toml

[dependencies] cortex-m = "0.7" cortex-m-rt = "0.7"
[profile.release] opt-level = "z" lto = true codegen-units = 1 panic = "abort"

```bash
cargo build --release  # Uses default target from .cargo/config.toml
For target triple reference and embedded setup details, see references/.
[dependencies] cortex-m = "0.7" cortex-m-rt = "0.7"
[profile.release] opt-level = "z" lto = true codegen-units = 1 panic = "abort"

```bash
cargo build --release  # 使用.cargo/config.toml中的默认目标
关于目标三元组参考和嵌入式设置详情，请查看[references/]。

Related skills

相关技能

  • Use 
    skills/rust/rustc-basics
    for compiler and profile configuration
  • Use 
    skills/compilers/cross-gcc
    for the underlying cross-compiler setup
  • Use 
    skills/zig/zig-cross
    for Zig's native cross-compilation approach
  • Use 
    skills/build-systems/cmake
    when Rust is part of a CMake cross-build
  • 编译器和配置文件配置请使用
    skills/rust/rustc-basics
  • 底层交叉编译器设置请使用
    skills/compilers/cross-gcc
  • Zig原生交叉编译方式请使用
    skills/zig/zig-cross
  • 当Rust作为CMake交叉构建的一部分时，请使用
    skills/build-systems/cmake