rust-cross

Rust クロスコンパイル

目的

Rust のクロスコンパイルについてエージェントをガイドします。rustup ターゲットの追加、cross を使った Docker ベースの分離されたクロスビルド、cargo-zigbuild を使ったセットアップ不要のクロスコンパイル、.cargo/config.toml の設定、組み込み向けベアメタルターゲットを扱います。

トリガー

• 「Rust を ARM/aarch64 向けにクロスコンパイルするにはどうすればよいですか？」
• 「別の OS 向けに Rust バイナリをビルドするにはどうすればよいですか？」
• 「Rust のクロスコンパイルに cross ツールを使うにはどうすればよいですか？」
• 「組み込み（no_std）ターゲット向けに Rust をビルドするにはどうすればよいですか？」
• 「cargo-zigbuild を使うにはどうすればよいですか？」
• 「クロスコンパイルした Rust バイナリがターゲット上で動きません」

ワークフロー

1. rustup ターゲットを追加する

# List installed targets
rustup target list --installed

# List all available targets
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

# Build for target
cargo build --target aarch64-unknown-linux-gnu --release

2. 一般的なターゲットトリプル

ターゲット	用途
x86_64-unknown-linux-gnu	Linux x86-64（glibc）
x86_64-unknown-linux-musl	Linux x86-64（musl、静的リンク）
aarch64-unknown-linux-gnu	ARM64 Linux（Raspberry Pi 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 ツール（Docker ベースで最も簡単）

cross は、適切なクロスツールチェーンを備えたビルド済み Docker イメージを使用します。

# Install
cargo install cross

# Build (drop-in replacement for cargo)
cross build --target aarch64-unknown-linux-gnu --release
cross test --target aarch64-unknown-linux-gnu

# Cross.toml — project configuration

# 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"]

4. cargo-zigbuild（セットアップ不要、zig cc を使用）

zig cc には完全な C クロスツールチェーンが含まれているため、システムにクロスコンパイラーを用意する必要はありません。

# Install
cargo install cargo-zigbuild
# Also needs zig installed: https://ziglang.org/download/

# Build (no Docker, no system cross-compiler)
cargo zigbuild --target aarch64-unknown-linux-gnu --release
cargo zigbuild --target x86_64-unknown-linux-musl --release

# Target with glibc version (important for compatibility)
cargo zigbuild --target aarch64-unknown-linux-gnu.2.17 --release
# This builds against glibc 2.17 (very compatible)

# Windows from Linux/macOS
cargo zigbuild --target x86_64-pc-windows-gnu --release

cross と比べた cargo-zigbuild の利点：

• Docker が不要です
• より高速です（コンテナーの起動がありません）
• ほとんどのターゲットで、すぐに利用できます
• glibc のバージョンを正確に指定できます

5. クロスターゲット向けの .cargo/config.toml

# .cargo/config.toml

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"    # System cross-linker
# or with zig:
# linker = "zig"
# 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"

6. musl による静的バイナリ

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

# Build statically linked binary
cargo build --target x86_64-unknown-linux-musl --release

# Verify it's static
file target/x86_64-unknown-linux-musl/release/myapp
# → ELF 64-bit, statically linked, not stripped

# Or with cargo-zigbuild (easier musl)
cargo zigbuild --target x86_64-unknown-linux-musl --release

7. 組み込み向けベアメタル（#[no_std]）

# .cargo/config.toml
[build]
target = "thumbv7em-none-eabihf"   # Set default target

[target.'cfg(target_arch = "arm")']
runner = "probe-run --chip STM32F411CE"

// 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 {}
}

# Cargo.toml
[dependencies]
cortex-m = "0.7"
cortex-m-rt = "0.7"

[profile.release]
opt-level = "z"
lto = true
codegen-units = 1
panic = "abort"

cargo build --release  # Uses default target from .cargo/config.toml

ターゲットトリプルの一覧と組み込み環境のセットアップの詳細については、references/ を参照してください。

関連スキル

• コンパイラーとプロファイルの設定には、skills/rust/rustc-basics を使用します
• 基盤となるクロスコンパイラーのセットアップには、skills/compilers/cross-gcc を使用します
• Zig ネイティブのクロスコンパイル方法には、skills/zig/zig-cross を使用します
• Rust が CMake のクロスビルドの一部である場合は、skills/build-systems/cmake を使用します