Adds make help/test/check/build/static/hooks/commit/publish wrapping the documented commands and the git workflow, and links them from DEVELOPMENT.md.
123 lines
3.9 KiB
Markdown
123 lines
3.9 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 \
|
|
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
|
|
```
|
|
|
|
## Make targets
|
|
|
|
`make help` lists the common tasks. `make test`, `make check`, `make build`,
|
|
`make static`, `make hooks`, `make commit MSG="..."` and `make publish` wrap the
|
|
commands above and the git workflow.
|
|
|
|
## 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`).
|