cross-gcc

Cross-GCC

用途

指导 Agent 设置和使用交叉编译 GCC 工具链：三元组、sysroot、pkg-config、基于 QEMU 的测试以及常见故障。

触发条件

• “如何在我的 x86 机器上为 ARM 编译？”
• “我遇到了 ‘wrong ELF class’ 或 ‘cannot execute binary file’ 错误”
• “如何为交叉编译设置 sysroot？”
• “交叉构建时 pkg-config 返回了主机上的库”
• “如何使用 QEMU + GDB 调试交叉编译的二进制文件？”

工作流

1. 了解三元组

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. 安装工具链

# Debian/Ubuntu
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-aarch64-linux-gnu

# For bare-metal ARM (Cortex-M)
sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi

# Verify
aarch64-linux-gnu-gcc --version

3. 基本交叉编译

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

# C++
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

4. Sysroot

sysroot 是一个包含目标平台头文件和库的目录。如果代码要链接目标平台专用的库，就需要使用 sysroot。

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

# Common sysroot sources:
# - Raspberry Pi: download from raspbian/raspios
# - Debian multiarch: debootstrap --arch arm64 bullseye /tmp/sysroot
# - Yocto/Buildroot: generated automatically in build output

验证 sysroot 是否正确：

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

5. 为交叉构建配置 pkg-config

默认情况下，pkg-config 会返回主机上的库路径。覆盖此行为：

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

6. CMake 交叉编译

创建工具链文件 aarch64.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)

cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=aarch64.cmake
cmake --build build

7. 使用 QEMU 测试

# User-mode emulation (Linux binaries, no full OS)
sudo apt install qemu-user-static

qemu-aarch64-static ./hello
# Or set binfmt_misc for transparent execution:
# Then just: ./hello

# GDB remote debug via QEMU
qemu-aarch64-static -g 1234 ./hello &
aarch64-linux-gnu-gdb -ex "target remote :1234" ./hello

8. 常见错误

错误	原因	解决方法
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. 环境变量

# 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

# For autoconf projects
./configure --host=aarch64-linux-gnu --prefix=/usr

有关 ARM 专用 GCC 标志的参考，请参阅 references/arm-flags.md。

相关技能

• 使用 skills/compilers/gcc 查看 GCC 标志详情
• 使用 skills/debuggers/gdb 配合 gdbserver 进行远程调试
• 使用 skills/low-level-programming/assembly-arm 查看 AArch64 汇编的具体信息
• 使用 skills/build-systems/cmake 设置工具链文件