# How the Build Process Works

`build.sh` iterates through stage directories in alphanumeric order and processes each one.

## Stage Processing

For each stage directory:

1. Skip the stage entirely if a `SKIP` file is present.
2. Run `prerun.sh` — typically copies the rootfs from the previous stage.
3. Iterate through each numbered subdirectory (e.g. `00-configure-apt`, `01-sys-tweaks`) in order.
4. Within each subdirectory, process these files if present:

| File | Description |
|------|-------------|
| `00-run.sh` | Shell script run on the host (must be executable) |
| `00-run-chroot.sh` | Shell script run inside the chroot (must be executable) |
| `00-debconf` | Passed to `debconf-set-selections` |
| `00-packages` | Packages installed via `apt-get install` |
| `00-packages-nr` | Same, but with `--no-install-recommends` |
| `00-packages-<arch>` | Arch-specific packages (e.g. `00-packages-amd64`, `00-packages-arm-only`) |
| `00-packages-nr-<arch>` | Arch-specific packages without recommends |
| `00-patches` | Directory of quilt patches applied to the rootfs |
| `00-patches-<arch>` | Arch-specific quilt patches |

5. If the stage contains `EXPORT_IMAGE`, `EXPORT_ISO`, or `EXPORT_SQUASHFS` (and `SKIP_IMAGES` is not present), add it to the export queue.

## Export Pipeline

After all stages are processed, the build runs the export pipeline for each queued stage:

| Marker file | Export pipeline | Output |
|-------------|----------------|--------|
| `EXPORT_IMAGE` | `export-image/` | `.img` disk image (RPi) |
| `EXPORT_ISO` | `export-iso/` | `.iso` live image (amd64) |
| `EXPORT_SQUASHFS` | `export-squashfs/` | `.squashfs` filesystem archive |

Multiple marker files can coexist in the same stage — all matching exports will run.

### export-iso pipeline

1. `prerun.sh` — rsync rootfs into work dir
2. `01-set-sources` — clean apt caches, run final upgrade
3. `02-network` — configure resolv.conf
4. `03-finalise` — rewrite fstab for live use, generate initramfs, build squashfs, build ISO with `grub-mkrescue`

### export-squashfs pipeline

1. `prerun.sh` — rsync rootfs into work dir
2. `00-finalise` — create squashfs and deploy

## Arch-Specific Logic

Scripts and package files support arch suffixes:
- `-arm-only` — runs on `arm64` and `armhf` only
- `-amd64` — runs on `amd64` only
- `-${ARCH}` — can be any specific arch string

Scripts that handle arch themselves check `${ARCH}` and exit early if not applicable.