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
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.