docs: GIFs and install steps

This commit is contained in:
Willem Vanhulle committed 2026-10-14 21:27:50 +02:00
1 parent b0521193a4
commit 5e4ce012f4
10 files changed
+152 -69

No files matched your search

+97 -10
View File
@@ -5,7 +5,7 @@ nix-output-monitor. It replaces the scrolling kernel and systemd lines with the
units still pending and, in the room the tree leaves, a timeline of the slowest
ones that ran.
![A boot through the initrd into stage 2, with one failed unit](docs/boot.gif)
<img src="docs/boot.gif" width="691" alt="A boot through the initrd into stage 2, with one failed unit">
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
@@ -19,7 +19,7 @@ It also follows shutdowns and reboots: the units being stopped, nested under
the units that have to stop first, until systemd hands over to
`systemd-shutdown`.
![A poweroff: units stopping under the targets waiting on them](docs/shutdown.gif)
<img src="docs/shutdown.gif" width="691" alt="A poweroff: units stopping under the targets waiting on them">
## Try
@@ -33,15 +33,102 @@ VM in a window.
## Install
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.
### NixOS
Elsewhere, install the binary to `/usr/bin` and the package's `lib/` under
`/usr/lib`, then `systemctl enable bootvine.service bootvine-shutdown.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.
1. Add the flake to your system flake's inputs and pass its module in:
```nix
{
inputs.bootvine = {
url = "git+https://codeberg.org/wvhulle/bootvine";
inputs.nixpkgs.follows = "nixpkgs";
};
outputs = { nixpkgs, bootvine, ... }: {
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
modules = [
bootvine.nixosModules.default
./configuration.nix
];
};
};
}
```
2. Enable it in `configuration.nix`:
```nix
{
services.bootvine.enable = true;
}
```
3. Optionally, follow the boot from the initrd and keep early kernel messages
to errors:
```nix
{
boot.initrd.systemd.enable = true;
boot.consoleLogLevel = 3;
}
```
4. Rebuild and reboot:
```sh
sudo nixos-rebuild switch --flake .#my-host
```
### Ubuntu
1. Install the build dependencies and Rust. The repository pins a nightly
toolchain in `rust-toolchain.toml`, which rustup fetches on the first
build:
```sh
sudo apt install build-essential pkg-config libdbus-1-dev git curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
2. Build:
```sh
git clone https://codeberg.org/wvhulle/bootvine.git
cd bootvine
cargo build --release
```
3. Install the binary and the systemd units, and enable them:
```sh
sudo install -Dm755 target/release/bootvine /usr/bin/bootvine
sudo install -Dm644 -t /usr/lib/systemd/system \
packaging/systemd/bootvine.service packaging/systemd/bootvine-shutdown.service
sudo systemctl enable bootvine.service bootvine-shutdown.service
```
This is enough for bootvine to show stage 2 and shutdown.
4. Optionally, follow the boot from the initrd. This needs a dracut initramfs
with systemd in it; initramfs-tools has no systemd, so on releases that use
it bootvine starts in stage 2 only.
```sh
sudo install -Dm755 packaging/dracut/90bootvine/module-setup.sh \
/usr/lib/dracut/modules.d/90bootvine/module-setup.sh
echo 'add_dracutmodules+=" bootvine "' | sudo tee /etc/dracut.conf.d/bootvine.conf
sudo dracut --force
```
5. Reboot.
### Other distributions
Install the binary and units as in the Ubuntu steps. For the initrd, use the
dracut module as above, or on mkinitcpio install
`packaging/mkinitcpio/install/sd-bootvine` to `/usr/lib/initcpio/install/`, add
`sd-bootvine` after `systemd` in `HOOKS` in `/etc/mkinitcpio.conf`, and run
`sudo mkinitcpio -P`.
## Configure
+2 -2
View File
@@ -24,10 +24,10 @@
testScript = ''
machine.start()
machine.wait_for_text("initrd")
machine.wait_for_text("Initrd")
machine.screenshot("initrd")
machine.wait_for_text("stage 2")
machine.wait_for_text("Stage 2")
machine.screenshot("stage-2")
quieted = machine.succeed("cut -f1 /proc/sys/kernel/printk").strip()
assert quieted == "1", f"stage 2 sysctl reopened the kernel console: {quieted}"
+2 -1
View File
@@ -11,7 +11,8 @@ depends() {
install() {
inst_binary bootvine
inst_simple "$systemdsystemunitdir/bootvine.service" if [[ -f /etc/bootvine.toml ]]; then
inst_simple "$systemdsystemunitdir/bootvine.service"
if [[ -f /etc/bootvine.toml ]]; then
inst_simple /etc/bootvine.toml
fi
$SYSTEMCTL -q --root "$initdir" enable bootvine.service
+2 -1
View File
@@ -2,7 +2,8 @@
build() {
add_binary bootvine
add_systemd_unit bootvine.service if [[ -f /etc/bootvine.toml ]]; then
add_systemd_unit bootvine.service
if [[ -f /etc/bootvine.toml ]]; then
add_file /etc/bootvine.toml
fi
add_symlink /usr/lib/systemd/system/sysinit.target.wants/bootvine.service \
+16 -16
View File
@@ -17,10 +17,10 @@ impl Phase {
#[must_use]
pub fn label(self) -> &'static str {
match self {
Self::Initrd => "initrd",
Self::Host => "stage 2",
Self::User => "user",
Self::Shutdown => "shutdown",
Self::Initrd => "Initrd",
Self::Host => "Stage 2",
Self::User => "User",
Self::Shutdown => "Shutdown",
}
}
}
@@ -197,15 +197,15 @@ impl UnitKind {
pub fn tag(self) -> &'static str {
match self {
Self::Service | Self::Target | Self::Other => "",
Self::Socket => "socket",
Self::Mount => "mount",
Self::Automount => "automount",
Self::Device => "device",
Self::Swap => "swap",
Self::Path => "path",
Self::Timer => "timer",
Self::Slice => "slice",
Self::Scope => "scope",
Self::Socket => "Socket",
Self::Mount => "Mount",
Self::Automount => "Automount",
Self::Device => "Device",
Self::Swap => "Swap",
Self::Path => "Path",
Self::Timer => "Timer",
Self::Slice => "Slice",
Self::Scope => "Scope",
}
}
@@ -578,7 +578,7 @@ impl BootState {
let remaining = succeeded.len() - walk.consumed + self.finished_before_reconnect;
if remaining > 0 {
walk.rows.push(MilestoneRow {
label: "finished".to_owned(),
label: "Finished".to_owned(),
finished_units: remaining,
started_at: walk.previous,
reached_at: None,
@@ -1146,7 +1146,7 @@ mod tests {
fn kinds_with_a_tag_drop_their_suffix() {
let socket = facts("docker.socket", &[]);
assert_eq!(UnitKind::of(&socket.name), UnitKind::Socket);
assert_eq!(UnitKind::Socket.tag(), "socket");
assert_eq!(UnitKind::Socket.tag(), "Socket");
assert_eq!(display_label(&socket), "docker");
assert_eq!(display_label(&facts("sshd.service", &[])), "sshd");
assert_eq!(display_label(&facts("basic.target", &[])), "basic.target");
@@ -1337,7 +1337,7 @@ mod tests {
assert_eq!(
state.finished_stages,
[FinishedStage {
label: "initrd",
label: "Initrd",
finished_units: 2,
failed_units: 0,
started_at: Duration::ZERO,
+16 -16
View File
@@ -349,8 +349,8 @@ mod tests {
lines[0], "ryzen · NixOS 26.11 · generation 2771 · Linux 7.2.9",
"{screen}"
);
assert!(lines[1].starts_with("└─ stage 2 12.4s"), "{screen}");
assert!(lines[1].ends_with("running"), "{screen}");
assert!(lines[1].starts_with("└─ Stage 2 12.4s"), "{screen}");
assert!(lines[1].ends_with("Running"), "{screen}");
assert!(
lines[2].starts_with(" ├─ ◆ multi-user.target"),
"{screen}"
@@ -365,10 +365,10 @@ mod tests {
assert!(lines[7].starts_with(" └─ [×] nvidia-powerd"), "{screen}");
let timeline = lines
.iter()
.position(|line| line.contains(" timeline "))
.position(|line| line.contains(" Timeline "))
.expect("timeline panel");
assert!(
lines[timeline + 1].starts_with(&format!("{:29}kernel", "")),
lines[timeline + 1].starts_with(&format!("{:29}Kernel", "")),
"{screen}"
);
assert!(
@@ -459,7 +459,7 @@ mod tests {
let gone = render(&state, 5500 * MS, 110, 24);
let tree: Vec<&String> = gone
.iter()
.take_while(|line| !line.contains(" timeline "))
.take_while(|line| !line.contains(" Timeline "))
.collect();
assert!(
tree.iter().all(|line| !line.contains("early")),
@@ -598,7 +598,7 @@ mod tests {
.find_map(|line| line.find(text).map(|at| line[..at].width()))
.unwrap_or_else(|| panic!("{text} missing\n{screen}"))
};
assert_eq!(column_of("Multi-User System"), column_of("description"));
assert_eq!(column_of("Multi-User System"), column_of("Description"));
assert_eq!(
column_of("Multi-User System"),
column_of("Docker Application")
@@ -628,11 +628,11 @@ mod tests {
.find(|line| line.contains("Docker Socket"))
.unwrap_or_else(|| panic!("{screen}"));
assert!(socket_row.contains("[/] docker "), "{screen}");
assert!(socket_row.contains(" socket "), "{screen}");
assert!(socket_row.contains(" Socket "), "{screen}");
assert!(
render(&described_boot(), 3000 * MS, 110, 24)
.iter()
.all(|line| !line.contains(" socket ")),
.all(|line| !line.contains(" Socket ")),
"{screen}"
);
}
@@ -693,17 +693,17 @@ mod tests {
let screen = lines.join("\n");
assert!(lines[0].ends_with("17.3s"), "{screen}");
assert!(
lines[1].starts_with("├─ initrd ■ done in 7.2s · 1 unit"),
lines[1].starts_with("├─ Initrd ■ done in 7.2s · 1 unit"),
"{screen}"
);
assert!(lines[2].starts_with("└─ stage 2 10.1s"), "{screen}");
assert!(lines[2].starts_with("└─ Stage 2 10.1s"), "{screen}");
assert!(lines[3].starts_with(" └─ ◆ graphical.target"), "{screen}");
let timeline = lines
.iter()
.position(|line| line.contains(" timeline "))
.position(|line| line.contains(" Timeline "))
.expect("timeline panel");
let initrd_bar = &lines[timeline + 2];
assert!(initrd_bar.starts_with("√ initrd (1 unit)"), "{screen}");
assert!(initrd_bar.starts_with("√ Initrd (1 unit)"), "{screen}");
assert!(initrd_bar.ends_with("■│"), "{screen}");
}
@@ -717,7 +717,7 @@ mod tests {
let lines = render(&state, 9500 * MS, 110, 24);
assert!(
lines[1].starts_with(
"└─ ■ boot finished in 9.5s · handing over to display-manager.service"
"└─ ■ Boot finished in 9.5s · handing over to display-manager.service"
),
"{}",
lines.join("\n")
@@ -733,7 +733,7 @@ mod tests {
state.queue_job(1, "poweroff.target", JobKind::BringsUp, 20_000 * MS);
let lines = render(&state, 21_500 * MS, 110, 24);
assert!(
lines[1].starts_with("└─ shutdown 1.5s") && lines[1].ends_with("running"),
lines[1].starts_with("└─ Shutdown 1.5s") && lines[1].ends_with("Running"),
"{}",
lines.join("\n")
);
@@ -747,7 +747,7 @@ mod tests {
let lines = render(&state, 30_000 * MS, 110, 24);
assert!(
lines[1]
.starts_with("└─ ■ shutdown finished in 4.2s · handing over to systemd-shutdown"),
.starts_with("└─ ■ Shutdown finished in 4.2s · handing over to systemd-shutdown"),
"{}",
lines.join("\n")
);
@@ -788,7 +788,7 @@ mod tests {
let screen = lines.join("\n");
let timeline = lines
.iter()
.position(|line| line.contains(" timeline "))
.position(|line| line.contains(" Timeline "))
.expect("timeline panel");
let (tree, panel) = lines.split_at(timeline);
assert!(tree.iter().all(|line| !line.contains('…')), "{screen}");
+2 -2
View File
@@ -101,7 +101,7 @@ pub struct PasswordBar<'a> {
impl Widget for PasswordBar<'_> {
fn render(self, area: Rect, buf: &mut Buffer) {
let status = if self.asking.sent {
format!(" checking{}", self.glyphs.ellipsis).fg(self.palette.waiting)
format!(" Checking{}", self.glyphs.ellipsis).fg(self.palette.waiting)
} else {
format!(" {}_", self.asking.input).fg(self.palette.text)
};
@@ -111,7 +111,7 @@ impl Widget for PasswordBar<'_> {
]))
.block(rule(
self.palette,
Line::from(" password ".fg(self.palette.running)),
Line::from(" Password ".fg(self.palette.running)),
))
.render(area, buf);
}
+2 -2
View File
@@ -35,13 +35,13 @@ impl Stages<'_> {
fn conclusion(&self) -> Option<Conclusion<'_>> {
if let Some(exited_at) = self.state.manager_exited_at {
return Some(Conclusion {
finished: "shutdown",
finished: "Shutdown",
took: exited_at.saturating_sub(self.state.origin),
handed_to: SHUTDOWN_SUCCESSOR,
});
}
self.state.is_complete().then(|| Conclusion {
finished: "boot",
finished: "Boot",
took: self.now.saturating_sub(self.state.origin),
handed_to: self
.state
+2 -2
View File
@@ -24,7 +24,7 @@ pub const LABEL_WIDTH: u16 = 28;
pub const CHROME_HEIGHT: u16 = 2;
const MARK_WIDTH: u16 = 2;
const SLOWEST_RUNS_SHOWN: usize = 5;
const KERNEL_ORIGIN_LABEL: &str = "kernel";
const KERNEL_ORIGIN_LABEL: &str = "Kernel";
const AXIS_LABEL_SPACING: u16 = 8;
const AXIS_STEPS: [Duration; 12] = [
Duration::from_secs(1),
@@ -164,7 +164,7 @@ impl Widget for Timeline<'_> {
fn render(self, area: Rect, buf: &mut Buffer) {
let block = rule(
self.palette,
Line::from(" timeline ".fg(self.palette.waiting)),
Line::from(" Timeline ".fg(self.palette.waiting)),
);
let inner = block.inner(area);
block.render(area, buf);
+11 -17
View File
@@ -17,8 +17,9 @@ use crate::{
};
const SPINNER: [char; 4] = ['|', '/', '-', '\\'];
const DESCRIPTION_GAP: u16 = 1;
const MIN_DESCRIPTION_WIDTH: u16 = 12;
const MIN_TAG_WIDTH: u16 = 6;
const MIN_LABEL_WIDTH: u16 = 24;
const HEADER_ROWS: u16 = 1;
pub struct UnitTree<'a> {
@@ -72,9 +73,9 @@ impl UnitTree<'_> {
let name = |text: &'static str| Line::from(text).fg(self.palette.muted);
Row::new(columns.shown([
self.phase.clone(),
name("kind"),
name("description"),
name("running").right_aligned(),
name("Kind"),
name("Description"),
name("Running").right_aligned(),
]))
}
@@ -162,19 +163,12 @@ impl UnitTree<'_> {
let tag = annotated
.iter()
.map(|(row, _)| width_of(row.kind.tag()))
.max()
.unwrap_or_default();
let content = unannotated.saturating_sub(1 + u16::from(tag > 0));
let label = annotated
.iter()
.map(|(row, stage)| {
width_of(&row.label)
.saturating_add(u16::try_from(self.lead_width(row, *stage)).unwrap_or(u16::MAX))
})
.max()
.map(|widest| widest.saturating_add(DESCRIPTION_GAP))
.filter(|widest| widest.saturating_add(tag + MIN_DESCRIPTION_WIDTH) <= content);
label.map_or(
.fold(MIN_TAG_WIDTH, u16::max);
let content = unannotated.saturating_sub(2);
let label = (content * 3 / 5).max(MIN_LABEL_WIDTH);
let fits_annotations =
!annotated.is_empty() && label + tag + MIN_DESCRIPTION_WIDTH <= content;
fits_annotations.then_some(label).map_or(
Columns {
label: unannotated,
tag: 0,