Adds the documentation a new session needs: AGENTS.md (read-first contract), docs/OBJECTIVES.md, ROADMAP.md, STATUS.md, ARCHITECTURE.md, DEVELOPMENT.md, CONTRIBUTING.md, GIT-WORKFLOW.md and CHANGELOG.md. STATUS.md records an honest implemented/unit-tested/VM-verified matrix and known limitations.
3.6 KiB
Development
Host requirements
Ubuntu/Debian host names (the development machine is Ubuntu 26.04):
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
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
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:
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:
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:
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
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
installer/tests/run_tests.shcd installer-rs && cargo test --workspacecargo fmt --all -- --checkandcargo clippy --workspace --all-targetsshellcheckon the Bash tree (while it exists)- Update
docs/CHANGELOG.mdanddocs/STATUS.mdwhen behavior changes. - Commit (see
docs/GIT-WORKFLOW.md).