cross-gcc

Cross-GCC

目的

エージェントがクロスコンパイル用 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（OS なし）
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 は、ターゲットのヘッダーとライブラリを含むディレクトリです。コードがターゲット固有のライブラリとリンクする場合に必要です。

# 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 を参照してください。

関連スキル

• GCC フラグの詳細については、skills/compilers/gcc を使用します
• gdbserver を使ったリモートデバッグについては、skills/debuggers/gdb を使用します
• AArch64 アセンブリの詳細については、skills/low-level-programming/assembly-arm を使用します
• ツールチェーンファイルのセットアップについては、skills/build-systems/cmake を使用します