residual os build scripts

Trimmed fork of Alpine's aports — scripts/ only, no upstream package trees, CI, or license (none exists upstream).

Contents

• scripts/ — mkimage.sh + mkimg.base.sh (load-bearing); mkimg.standard.sh and genapkovl-dhcp.sh kept as reference only, everything ARM/Xen/U-Boot/ netboot/minirootfs-specific dropped (irrelevant to an x86_64 ISO). Our own mkimg.residual*.sh profiles live here too — mkimage.sh discovers every mkimg.*.sh in its own directory, so there's no separate profiles dir or copy step, just one mount.
• Dockerfile.mkimage / compose.yml / entrypoint.sh — the build pipeline. No git clone of aports at build time; scripts/ is vendored directly, so builds are hermetic.
• residual/ — residual's own package tree, no packages ported yet
• .forgejo/workflows/lint.yml — advisory shellcheck pass over scripts/
• .githooks/ — APKBUILD checksum + commit-prefix hooks

Build targets and partitioning

x86_64 ISO (residual, residual_virt)

Produces a bootable ISO with GRUB/EFI + ISOLINUX for x86_64 machines.

ISO9660 filesystem
├── boot/
│   ├── vmlinuz-lts (or vmlinuz-virt)
│   ├── initramfs-lts
│   ├── modloop-lts
│   ├── grub/         (EFI payload + config)
│   └── syslinux/     (BIOS payload + config)
├── apks/             (diskless package repository)
└── .alpine-release

Boot flow:

1. GRUB/ISOLINUX loads the kernel and initramfs.
2. Alpine initramfs mounts the ISO squashfs as the read-only root.
3. Persistence is optional and will be layered later via an overlayfs hook (init/residual-init → to be renamed residual-initramfs).

AArch64 Raspberry Pi (residual_rpi)

Produces a compressed SD-card image (residual-rpi-*.img.gz) for Pi 3B+, 4, 5, and Zero 2 W.

/dev/mmcblk0
├── p1  FAT32   ~256 MB   label=RPI-BOOT
│       Raspberry Pi firmware, config.txt, cmdline.txt,
│       boot/vmlinuz-rpi, boot/initramfs-rpi, boot/dtbs-rpi/
├── p2  btrfs     1 GB    label=RESIDUAL-OS
│       @base subvolume — read-only root filesystem
└──     unpartitioned free space
        (reserved for future RESIDUAL-PERSIST overlay partition)

Boot flow (v1 — no custom overlay hook yet):

1. Raspberry Pi firmware reads config.txt and loads the kernel + initramfs.
2. The initramfs loads the btrfs module and runs btrfs device scan to discover LABEL=RESIDUAL-OS.
3. overlaytmpfs=yes in cmdline.txt gives a writable tmpfs overlay for the current session; changes are lost on reboot.

Serial console is off by default. To enable it, add enable_uart=1 to usercfg.txt on the FAT32 boot partition and append console=ttyAMA0,115200 to cmdline.txt.

Long-term flow (persistence work):

1. Firmware loads kernel + initramfs.
2. Custom residual-initramfs hook locates the base OS and persistence backend (internal SD card partition, external USB drive, or qcow2 file).
3. Overlayfs is mounted with the btrfs persistence partition as the upper layer.

Building

# x86_64 ISO profiles
PROFILE=residual_virt docker compose run --rm mkimage   # ~78MB, virt kernel, fast iteration
PROFILE=residual docker compose run --rm mkimage         # ~360MB, lts kernel, ships

# AArch64 Raspberry Pi image
PROFILE=residual_rpi ARCH=aarch64 docker compose run --rm mkimage

Status

• x86_64 ISO pipeline works end-to-end.
• AArch64 Raspberry Pi image pipeline is under construction; the first bootable image (read-only base OS + tmpfs overlay) is the current milestone.
• Not yet migrated from os-old/: the res-os persistence CLI (Go), overlayfs/rootfs overlay content, and init/residual-init (to be renamed residual-initramfs).

See docs/os/os.md and the workspace-root AGENTS.md.

Git hooks

git config --local core.hooksPath .githooks

Guidelines

• Coding style — APKBUILD conventions
• Commit style — commit message conventions