Back to Details

cross-gcc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cross-GCC

GCC交叉编译

Purpose

用途

Guide agents through setting up and using cross-compilation GCC toolchains: triplets, sysroots, pkg-config, QEMU-based testing, and common failure modes.
指导Agent完成交叉编译GCC工具链的搭建与使用：包括交叉编译三元组、sysroot、pkg-config、基于QEMU的测试，以及常见问题排查。

Triggers

触发场景

  • "How do I compile for ARM on my x86 machine?"
  • "I'm getting 'wrong ELF class' or 'cannot execute binary file'"
  • "How do I set up a sysroot for cross-compilation?"
  • "pkg-config returns host libraries in my cross build"
  • "How do I debug a cross-compiled binary with QEMU + GDB?"
  • "如何在x86机器上为ARM架构编译代码？"
  • "我遇到了'wrong ELF class'或'cannot execute binary file'错误"
  • "如何为交叉编译配置sysroot？"
  • "交叉编译时pkg-config返回主机库路径"
  • "如何使用QEMU + GDB调试交叉编译的二进制文件？"

Workflow

工作流程

1. Understand the triplet

1. 理解交叉编译三元组

A GNU triplet has the form 
<arch>-<vendor>-<os>-<abi>
(often 3 or 4 parts):
TripletTarget
aarch64-linux-gnu
64-bit ARM Linux (glibc)
arm-linux-gnueabihf
32-bit ARM Linux hard-float
arm-none-eabi
Bare-metal ARM (no OS)
riscv64-linux-gnu
64-bit RISC-V Linux
x86_64-w64-mingw32
Windows (MinGW) from Linux
mipsel-linux-gnu
Little-endian MIPS Linux
GNU交叉编译三元组的格式为
<arch>-<vendor>-<os>-<abi>
（通常为3或4个部分）：
三元组目标架构
aarch64-linux-gnu
64位ARM Linux（glibc）
arm-linux-gnueabihf
32位ARM Linux硬浮点
arm-none-eabi
裸机ARM（无操作系统）
riscv64-linux-gnu
64位RISC-V Linux
x86_64-w64-mingw32
从Linux编译Windows（MinGW）
mipsel-linux-gnu
小端MIPS Linux

2. Install the toolchain

2. 安装工具链

bash
undefined
bash
undefined

Debian/Ubuntu

Debian/Ubuntu

sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-aarch64-linux-gnu
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-aarch64-linux-gnu

For bare-metal ARM (Cortex-M)

针对裸机ARM（Cortex-M）

sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi
sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi

Verify

验证

aarch64-linux-gnu-gcc --version
undefined
aarch64-linux-gnu-gcc --version
undefined

3. Basic cross-compilation

3. 基础交叉编译

bash
undefined
bash
undefined

C

C语言

aarch64-linux-gnu-gcc -O2 -o hello hello.c
aarch64-linux-gnu-gcc -O2 -o hello hello.c

C++

C++语言

aarch64-linux-gnu-g++ -O2 -std=c++17 -o hello hello.cpp
aarch64-linux-gnu-g++ -O2 -std=c++17 -o hello hello.cpp

Bare-metal (no stdlib, no OS)

裸机环境（无标准库、无操作系统）

arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16
-ffreestanding -nostdlib -T linker.ld -o firmware.elf startup.s main.c
undefined
arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16
-ffreestanding -nostdlib -T linker.ld -o firmware.elf startup.s main.c
undefined

4. Sysroot

4. Sysroot配置

A sysroot is a directory containing the target's headers and libraries. Required when your code links against target-specific libraries.
bash
undefined
Sysroot是包含目标架构头文件和库的目录，当代码需要链接目标架构专属库时必须配置。
bash
undefined

Use a sysroot

使用sysroot

aarch64-linux-gnu-gcc --sysroot=/path/to/aarch64-sysroot -O2 -o prog main.c
aarch64-linux-gnu-gcc --sysroot=/path/to/aarch64-sysroot -O2 -o prog main.c

Common sysroot sources:

常见sysroot来源：

- Raspberry Pi: download from raspbian/raspios

- 树莓派：从raspbian/raspios下载

- Debian multiarch: debootstrap --arch arm64 bullseye /tmp/sysroot

- Debian多架构：debootstrap --arch arm64 bullseye /tmp/sysroot

- Yocto/Buildroot: generated automatically in build output

- Yocto/Buildroot：在构建输出中自动生成


Verify the sysroot is correct:

```bash
aarch64-linux-gnu-gcc --sysroot=/path/to/sysroot -v -E - < /dev/null 2>&1 | grep sysroot

验证sysroot配置是否正确：

```bash
aarch64-linux-gnu-gcc --sysroot=/path/to/sysroot -v -E - < /dev/null 2>&1 | grep sysroot

5. pkg-config for cross builds

5. 交叉编译中的pkg-config配置

pkg-config
will return host library paths by default. Override:
bash
export PKG_CONFIG_SYSROOT_DIR=/path/to/sysroot
export PKG_CONFIG_LIBDIR=${PKG_CONFIG_SYSROOT_DIR}/usr/lib/aarch64-linux-gnu/pkgconfig:${PKG_CONFIG_SYSROOT_DIR}/usr/share/pkgconfig
export PKG_CONFIG_PATH=   # clear host path

