Files
bootvine/CONTRIBUTING.md
T

74 lines
3.4 KiB
Markdown

# Contributing
## Workflow
Work inside the dev shell (`direnv allow` once). Run `cargo clippy --workspace
--all-targets` before committing (the workspace warns on clippy pedantic plus
`absolute_paths`) and `cargo fmt --all`, which needs the nightly toolchain for
`.rustfmt.toml`. Version control is jj, not the `git` CLI.
The workspace has two crates: `bootvine` itself and `xtask`, the repository
tasks behind `cargo xtask` (`record-screencasts`, `install`, `uninstall`).
## Testing
Everything that boots a machine or a service manager lives under `tests/`:
`tests/sample-machine/` holds the sample host, its slow and failing sample units
and the interactive VM; `tests/vm-checks/` holds the NixOS tests that boot it.
- `cargo test --workspace`: model and render snapshot tests.
- Live against your user manager, with the sample units:
```sh
units=$(nix build --no-link --print-out-paths .#sample-unit-files)
systemctl --user link --runtime $units/*
systemctl --user start --no-block bootvine-demo.target
cargo run -- --user --target bootvine-demo.target --hold 3s
systemctl --user stop $(ls $units)
systemctl --user disable --runtime $(ls $units)
```
- `nix run .#sample-machine-vm`: the sample host in a QEMU window. Its disk
image goes to `~/.cache/bootvine-sample-machine.qcow2`.
- `nix build .#checks.x86_64-linux.<name>`: each `tests/vm-checks/<test>.nix`
boots a VM and runs `console.py` followed by `<test>.py`.
`vm-boot-and-shutdown` follows the initrd, stage 2 and a poweroff;
`vm-luks-passphrase` answers a passphrase prompt in the initrd. They read
tty12 as text from `/dev/vcsu12`, hold the boot with the initrd backdoor and
gate files under `/run` instead of sleeping. Run one by hand with
`nix run .#checks.x86_64-linux.vm-boot-and-shutdown.driverInteractive`, then
`test_script()`.
- `nix run .#record-screencasts`, from the repository root: runs
`cargo xtask record-screencasts`, which records `recordings/boot.tape` and
`recordings/shutdown.tape` with VHS against the scripted examples into the README
GIFs and copies the passphrase screenshot from the `vm-luks-passphrase` check.
- `cargo xtask install --destdir <dir> --initrd dracut`: stages an install
without touching the system; `cargo xtask uninstall --destdir <dir>` empties
it again.
Prefix the VM and VHS commands with `env -u LD_LIBRARY_PATH` when the shell
exports libraries that clash with QEMU's or Chromium's.
## Conventions
- No comments or doc comments; intent lives in names and call flow.
- Pub fields instead of getters, `Duration` instead of raw integers, crates
instead of hand-written formatting.
- One thread, Elm-style: a tokio current-thread runtime merges streams of
`ScreenInput` (the bus as `BootChange` batches, keys, frame ticks, full
repaints, the ask-password inotify watch, SIGTERM) with `stream::select`,
and one owned `WatchScreen` absorbs each ready batch and draws once. The
live boot and the scripted demos share this loop and differ only in their
console desk.
- Ratatui views are built declaratively from iterators.
## systemd's private socket
- zbus rejects it: PID 1 sends as `org.freedesktop.systemd1`, not a unique
name. libdbus works.
- libdbus pipelines `BEGIN` with the first message and sd-bus leaves it unread,
so a no-reply `Ping` goes out right after connecting.
- Surviving switch-root needs `argv[0]` starting with `@`, `IgnoreOnIsolate`,
and a chroot through an fd to `/sysroot` taken when
`initrd-switch-root.service` is queued.