# Development ## Host requirements Ubuntu/Debian host names (the development machine is Ubuntu 26.04): ```sh sudo apt install qemu-system-x86 qemu-utils ovmf-generic seabios ipxe-qemu \ dialog xorriso mtools dosfstools squashfs-tools cpio zstd \ shellcheck python3-pexpect # Rust quality gates (names may be versioned; check `apt search rustfmt`) sudo apt install rust-clippy rustfmt # or, if cargo is rustup-managed: # rustup component add rustfmt clippy ``` Optional: `expect`, `cryptsetup`, `btrfs-progs`, `parted`, `kpartx` for offline inspection of VM images. `7z`/`p7zip` is useful for reading the reference ISO. ## Reference media The Gentoo LiveGUI ISO is a **reference artifact**, not source. It is ignored by `.gitignore`. Keep it outside git; point the VM harness at it by path. ## Bash installer ```sh installer/tests/run_tests.sh shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh # Non-interactive, non-destructive: installer/bin/ai-installer --config installer/config/example.conf --plan installer/bin/ai-installer --dry-run --config installer/config/example.conf ``` ## Rust installer ```sh cd installer-rs cargo fmt --all -- --check cargo clippy --workspace --all-targets cargo test --workspace cargo build --release -p phoebus-installer # Static binary for the live environment: RUSTFLAGS="-C target-feature=+crt-static" \ cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu ``` Useful CLI invocations: ```sh target/release/phoebus-installer --config FILE --plan target/release/phoebus-installer --config FILE --dry-run --install target/release/phoebus-installer --config FILE --install --yes \ --luks-passphrase-file /secure/luks.pw --user-password-file /secure/user.pw ``` ## Disposable VM testing Never point the harness at a physical disk. The target is always a qcow2 file. `installer/tests/vm/serial-driver.py` drives QEMU over the serial console: ```sh cd /path/to/serve tar czf installer.tar.gz -C /path/to/phoebus_os installer # or the Rust binary python3 -m http.server 8000 --bind 127.0.0.1 QEMU_BIN=qemu-system-x86_64 \ OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \ OVMF_VARS=/usr/share/OVMF/OVMF_VARS_4M.fd \ DISK=/tmp/phoebus/target.qcow2 \ ISO=/path/to/livegui-*.iso \ KERNEL=/tmp/live/boot/gentoo INITRD=/tmp/live/boot/gentoo.igz \ INSTALL_URL=http://10.0.2.2:8000/install.sh \ python3 installer/tests/vm/serial-driver.py install # Then boot the disk alone (ISO detached): DISK=/tmp/phoebus/target.qcow2 OVMF_CODE=... OVMF_VARS=... \ python3 installer/tests/vm/serial-driver.py boot ``` `installer/tests/vm/run-vm.sh` launches an interactive VM instead. ### Verifying the graphical stack The serial-only VM has no logind seat, so wlroots' DRM backend cannot start there. For headless verification use: ```sh export WLR_BACKENDS=headless WLR_RENDERER=pixman WLR_RENDERER_ALLOW_SOFTWARE=1 dwl & # creates wayland-0 grim /tmp/shot.png # proves the compositor renders ``` On a real machine the installer writes `/usr/local/bin/phoebus-session` (waybar + mako + swaybg + dwl). ## Inspecting the reference ISO without booting ```sh 7z l livegui-*.iso 7z x livegui-*.iso image.squashfs boot/gentoo boot/gentoo.igz unsquashfs -l image.squashfs # file listing unsquashfs -d /tmp/root image.squashfs etc/portage/make.conf ``` ## Quality gates before commit 1. `installer/tests/run_tests.sh` 2. `cd installer-rs && cargo test --workspace` 3. `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets` 4. `shellcheck` on the Bash tree (while it exists) 5. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes. 6. Commit (see `docs/GIT-WORKFLOW.md`).