From 1dfdee7ae102868812988cdb2c84f9ad3a12f573 Mon Sep 17 00:00:00 2001
From: commander <danny@gositeme.com>
Date: Tue, 7 Apr 2026 15:46:04 -0400
Subject: [PATCH] docs: ARM64 build investigation

---
 docs/ARM64_BUILD_INVESTIGATION.md | 128 ++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 docs/ARM64_BUILD_INVESTIGATION.md

diff --git a/docs/ARM64_BUILD_INVESTIGATION.md b/docs/ARM64_BUILD_INVESTIGATION.md
new file mode 100644
index 0000000..ca323c4
--- /dev/null
+++ b/docs/ARM64_BUILD_INVESTIGATION.md
@@ -0,0 +1,128 @@
+# Alfred Linux — ARM64 Build Investigation
+
+## Executive Summary
+- ✅ Cross-compilation possible but **native ARM64 builds recommended for production**
+- Each target differs: Generic ARM64 UEFI, Raspberry Pi, Apple Silicon = separate boot chains
+- **Effort**: 4–8h (generic ARM64), 8–16h (RPi), 20–40h (Apple Silicon)
+- **Recommendation**: Start with native ARM64 build server, generic ARM64 first; defer Apple Silicon
+
+---
+
+## 1. Cross-Compilation vs Native Builds
+
+| Factor | Cross-Compile (x86_64) | Native (ARM64) |
+|--------|------------------------|-----------------|
+| Speed | 3–5× slower (QEMU) | 1× baseline |
+| Reliability | Potential edge cases | Most reliable |
+| Setup | Moderate (qemu-user-static) | Simple |
+| Cost | $0 (use existing server) | €10–500/mo (Hetzner ARM64 VPS) |
+| Best for | Experimentation | Production releases |
+
+**Recommendation: Native ARM64 build server** (Hetzner CAX21 ~€10/mo)
+
+---
+
+## 2. Boot Methods by Target
+
+### Generic ARM64 (UEFI servers/laptops)
+- **Boot**: UEFI firmware → GRUB2 EFI → kernel
+- **Package**: `grub-efi-arm64`
+- **Complexity**: Medium
+- **live-build**: `--bootloader grub-efi-arm64 --arch arm64`
+
+### Raspberry Pi 4/5
+- **Boot**: GPU firmware → EEPROM → config.txt → kernel
+- **Packages**: `raspberrypi-kernel`, `raspberrypi-bootloader`, `raspberrypi-firmware`
+- **Image**: `.img` (NOT ISO) — FAT32 boot + ext4 root
+- **Complexity**: High
+
+### Apple Silicon
+- **Boot**: Asahi Linux m1n1 → custom kernel
+- **Status**: NOT in mainline Debian
+- **Recommendation**: **Defer to v2.2+**
+
+---
+
+## 3. Implementation Plan
+
+### Phase 1: Generic ARM64 (Week 1, 4–8 hours)
+
+1. Add `--arch arm64` parameter to `build-unified.sh`
+2. Conditional bootloader: GRUB-EFI for ARM64, syslinux for x86
+3. Create `9999-arm64-efi-grub.hook.binary`
+4. Test on native ARM64 server
+5. Publish ARM64 ISO
+
+```bash
+# build-unified.sh additions
+ARCH="${1:-amd64}"
+if [[ "$ARCH" == "arm64" ]]; then
+    LB_BOOTLOADER="grub-efi-arm64"
+    LB_KERNEL_FLAVOUR="generic"
+fi
+```
+
+### Phase 2: Raspberry Pi (Week 2–3, 8–16 hours)
+
+1. Add `--target rpi5` parameter
+2. RPi firmware hook + config.txt generation
+3. `.img` output instead of ISO (`--image-type hdd`)
+4. Test on Pi 5 hardware
+5. RPi installation guide on alfredlinux.com/docs
+
+### Phase 3: CI/CD (Week 3–4)
+
+1. Permanent ARM64 build server
+2. Nightly builds via cron
+3. Auto-upload to alfredlinux.com
+4. Multi-arch download page
+
+---
+
+## 4. Effort Estimates
+
+| Target | Hours | Prerequisites | Status |
+|--------|-------|--------------|--------|
+| Generic ARM64 UEFI | 4–8 | GRUB-EFI knowledge, ARM64 server | Ready to start |
+| Raspberry Pi 4/5 | 8–16 | RPi hardware, firmware blobs | Phase 2 |
+| Apple Silicon | 20–40+ | Asahi Linux partnership | Deferred |
+| CI/CD pipeline | 6–12 | ARM64 server, testing infra | Phase 3 |
+
+---
+
+## 5. Checklist
+
+### Phase 1: Generic ARM64
+- [ ] Update build-unified.sh for `--arch arm64`
+- [ ] Add GRUB-EFI ARM64 conditional
+- [ ] Create ARM64 binary hook
+- [ ] Test on ARM64 server
+- [ ] Publish test ISO
+
+### Phase 2: Raspberry Pi
+- [ ] Add `--target rpi5` support
+- [ ] RPi firmware hook
+- [ ] .img partition layout
+- [ ] Test on Pi 5 hardware
+- [ ] RPi docs page
+
+### Phase 3: Automation
+- [ ] ARM64 build server setup
+- [ ] Nightly build cron
+- [ ] Auto-upload pipeline
+- [ ] Multi-arch download page
+
+---
+
+## 6. Release Plan
+
+| Release | Architecture | Boot | Format |
+|---------|-------------|------|--------|
+| v2.0 RC3 | x86_64 | BIOS (syslinux) | ISO |
+| v2.0 RC4+ | x86_64 + ARM64 | BIOS + UEFI | ISO |
+| v2.1 | + Raspberry Pi | RPi firmware | .img |
+| v2.2+ | + Apple Silicon (maybe) | Asahi m1n1 | TBD |
+
+---
+
+**Status:** Ready for Phase 1 | Updated: April 6, 2026