diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d2de60f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributing + +## Workflow + +Work inside the dev shell (`direnv allow` once). Run `cargo clippy +--all-targets` before committing (the crate warns on clippy pedantic plus +`absolute_paths`) and `cargo fmt`, which needs the nightly toolchain for +`rustfmt.toml`. Version control is jj, not the `git` CLI. + +## Testing + +- `cargo test`: model and render snapshot tests. +- `nix run .#demo-units -- start`, then + `cargo run -- --user --target bootvine-demo.target --hold 3s`: live against + your user manager. +- `nix build .#checks.x86_64-linux.boot`: boots a VM and reads the screen with + OCR; screenshots land in `result/`. Run it by hand with + `nix run .#checks.x86_64-linux.boot.driverInteractive`, then `test_script()`. + +Prefix the VM commands with `env -u LD_LIBRARY_PATH` when the shell exports +libraries that clash with QEMU'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: the loop waits on the bus with a timeout, then draws. +- 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. diff --git a/README.md b/README.md index 60522ad..5b20db5 100644 --- a/README.md +++ b/README.md @@ -1,124 +1,52 @@ # bootvine -A live dependency tree of systemd jobs on the boot console, in the spirit of -nix-output-monitor. It replaces the scrolling kernel and systemd lines with a -tree of pending units and a timeline bar per row. +A live tree of systemd jobs on the boot console, in the spirit of +nix-output-monitor. It replaces the scrolling kernel and systemd lines with the +units still pending and a timeline of the ones that ran. -## Requirements +It needs systemd ≥ 246 as PID 1, libdbus and a virtual terminal (it draws on +tty12). With a systemd initrd it starts about a second after the kernel and +follows the boot through the switch to the real root; without one it starts in +stage 2. While it runs it quiets the kernel console and systemd's status +output, and restores both when it hands the console back. -- Linux with **systemd ≥ 246 as PID 1** (private socket `/run/systemd/private`, - `Manager.SetShowStatus`). -- Runs as **root**, from the shipped `bootvine.service`. -- **libdbus-1** at runtime. -- A **virtual terminal** (`CONFIG_VT`); the unit draws on `/dev/tty12`. -- Optional: a **systemd-based initrd** (NixOS `boot.initrd.systemd`, dracut, or - mkinitcpio's `systemd` hook). Without one the tree starts in stage 2, once the - real root is mounted. -- Optional: a large console font on HiDPI screens, e.g. Terminus `ter-v32n` - through the distro's console font setting. +## Try -No kernel parameters are needed: while it runs, bootvine lowers the kernel -console log level and turns systemd's status output off, and restores both when -it hands the console over. - -## How it works - -- Starts as an initrd unit when the initrd runs systemd, about a second after - the kernel. -- Talks to PID 1 over the private socket `/run/systemd/private` with libdbus: - `Subscribe`, `ListJobs`, unit properties, and the `JobNew`/`JobRemoved`/ - `PropertiesChanged` signals. -- Survives the switch to the real root: its `argv[0]` starts with `@`, the unit - ignores isolate, and it chroots into `/sysroot` before PID 1 re-executes, then - reconnects. Plymouth does the same with `plymouth update-root-fs`. -- Draws on its own virtual terminal (tty12 by default) and switches back to the - previous one when the display manager starts or the default target is - reached, so gettys and greeters on tty1 cannot draw over it. - -## Installing - -The package ships everything a system needs under `lib/`: - -| File | Purpose | -| --- | --- | -| `lib/systemd/system/bootvine.service` | the unit, used in both the initrd and stage 2 | -| `lib/dracut/modules.d/90bootvine/` | dracut module | -| `lib/initcpio/install/sd-bootvine` | mkinitcpio hook | - -### NixOS - -```nix -inputs.bootvine.url = "git+https://codeberg.org/wvhulle/bootvine"; -# in the host's modules: -bootvine.nixosModules.default -{ services.bootvine.enable = true; } +```sh +cargo run --example demo ``` -With `boot.initrd.systemd.enable` the unit is added to the initrd as well. +plays a scripted boot without systemd; `q` quits. `nix run .#vm` boots a demo +VM in a window. -### Other distributions +## Install -1. Install `bootvine` to `/usr/bin` and the files above under `/usr/lib`. -2. `systemctl enable bootvine.service`. -3. To start it in the initrd: - - dracut: `add_dracutmodules+=" bootvine "` in `/etc/dracut.conf.d/bootvine.conf`, - then `dracut --force`; - - mkinitcpio: add `sd-bootvine` after `systemd` in `HOOKS`, then - `mkinitcpio -P`. +On NixOS, import `nixosModules.default` from the flake and set +`services.bootvine.enable = true`. With `boot.initrd.systemd.enable` the unit +goes into the initrd as well. -To draw on another terminal, override `TTYPath=` with -`systemctl edit bootvine.service`. +Elsewhere, install the binary to `/usr/bin` and the package's `lib/` under +`/usr/lib`, then `systemctl enable bootvine.service`. To start it in the +initrd, add `bootvine` to `add_dracutmodules` (dracut) or `sd-bootvine` after +`systemd` in `HOOKS` (mkinitcpio), and rebuild the initramfs. -## Configuration +## Configure -Colours come from `/etc/bootvine.toml` (another path with `--config`). Every -key is optional; these are the defaults: +`/etc/bootvine.toml`, or `services.bootvine.palette` on NixOS. Every key is +optional; these are the defaults: ```toml [palette] -text = "white" # running units, headings -muted = "dark-gray" # rules, tree lines, axis -waiting = "gray" # queued units, finished-unit labels +text = "white" +muted = "dark-gray" +waiting = "gray" running = "yellow" done = "green" failed = "light-red" target = "cyan" ``` -Values are the 16 console colour names (`red`, `light-red`, `dark-gray`, …). -The Linux console cannot show other colours, so to change what the names look -like, set the console palette itself. That recolours every virtual terminal from -the start of boot: - -- NixOS: `console.colors = [ "1d2021" "fb4934" … ];` (16 hex values); -- elsewhere: the kernel parameters `vt.default_red=`, `vt.default_grn=` and - `vt.default_blu=`. - -On NixOS set the roles as options; unset ones keep their defaults: - -```nix -services.bootvine.palette = { - running = "light-yellow"; - done = "light-green"; -}; -``` - -On dracut and mkinitcpio systems the hooks copy `/etc/bootvine.toml` into the +Values are the 16 console colour names. To change how those look, set the +console palette: `console.colors` on NixOS, or the `vt.default_red`, `_grn` and +`_blu` kernel parameters elsewhere. The initrd hooks copy the file into the initramfs, so rebuild it after editing. - -## Testing - -Commands assume the dev shell is active (`direnv allow` once; `.envrc` runs -`use flake`). - -| What | Command | -| --- | --- | -| Unit and render snapshot tests | `cargo test` | -| Scripted boot animation, no systemd needed | `cargo run --example demo` (`q` quits) | -| Live against your user manager | `nix run .#demo-units -- start`, then `nix run . -- --user --target bootvine-demo.target --hold 3s` | -| Boot a demo VM in a window | `env -u LD_LIBRARY_PATH nix run .#vm` | -| Automated boot test with OCR | `nix build .#checks.x86_64-linux.boot` (screenshots in `result/`) | -| Same test, interactively | `nix run .#checks.x86_64-linux.boot.driverInteractive`, then `test_script()` | - -`env -u LD_LIBRARY_PATH` is only needed when the shell exports libraries that -clash with QEMU's.