259 lines
9.8 KiB
Markdown
259 lines
9.8 KiB
Markdown
# 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 -p phoebus-mcp --bins
|
|
|
|
# Static binary for the live environment:
|
|
RUSTFLAGS="-C target-feature=+crt-static" \
|
|
cargo build --release -p phoebus-installer -p phoebus-mcp --bins --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 -p phoebus-mcp --bins --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 -p phoebus-mcp --bins --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-<stamp>.bundle
|
|
```
|
|
|
|
Restore with `git clone /path/to/phoebus-<stamp>.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`).
|
|
|
|
## User-agent verification
|
|
|
|
Run `node installer/tests/ui/assistant-bridge.test.cjs` for the shipped bridge
|
|
JavaScript lifecycle checks. `installer/tests/vm/user-agent-guest.py` requires a
|
|
normal user in a disposable QEMU/KVM overlay, static companion binaries under
|
|
`/tmp/phoebus-user-bins`, and the harness synthetic passwordless sudo. It tests
|
|
no physical disk or real account credentials. See [USER-AGENTS.md](USER-AGENTS.md).
|