# OreBolt OS -- Quickstart

Build and deploy OreBolt OS to a HiFiWalker H2 (or compatible rebadged DAP)
from a fresh Arch Linux host.  ~30 min if toolchain and kernel tree are
pre-staged, ~75 min if building the toolchain from source.

> **Not on Arch?** Stop.  The build pipeline is validated against Arch only.
> Other distros will need porting effort.  See [PREREQUISITES.md](PREREQUISITES.md)
> section 1 for the full dependency rationale.

---

## 0. What you need

| Item | Where | Details |
|---|---|---|
| Arch Linux host (x86_64) | any Arch install | `pacman -Syu` first |
| `mipsel-linux-musl` toolchain | Rockbox prebuilt tarball (recommended) | step 2 below |
| FiiO M3K GPL kernel tree | community mirror or FiiO's GPL download | step 3 below |
| MicroSD card, 2 GB or larger | any | FAT32, single partition |

---

## 1. Host dependencies

```bash
sudo pacman -Syu --needed base-devel git make python3 rsync \
                                    dosfstools e2fsprogs parted file
```

## 2. Cross toolchain

Option A — Rockbox prebuilt (recommended, ~5 min):

```bash
sudo mkdir -p /opt/mipsel-linux-musl
sudo tar xzf rockbox-mips-toolchain-*.tar.gz \
    -C /opt/mipsel-linux-musl --strip-components=1
```

Option B — musl.cc fallback (less tuned, but works):

```bash
wget https://musl.cc/mipsel-linux-musl-cross.tgz -O - | \
    sudo tar xz -C /opt/mipsel-linux-musl --strip-components=1
```

Either way, add to PATH and verify:

```bash
export PATH="/opt/mipsel-linux-musl/bin:$PATH"
echo 'export PATH="/opt/mipsel-linux-musl/bin:$PATH"' >> ~/.bashrc

mipsel-linux-musl-gcc -dumpmachine
# expected output: mipsel-linux-musl
```

## 3. Kernel headers

The FiiO M3K uses the same Ingenic X1000E SoC as the H2, so its GPL kernel
tree is the canonical headers source — no reverse-engineering from Rockbox
needed.  See [HEADERS.md](HEADERS.md) for mirror URLs and the XBurst BSP
fallback path.

```bash
sudo mkdir -p /opt/fiio-m3k-linux
sudo tar xzf fiio_m3k_kernel_*.tar.gz \
    -C /opt/fiio-m3k-linux --strip-components=1

export KERNEL_HEADERS=/opt/fiio-m3k-linux
echo 'export KERNEL_HEADERS=/opt/fiio-m3k-linux' >> ~/.bashrc

make headers-check
# expected output: [OK] kernel headers root: /opt/fiio-m3k-linux
```

## 4. Build

```bash
git clone <your-repo-url> h2-workspace
cd h2-workspace
./build.sh
```

The build script runs eight phases in sequence:

| Phase | What it does |
|---|---|
| 0–1 | Verifies host deps, toolchain, and kernel headers |
| 2 | Workspace integrity check (all modules + headers + scripts present) |
| 3–4 | Creates `overlay/` tree, fixes permissions |
| 5 | Clones LVGL v8.3.11, builds `liblvgl.so`, `h2_test`, all modules, mapper |
| 6 | Builds `liborebolt.a`, regenerates 150-payload HID matrix |
| 7 | Validates all artifacts are MIPS LE ELF; checks bitchat AGPL marker |
| 8 | *(only with `--deploy`)* Copies everything to SD card |

## 5. Verify the build

```
[OK] OREBOLT OS v1.7 BUILD COMPLETE
```

Artifacts you should see on disk:

| Artifact | Path | Notes |
|---|---|---|
| `liblvgl.so` | `overlay/usr/lib/` | LVGL v8.3.11 shared library (MIT) |
| `h2_test` | `overlay/usr/bin/` | Master launcher |
| `retro_input_mapper` | `overlay/usr/bin/` | Gamepad input mapper daemon |
| 17 `*.mod` files | `overlay/apps/` | 16 GPL modules + 1 AGPL bitchat |
| `liborebolt.a` | `./` | Hardware library static archive |
| 150 `.dd` payloads | `overlay/data/payloads/{linux,macos,windows}/` | HID macro matrix |