pkg-config --libs libssl  # now returns target paths
默认情况下
pkg-config
会返回主机库路径，需通过以下方式覆盖：
bash
export PKG_CONFIG_SYSROOT_DIR=/path/to/sysroot
export PKG_CONFIG_LIBDIR=${PKG_CONFIG_SYSROOT_DIR}/usr/lib/aarch64-linux-gnu/pkgconfig:${PKG_CONFIG_SYSROOT_DIR}/usr/share/pkgconfig
export PKG_CONFIG_PATH=   # 清空主机路径

pkg-config --libs libssl  # 现在返回目标架构路径

6. CMake cross-compilation

6. CMake交叉编译

Create a toolchain file 
aarch64.cmake
:
cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

set(CMAKE_C_COMPILER   aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)

set(CMAKE_SYSROOT /path/to/aarch64-sysroot)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
bash
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=aarch64.cmake
cmake --build build
创建工具链文件
aarch64.cmake
：
cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

set(CMAKE_C_COMPILER   aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)

set(CMAKE_SYSROOT /path/to/aarch64-sysroot)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
bash
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=aarch64.cmake
cmake --build build

7. Test with QEMU

7. 使用QEMU测试

bash
undefined
bash
undefined

User-mode emulation (Linux binaries, no full OS)

用户模式仿真（Linux二进制文件，无需完整操作系统）

sudo apt install qemu-user-static
qemu-aarch64-static ./hello
sudo apt install qemu-user-static
qemu-aarch64-static ./hello

Or set binfmt_misc for transparent execution:

或设置binfmt_misc实现透明执行：

Then just: ./hello

之后直接运行：./hello

GDB remote debug via QEMU

通过QEMU进行GDB远程调试

qemu-aarch64-static -g 1234 ./hello & aarch64-linux-gnu-gdb -ex "target remote :1234" ./hello
undefined
qemu-aarch64-static -g 1234 ./hello & aarch64-linux-gnu-gdb -ex "target remote :1234" ./hello
undefined

8. Common errors

8. 常见错误

ErrorCauseFix
cannot execute binary file: Exec format error
Running target binary on host without QEMUUse 
qemu-<arch>-static
wrong ELF class: ELFCLASS64
(or 32)		Wrong-architecture object linkedCheck triplet; ensure all objects use same toolchain
/usr/bin/ld: cannot find -lfoo
Host library path used for cross-linkSet 
--sysroot
; fix 
PKG_CONFIG_LIBDIR
undefined reference to '__aeabi_*'
Missing ARM ABI runtimeLink with 
-lgcc
or 
-lclang_rt.builtins
relocation R_AARCH64_ADR_PREL_PG_HI21 out of range
Distance too largeUse 
-mcmodel=large
or restructure
unrecognized opcode
Wrong 
-mcpu
or 
-march
Set correct CPU flags for target
错误信息原因解决方法
cannot execute binary file: Exec format error
未通过QEMU直接在主机运行目标架构二进制文件使用
qemu-<arch>-static
执行
wrong ELF class: ELFCLASS64
（或32）		链接了架构不兼容的对象文件检查交叉编译三元组；确保所有对象文件使用同一工具链
/usr/bin/ld: cannot find -lfoo
交叉链接时使用了主机库路径设置
--sysroot
；修复
PKG_CONFIG_LIBDIR
配置
undefined reference to '__aeabi_*'
缺少ARM ABI运行时库添加链接参数
-lgcc
或
-lclang_rt.builtins
relocation R_AARCH64_ADR_PREL_PG_HI21 out of range
代码距离过大使用
-mcmodel=large
参数或重构代码
unrecognized opcode
-mcpu
或
-march
参数设置错误		为目标架构设置正确的CPU标志

9. Environment variables

9. 环境变量配置

bash
undefined
bash
undefined

Tell build systems to use cross-compiler

告知构建系统使用交叉编译器

export CC=aarch64-linux-gnu-gcc export CXX=aarch64-linux-gnu-g++ export AR=aarch64-linux-gnu-ar export STRIP=aarch64-linux-gnu-strip export OBJDUMP=aarch64-linux-gnu-objdump
export CC=aarch64-linux-gnu-gcc export CXX=aarch64-linux-gnu-g++ export AR=aarch64-linux-gnu-ar export STRIP=aarch64-linux-gnu-strip export OBJDUMP=aarch64-linux-gnu-objdump

For autoconf projects

针对autoconf项目

./configure --host=aarch64-linux-gnu --prefix=/usr

For a reference on ARM-specific GCC flags, see [references/arm-flags.md](references/arm-flags.md).
./configure --host=aarch64-linux-gnu --prefix=/usr

关于ARM专属GCC标志的参考文档，请查看[references/arm-flags.md](references/arm-flags.md)。

Related skills

相关技能

  • Use 
    skills/compilers/gcc
    for GCC flag details
  • Use 
    skills/debuggers/gdb
    for remote debugging with 
    gdbserver
  • Use 
    skills/low-level-programming/assembly-arm
    for AArch64 assembly specifics
  • Use 
    skills/build-systems/cmake
    for toolchain file setup
  • 若需了解GCC标志细节，请使用
    skills/compilers/gcc
  • 若需了解gdbserver远程调试，请使用
    skills/debuggers/gdb
  • 若需了解AArch64汇编细节，请使用
    skills/low-level-programming/assembly-arm
  • 若需了解工具链文件设置，请使用
    skills/build-systems/cmake