# 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)

```bash
# 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`:

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

## Building

### Native (x86_64)

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

### ARM64 Cross-Compilation

```bash
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

```bash
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:

```bash
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:
```bash
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:
```bash
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 |