docs: compact README, move workflow to CONTRIBUTING

This commit is contained in:
Willem Vanhulle committed 2026-10-11 15:59:48 +02:00
1 parent 2d586f57f7
commit d789c24dee
2 files changed
+69 -102

No files matched your search

+39
View File
@@ -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.
+30 -102
View File
@@ -1,124 +1,52 @@
# bootvine # bootvine
A live dependency tree of systemd jobs on the boot console, in the spirit of 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 a nix-output-monitor. It replaces the scrolling kernel and systemd lines with the
tree of pending units and a timeline bar per row. 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`, ## Try
`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.
No kernel parameters are needed: while it runs, bootvine lowers the kernel ```sh
console log level and turns systemd's status output off, and restores both when cargo run --example demo
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; }
``` ```
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`. On NixOS, import `nixosModules.default` from the flake and set
2. `systemctl enable bootvine.service`. `services.bootvine.enable = true`. With `boot.initrd.systemd.enable` the unit
3. To start it in the initrd: goes into the initrd as well.
- 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`.
To draw on another terminal, override `TTYPath=` with Elsewhere, install the binary to `/usr/bin` and the package's `lib/` under
`systemctl edit bootvine.service`. `/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 `/etc/bootvine.toml`, or `services.bootvine.palette` on NixOS. Every key is
key is optional; these are the defaults: optional; these are the defaults:
```toml ```toml
[palette] [palette]
text = "white" # running units, headings text = "white"
muted = "dark-gray" # rules, tree lines, axis muted = "dark-gray"
waiting = "gray" # queued units, finished-unit labels waiting = "gray"
running = "yellow" running = "yellow"
done = "green" done = "green"
failed = "light-red" failed = "light-red"
target = "cyan" target = "cyan"
``` ```
Values are the 16 console colour names (`red`, `light-red`, `dark-gray`, …). Values are the 16 console colour names. To change how those look, set the
The Linux console cannot show other colours, so to change what the names look console palette: `console.colors` on NixOS, or the `vt.default_red`, `_grn` and
like, set the console palette itself. That recolours every virtual terminal from `_blu` kernel parameters elsewhere. The initrd hooks copy the file into the
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
initramfs, so rebuild it after editing. 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.