레트로아크 크로스 빌드 가이드

Docker QEMU로 RetroArch 크로스빌드 완전 가이드

전체 흐름

PC (x86_64)
  └─ Docker + QEMU
       ├─ ARM32 컨테이너  →  Pi 3 바이너리
       ├─ ARM64 컨테이너  →  Pi 4 바이너리
       └─ ARM64 컨테이너  →  Pi 5 바이너리

---

STEP 1: Docker 설치

# Ubuntu/Debian 기준
sudo apt-get update
sudo apt-get install -y docker.io

# 현재 유저를 docker 그룹에 추가 (sudo 없이 사용)
sudo usermod -aG docker $USER
newgrp docker

# 설치 확인
docker --version

---

STEP 2: QEMU 멀티아키텍처 등록

이게 핵심입니다. PC가 ARM 바이너리를 실행할 수 있도록 등록합니다.

docker run --privileged --rm tonistiigi/binfmt --install all

등록 확인

ls /proc/sys/fs/binfmt_misc/
# qemu-aarch64, qemu-arm 등이 보이면 성공

---

STEP 3: RetroArch 소스 준비

# 작업 폴더 생성
mkdir ~/retroarch-build && cd ~/retroarch-build

# 소스 클론
git clone https://github.com/libretro/RetroArch.git
cd RetroArch

---

STEP 4: 각 파이별 Dockerfile 작성

폴더 구조를 먼저 만듭니다.

mkdir -p ~/retroarch-build/docker/{pi3,pi4,pi5}

Pi 3용 Dockerfile (ARM32)

cat > ~/retroarch-build/docker/pi3/Dockerfile << 'EOF'
FROM --platform=linux/arm/v7 debian:bookworm

RUN apt-get update && apt-get install -y \
    build-essential git pkg-config \
    libgbm-dev libdrm-dev \
    libegl1-mesa-dev libgles2-mesa-dev \
    libasound2-dev libusb-1.0-0-dev \
    libfreetype6-dev libudev-dev \
    libxml2-dev zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /build
COPY . .

RUN ./configure \
    --enable-opengles \
    --enable-opengles3 \
    --enable-kms \
    --enable-egl \
    --enable-alsa \
    --enable-udev \
    --disable-vulkan \
    --disable-opengl1

RUN make -j$(nproc)
EOF

Pi 4용 Dockerfile (ARM64 + Vulkan)

cat > ~/retroarch-build/docker/pi4/Dockerfile << 'EOF'
FROM --platform=linux/arm64 debian:bookworm

RUN apt-get update && apt-get install -y \
    build-essential git pkg-config \
    libgbm-dev libdrm-dev \
    libegl1-mesa-dev libgles2-mesa-dev \
    libvulkan-dev mesa-vulkan-drivers \
    libasound2-dev libusb-1.0-0-dev \
    libfreetype6-dev libudev-dev \
    libxml2-dev zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /build
COPY . .

RUN ./configure \
    --enable-opengles \
    --enable-opengles3 \
    --enable-opengles3_1 \
    --enable-kms \
    --enable-egl \
    --enable-vulkan \
    --enable-vulkan-display \
    --enable-alsa \
    --enable-udev

RUN make -j$(nproc)
EOF

Pi 5용 Dockerfile (ARM64 + Vulkan 1.2)

cat > ~/retroarch-build/docker/pi5/Dockerfile << 'EOF'
FROM --platform=linux/arm64 debian:bookworm

RUN apt-get update && apt-get install -y \
    build-essential git pkg-config \
    libgbm-dev libdrm-dev \
    libegl1-mesa-dev libgles2-mesa-dev \
    libvulkan-dev mesa-vulkan-drivers \
    libasound2-dev libusb-1.0-0-dev \
    libfreetype6-dev libudev-dev \
    libxml2-dev zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /build
COPY . .

RUN ./configure \
    --enable-opengles \
    --enable-opengles3 \
    --enable-opengles3_1 \
    --enable-opengles3_2 \
    --enable-kms \
    --enable-egl \
    --enable-vulkan \
    --enable-vulkan-display \
    --enable-alsa \
    --enable-udev

