# 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 \ xorriso mtools dosfstools squashfs-tools cpio zstd 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. ## Rust installer The Bash prototype has been retired (see `docs/BASH-MIGRATION.md`); the Rust workspace is the only 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 cp /path/to/phoebus_os/installer-rs/target/x86_64-unknown-linux-gnu/release/phoebus-installer . cp /path/to/phoebus_os/installer/tests/vm/install.sh . 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. Its default VirtIO display uses an absolute USB tablet and unscaled GTK output so visible controls line up with clicks. Use `--graphics gl` to request VirGL acceleration; some QEMU GL viewers have a cursor offset, so use `--graphics 2d` if that occurs. Guest package selection and the limits of window resize are described in `docs/VIRTUAL-MACHINES.md`. ### Debian-Live appliance harness The appliance ISO (`installer/live/build.sh`) boots its own GRUB, so it has its own driver. It is the fastest path to a full install on hosts where the Gentoo LiveGUI ISO is unavailable: ```sh cd installer-rs RUSTFLAGS="-C target-feature=+crt-static" \ cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu cd .. BASE_ISO=/path/to/debian-live-standard.iso installer/live/build.sh # Serve the stage3, config and 0600 secrets (host 10.0.2.2:8000): mkdir -p /path/serve && cd /path/serve cp /path/to/stage3-amd64-systemd-*.tar.xz stage3.tar.xz && sha256sum stage3.tar.xz cp /path/to/installer/tests/vm/appliance-guest.sh . cp /path/to/installer/tests/vm/appliance-test.conf.example test.conf # set STAGE3_SHA256 printf 'phoebus-luks-test' > luks.pw && chmod 600 luks.pw printf 'phoebus-user-test' > user.pw && chmod 600 user.pw python3 -m http.server 8000 --bind 127.0.0.1 qemu-img create -f qcow2 /path/target.qcow2 24G cp /usr/share/OVMF/OVMF_VARS_4M.fd /path/OVMF_VARS.fd OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \ OVMF_VARS=/path/OVMF_VARS.fd \ DISK=/path/target.qcow2 \ ISO=/path/to/installer/live/phoebus-installer-amd64.iso \ python3 installer/tests/vm/appliance-driver.py install # Detached boot (no ISO): DISK=/path/target.qcow2 OVMF_CODE=... OVMF_VARS=... \ python3 installer/tests/vm/appliance-driver.py boot ``` `INSTALL_TIMEOUT` and `CHECKS_TIMEOUT` bound the long steps. A full base install still fetches and merges the Gentoo stage3 and base packages, so it takes tens of minutes. ### 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 mango & # creates wayland-0 grim /tmp/shot.png # proves the compositor renders ``` On a real machine the installer writes `/usr/local/bin/phoebus-session-mango` (and wrapper `/usr/local/bin/phoebus-session`), which starts Mango and DankMaterialShell (providing the bar, app launcher, notifications, lock and idle handling, and Quickshell polkit agent). ### Physical VT / real-seat check (needs a person) The serial harness has no logind seat, so this must be done on real hardware or a seat-providing VM. From a text VT (e.g. `Ctrl+Alt+F3`), log in and run: ```sh /usr/local/bin/phoebus-session ``` Check, in order: 1. `mango` starts and the screen shows the compositor (no `Failed to start a DRM session`). 2. DankMaterialShell (`dms`) starts and the shell bar and notifications appear. 3. Open a terminal: `kitty` (via `Mod+Shift+Return`). Run an X11 app to exercise XWayland (e.g. `xterm` or `env -u WAYLAND_DISPLAY kitty`). 4. Press `Mod+Space` or `Mod+p` to open the launcher spotlight. 5. Check DMS controls for network, audio, and power. 6. Press `Mod+Alt+L` to lock the session and confirm unlock works. 7. Trigger a privilege prompt (e.g. `pkexec true`) and confirm the Quickshell polkit authentication dialog appears. 8. Log out (`Mod+Shift+e`). Confirm all shell and helper processes exit cleanly and the session returns to the VT login. 9. Reboot and confirm the same result. Record the result (date, kernel, GPU, pass/fail per step) in `docs/VM-BOOT-VERIFICATION.md`. A headless wlroots session is not physical-seat verification. ### Mango + DankMaterialShell (canonical desktop) Mango + DankMaterialShell is the canonical desktop: omitting `desktop.profile` selects `mango`. The installer writes GURU's `repos.conf`, installs `dev-vcs/git`, syncs the overlay with `emaint sync -r guru`, and installs Mango, DMS, Quickshell and scenefx with **scoped** `~amd64` keywords. It also installs and enables `greetd` (with `tuigreet`) for authenticated login into `/usr/local/bin/phoebus-session-mango`. To choose a headless/server profile with no desktop, set `DESKTOP_PROFILE='none'`. ```sh /usr/local/bin/phoebus-session-mango # Mango + DMS /usr/local/bin/phoebus-session # wrapper invoking phoebus-session-mango ``` To inspect the resolved effect of the transition before installing, use `emerge --pretend gui-wm/mangowm gui-apps/dankmaterialshell` and review the `~amd64` list; add only reviewed atoms to `/etc/portage/package.accept_keywords/phoebus`. Never run a global `~amd64` switch. **Acceptance is a graphical VM with a real seat.** Headless compositor tests do not qualify. The gates are listed in `docs/VM-BOOT-VERIFICATION.md`; the default was an explicit owner decision and no desktop stability is claimed until they pass. ### Building the live desktop ISO ```sh cd installer-rs RUSTFLAGS="-C target-feature=+crt-static" \ cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu cd .. installer/live/build.sh ``` This builds a rootless Debian testing rootfs with Mango (source build) + DankMaterialShell (pinned release), live autologin, the "Install Phoebus" launcher and a serial/VT recovery console, then splices it into the base Debian-Live ISO. See `installer/live/README.md` for the full description, including the world-traversable `WORKDIR` requirement of the unprivileged user namespace. ## 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 ``` ## Make targets `make help` lists the common tasks. `make context` prints a session briefing (state, roadmap next steps, handoff), `make doctor` checks the host prerequisites, and `make test`, `make check`, `make build`, `make static`, `make hooks`, `make commit MSG="..."`, `make publish`, `make backup`, `make forgejo-init`, `make public` and `make release TAG=...` wrap the rest. ## Continuous integration `.forgejo/workflows/ci.yml` mirrors the local gates (`cargo fmt`, `cargo clippy`, `cargo test`). It runs only once a Forgejo Actions runner is registered for the repository; see Forgejo's documentation for `act_runner`. Until then, run `make test` before pushing. ## Backups The only remotes are self-hosted, so keep off-box copies: ```sh make backup # writes ~/backups/phoebus/phoebus-.bundle ``` Restore with `git clone /path/to/phoebus-.bundle phoebus_os`. ## Quality gates before commit 1. `make test` (`cd installer-rs && cargo test --workspace`) 2. `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets` 3. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes. 4. Commit (see `docs/GIT-WORKFLOW.md`).