Build reference#

Requirements#

Repo layout#

Dev loop#

just validate # graph check — always run first (~5 min, no build)

just build default # build default image — warm cache: 2–5 min; cold: 60–90 min
# or: just build all # build all variants (default + nvidia)

just lint # bootc container lint — must pass before PR

just boot-test # automated smoke test — exits 0 on success
just boot-fast # interactive ephemeral VM via virtiofs (requires virtiofsd)

just show-me-the-future # full loop: build → export → disk image → QEMU VM

First run is slow (cold BST cache). Subsequent runs are fast — BST caches by content hash.

Useful BST commands#

just validate # check element graph
just bst build bluefin/tailscale.bst # build one element
just bst shell --build bluefin/tailscale.bst # sandbox shell
just bst show --deps all oci/bluefin.bst # full dependency graph

Fastfetch ownership#

bluefin/common.bst installs the fastfetch config and wrapper from its pinned
projectbluefin/common source. Do not copy the layout into Dakota or snapshot
its icons/colors in tests. Common updates should carry presentation changes
without a second sync step.

The temporary patches/common/0001-fastfetch-install-date.patch changes only
the date command to read the first-boot record. Drop it when common supports
that record through a shared helper. firstboot-date.bst owns the runtime
records, not the presentation; nerd-fonts-symbols.bst supplies icon fallback
without changing the default text font. The existing booted-image helper patch
in common.bst is separate and remains until common supports that record too.

Run just bst build bluefin/common.bst to exercise the patch against the pinned
source. A source rewrite that invalidates the patch must be reviewed, not
worked around by restoring a local config. Check glyph rendering in a booted
image.
The common source import also does not supply fastfetch-user-count or
bazaar-install-count; those weekly-statistics inputs remain a separate parity
gap, not a reason to fork the config or invent counts.

Ghostty theme ownership#

bluefin/common.bst imports Ghostty's GNOME profile from projectbluefin/common.
Because Dakota uses Ghostty as its primary terminal emulator,
patches/common/0002-ghostty-dual-theme.patch configures theme = light:Catppuccin Latte,dark:Catppuccin Mocha
so that Ghostty follows the GNOME Dark/Light style toggle button out of the box.
Drop this patch once common carries dual-theme by default.

What NOT to do#