RUN make -j$(nproc)
EOF

---

STEP 5: 빌드 실행

Pi 3 빌드

cd ~/retroarch-build

docker build \
  --platform linux/arm/v7 \
  -f docker/pi3/Dockerfile \
  -t retroarch-pi3 \
  ./RetroArch

# 바이너리 추출
docker create --name tmp-pi3 retroarch-pi3
docker cp tmp-pi3:/build/retroarch ./retroarch-pi3
docker rm tmp-pi3

Pi 4 빌드

docker build \
  --platform linux/arm64 \
  -f docker/pi4/Dockerfile \
  -t retroarch-pi4 \
  ./RetroArch

docker create --name tmp-pi4 retroarch-pi4
docker cp tmp-pi4:/build/retroarch ./retroarch-pi4
docker rm tmp-pi4

Pi 5 빌드

docker build \
  --platform linux/arm64 \
  -f docker/pi5/Dockerfile \
  -t retroarch-pi5 \
  ./RetroArch

docker create --name tmp-pi5 retroarch-pi5
docker cp tmp-pi5:/build/retroarch ./retroarch-pi5
docker rm tmp-pi5

---

STEP 6: 한 번에 전부 빌드하는 쉘 스크립트

cat > ~/retroarch-build/build-all.sh << 'EOF'
#!/bin/bash
set -e

echo "=============================="
echo " RetroArch 전체 빌드 시작"
echo "=============================="

TARGETS=("pi3:linux/arm/v7" "pi4:linux/arm64" "pi5:linux/arm64")
OUTPUT_DIR="./output"
mkdir -p $OUTPUT_DIR

for TARGET in "${TARGETS[@]}"; do
  NAME="${TARGET%%:*}"
  PLATFORM="${TARGET##*:}"

  echo ""
  echo ">>> [$NAME] 빌드 시작 (platform: $PLATFORM)"

  docker build \
    --platform $PLATFORM \
    -f docker/$NAME/Dockerfile \
    -t retroarch-$NAME \
    ./RetroArch

  docker create --name tmp-$NAME retroarch-$NAME
  docker cp tmp-$NAME:/build/retroarch $OUTPUT_DIR/retroarch-$NAME
  docker rm tmp-$NAME

  echo ">>> [$NAME] 완료! → $OUTPUT_DIR/retroarch-$NAME"
done

echo ""
echo "=============================="
echo " 전체 빌드 완료!"
ls -lh $OUTPUT_DIR/
echo "=============================="
EOF

chmod +x ~/retroarch-build/build-all.sh

실행

cd ~/retroarch-build
./build-all.sh

---

STEP 7: 파이에 복사해서 실행

# scp로 각 파이에 전송
scp output/retroarch-pi3  pi@<Pi3_IP>:/home/pi/retroarch
scp output/retroarch-pi4  pi@<Pi4_IP>:/home/pi/retroarch
scp output/retroarch-pi5  pi@<Pi5_IP>:/home/pi/retroarch

# 파이에서 실행
chmod +x ~/retroarch
./retroarch --verbose

---

예상 빌드 시간 (PC 성능에 따라 다름)

Pi 3 (ARM32 에뮬레이션)  →  약 30~60분
Pi 4 (ARM64 에뮬레이션)  →  약 20~40분
Pi 5 (ARM64 에뮬레이션)  →  약 20~40분

💡 QEMU 에뮬레이션이라 실제 파이보다 느리지만, Pi 3 네이티브보다는 빠릅니다. PC CPU 코어가 많을수록 make -j$(nproc) 덕분에 빨라집니다.

---

자주 발생하는 에러와 해결법

에러 원인 해결

exec format error	QEMU 미등록	STEP 2 재실행
no space left on device	Docker 디스크 부족	docker system prune -a
configure: error: EGL not found	라이브러리 누락	Dockerfile에 해당 패키지 추가
빌드 중 멈춤	메모리 부족	Docker 메모리 제한 늘리기