archy/docs/arm64-build.md

ARM64 (aarch64) Cross-Compilation Guide

Overview

Archipelago supports both x86_64 and ARM64 (aarch64) platforms. The backend is compiled natively on x86_64 and cross-compiled for ARM64 targets like Raspberry Pi 5.

Prerequisites

On the Build Server (Debian 12)

# 1. Add the ARM64 Rust target
rustup target add aarch64-unknown-linux-gnu

# 2. Install the cross-linker and C library
sudo apt update
sudo apt install -y gcc-aarch64-linux-gnu libc6-dev-arm64-cross

# 3. Install cross-compilation OpenSSL headers (for reqwest/hyper TLS)
sudo apt install -y libssl-dev:arm64
# If the above fails (no multiarch), use vendored OpenSSL instead:
# Set OPENSSL_STATIC=1 and add openssl = { version = "0.10", features = ["vendored"] }

Cargo Configuration

The cross-compilation config is at core/.cargo/config.toml:

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

Building

Native (x86_64)

cd core
cargo build --release -p archipelago
# Output: core/target/release/archipelago

ARM64 Cross-Compilation

cd core

# Option A: System OpenSSL (requires libssl-dev:arm64)
PKG_CONFIG_ALLOW_CROSS=1 \
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig \
cargo build --release --target aarch64-unknown-linux-gnu -p archipelago

# Output: core/target/aarch64-unknown-linux-gnu/release/archipelago

# Option B: Vendored OpenSSL (no system packages needed)
OPENSSL_STATIC=1 \
cargo build --release --target aarch64-unknown-linux-gnu -p archipelago

Verify the Binary

file core/target/aarch64-unknown-linux-gnu/release/archipelago
# Should show: ELF 64-bit LSB pie executable, ARM aarch64, ...

Using cross (Alternative)

The cross tool uses Docker containers for hermetic cross-compilation:

cargo install cross

# Build for ARM64 (downloads a Docker image with all dependencies)
cross build --release --target aarch64-unknown-linux-gnu -p archipelago

This is the simplest approach and avoids installing system cross-compilation packages.

Troubleshooting

cannot find -lssl / cannot find -lcrypto

OpenSSL headers for ARM64 are missing. Either:

• Install libssl-dev:arm64 (requires multiarch support)
• Use vendored OpenSSL: set OPENSSL_STATIC=1
• Add openssl = { version = "0.10", features = ["vendored"] } to Cargo.toml

cc: error: unrecognized command-line option

The wrong linker is being used. Verify aarch64-linux-gnu-gcc is installed:

which aarch64-linux-gnu-gcc
aarch64-linux-gnu-gcc --version

Exec format error when running

You're trying to run an ARM64 binary on x86_64. Use qemu-aarch64-static for testing:

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

Target Hardware

Device	Arch	Status
Raspberry Pi 5	aarch64	Primary ARM target
Raspberry Pi 4	aarch64	Supported
Rock Pi 4	aarch64	Untested
Orange Pi 5	aarch64	Untested
x86_64 NUC/Mini PC	x86_64	Primary platform