docs: compact README, move workflow to CONTRIBUTING
This commit is contained in:
1 parent
2d586f57f7
commit
d789c24dee
2 files changed
+69
-102
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user