Confirm a binary is actually MIPS, not accidentally built with host GCC:

```bash
file overlay/usr/bin/h2_test
# expected: ELF 32-bit LSB executable, MIPS, MIPS32 version 1 ...
```

## 6. Deploy to SD card

```bash
# Identify the card (be sure — /dev/sda is usually your system disk)
lsblk -o NAME,SIZE,TYPE,MOUNTPOINT

# Format: single-partition FAT32
sudo umount /dev/sdX1 2>/dev/null || true
sudo parted /dev/sdX --script mklabel msdos
sudo parted /dev/sdX --script mkpart primary fat32 1MiB 100%
sudo parted /dev/sdX --script set 1 boot on
sudo mkfs.vfat -F 32 -n OREBOLT /dev/sdX1

# Mount and deploy
sudo mkdir -p /mnt/h2-sd
sudo mount /dev/sdX1 /mnt/h2-sd

# First deploy: back up stock firmware, then deploy
SD_CARD_MOUNT=/mnt/h2-sd ./build.sh --deploy --backup-stock

# Subsequent deploys (stock backup already exists):
# SD_CARD_MOUNT=/mnt/h2-sd ./build.sh --deploy

sync && sudo umount /mnt/h2-sd && sudo eject /dev/sdX
```

Insert the card, power on the H2.  The LVGL UI boots with all 17 modules
registered.  Init order: `S98retro-input` → `S99broker` (starts
`h2_test`) → `bt_input_daemon.sh` (BLE).

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `[-] Missing toolchain binaries: mipsel-linux-musl-gcc` | `export PATH="/opt/mipsel-linux-musl/bin:$PATH"` |
| `[-] CRITICAL: KERNEL_HEADERS not found` | Install FiiO M3K GPL tree (step 3) |
| `[-] BAD: h2_test -- ELF 64-bit LSB executable, x86-64` | `./build.sh --clean && ./build.sh` (host GCC leaked in) |
| `error: cannot find -lm` | Switch to Rockbox toolchain (step 2, option A) |
| `fatal: unable to access 'https://github.com/lvgl/lvgl.git'` | Pre-clone LVGL manually (see PREREQUISITES.md section 8) |
| `[-] bitchat.mod missing AGPL_BITCHAT marker` | If building manually, add `-DAGPL_BITCHAT` to CFLAGS |

---

## Before deploying bitchat (AGPL obligation)

If you modify the bitchat module and deploy it where other operators will
interact with it over the mesh, AGPL v3 section 13 requires you to provide
your modified source.  Do this before deploying:

```bash
# 1. Replace the placeholder URL with your real source / Written Offer
sed -i 's|https://example.invalid/orebolt-bitchat-src|https://your-domain/orebolt-os-bitchat-src|' \
    src/modules/mod_bitchat_mesh.c

# 2. Drop in the full AGPL license text
curl -o licenses/AGPL-3.0.txt https://www.gnu.org/licenses/agpl-3.0.txt

# 3. Rebuild
./build.sh --clean && ./build.sh
```

Full compliance checklist: [LICENSE.md section 4](LICENSE.md#4-operator-obligations-when-modifying-bitchat).

---

## What to read next

| When you want to... | Read |
|---|---|
| Understand module layout and boot sequence | [ARCHITECTURE.md](ARCHITECTURE.md) |
| Diagnose a toolchain or headers issue | [PREREQUISITES.md section 8](PREREQUISITES.md#8-troubleshooting) |
| Understand the AGPL/GPL split | [LICENSE.md](LICENSE.md) |
| See the full version history | [CHANGELOG.md](CHANGELOG.md) |
| Add a new module | `Makefile` header comment, steps 1–5 |