BifrOSt

Latest change 2470f865b919f6a226354bc329a8ee630f90cd70 - Fix black-screen boot by normalizing installed /etc permissions by Ólafur Búi Ólafsson

# Build the ISO

`build-iso.sh` builds the BifrOSt live/install ISO from a repository checkout.
It wraps `mkarchiso` with the project's required pre-build steps so a build
either produces a complete, installable image or fails with a clear reason.

Builds run on Titan, never on a laptop. `mkarchiso` requires root, so run the
script with `sudo`. Scratch and output land under the repository's `.tmp/`
directory per the workspace temporary-work policy.

## Prerequisites

Install the official build and VM tools:

```bash
sudo pacman -S --needed archiso qemu-desktop edk2-ovmf
```

The checkout must already carry a verified installer package seed under
`profile/airootfs/usr/share/bifrost/installer-cache/` (with `manifest.json`) and
staged release metadata. The tracked profile ships both; `prepare-installer-cache.py`
rebuilds the seed when needed.

## Quick build

From the repository root:

```bash
sudo ./build-iso.sh
```

On success the script prints the finished ISO path, size, and SHA-256, for
example `.tmp/iso-out/bifrost-<version>-x86_64.iso`.

## Options

```
-w, --work-dir DIR         Scratch build directory (default: .tmp/iso-work)
-o, --out-dir DIR          ISO output directory (default: .tmp/iso-out)
-p, --profile DIR          archiso profile directory (default: profile)
    --source-revision REV  Restage installed release metadata for REV (40/64 hex)
    --source-date-epoch N  Epoch for metadata restaging (default: REV commit time)
    --skip-validate        Skip validate-build.py (not recommended)
    --keep-work            Keep the scratch work directory after building
-h, --help                 Show help and exit
```

## Pipeline

1. **Verify the installer seed** — `prepare-installer-cache.py --require` fails
   if the seed manifest is absent or invalid. A verified seed is mandatory
   before an ISO build so offline installs have every required package archive.
2. **Restage release metadata (optional)** — with `--source-revision`, runs
   `generate-release-metadata.py --prepare-installed` to rewrite the installed
   system's `release.json`. The tracked profile already carries staged metadata,
   so this is only needed when cutting a new revision. Without a signing key the
   evidence is explicitly unsigned local development metadata.
3. **Validate** — `validate-build.py` checks profile layout, airootfs hygiene
   (no interpreter caches, no `.github`), tracked sources, and the release
   contract. Use `--skip-validate` only for throwaway experiments.
4. **Build** — `mkarchiso -v -r -w <work> -o <out> <profile>` produces the ISO.
5. **Report** — prints the ISO path, size, and SHA-256.

## Post-build verification

Build success is not installation or hardware qualification. Exercise the image
with the [QEMU test plan](qemu-test-plan.md) for both the standard and encrypted
release-candidate installs: install, power off, detach the ISO, cold-boot the
installed disk, and confirm it reaches the COSMIC greeter. The installer resets
the base hierarchy to world-traversable modes during `postinstall`; a cold boot
that stops at a black screen indicates that step regressed.

## Notes

- The profile consumes current official Arch repositories unless a separately
  validated complete local source is supplied, so two builds from the same
  source revision are not claimed to be bit-for-bit reproducible.
- Secure Boot is unsupported; disable it before booting the image.