Phase 206 — install the systemd-boot/BLS skeleton

At a glance

Field	Value
Phase family	Phase 2 — bootable image
Run command	`make phase 206`
Underlying make target/script	`vm/phase2/build-image-skeleton.sh --boot-skeleton`
Runs on	host with rootful image mount work
Main proof/artifact	Installs the systemd-boot/BLS skeleton into the image.

Phase 206 starts the boot layer, but still does not pretend the OS can fully boot yet.

The basic boot chain we are building toward is:

UEFI firmware
  -> EFI loader on ONIX-ESP
  -> systemd-boot
  -> BLS entry on ONIX-BOOT
  -> kernel
  -> initramfs
  -> mount onix-root as /
  -> run /usr/lib/systemd/systemd

Phase 206 installs only the first bootloader/config part:

UEFI firmware
  -> systemd-boot
  -> BLS entry

It does not install:

kernel
initramfs
systemd userspace

So the image is still not a complete bootable ONIX system. That is intentional.

If Phase 200 or 206 says bootctl or systemd-bootx64.efi is missing, reload the dev shell:

direnv reload

flake.nix exports the host-side ONIX_SYSTEMD_BOOT_EFI path used by this phase.

Why systemd-boot, not GRUB

For the real ONIX image, we want the simple UEFI path:

UEFI + systemd-boot + Boot Loader Specification entries

GRUB was useful in Phase 0 because Alpine needed a practical throwaway forge boot path. ONIX itself should not inherit that forge choice.

systemd-boot is smaller and more direct:

EFI binary on /efi
plain text loader config
plain text boot entries

That makes it easier to understand and easier to generate.

What the ESP is for

ONIX-ESP is mounted at:

/efi

UEFI firmware reads this partition before Linux is running. That means it must contain the EFI executable that firmware can launch.

Phase 206 writes:

/efi/EFI/systemd/systemd-bootx64.efi
/efi/EFI/BOOT/BOOTX64.EFI
/efi/loader/loader.conf

BOOTX64.EFI is the standard removable-media path. OVMF/QEMU can find it without us writing host EFI variables.

What ONIX-BOOT is for

ONIX-BOOT is mounted at:

/boot

It is the future boot asset partition. Phase 206 writes the future BLS entry:

/boot/loader/entries/onix-phase-206.conf

That entry points to future kernel paths:

/boot/ONIX/vmlinuz
/boot/ONIX/initramfs.img

The entry also says the future kernel should mount:

root=LABEL=onix-root

and then start:

init=/usr/lib/systemd/systemd

Those files do not exist yet. That is why Phase 206 is a boot skeleton, not a boot success phase.

What BLS means

BLS means Boot Loader Specification.

For us, the important idea is simple: boot entries are normal text files.

Instead of hiding boot configuration inside a generated GRUB config, ONIX can write a file like:

title ONIX
linux /ONIX/vmlinuz
initrd /ONIX/initramfs.img
options root=LABEL=onix-root rw init=/usr/lib/systemd/systemd

That is easy to inspect, easy to version conceptually, and easy for an image builder to generate.

What Phase 206 verifies

make phase 206 verifies:

Phase 204 contract still passes
the Phase 205 partition labels still exist
systemd-bootx64.efi is available from the dev shell
/efi/EFI/systemd/systemd-bootx64.efi is installed
/efi/EFI/BOOT/BOOTX64.EFI is installed
/efi/loader/loader.conf selects onix-phase-206.conf
/boot/loader/entries/onix-phase-206.conf exists
the entry points at root=LABEL=onix-root
the entry points at /usr/lib/systemd/systemd
kernel/initramfs/systemd are still absent

The last item is important. Phase 206 fails if it accidentally becomes a fake “it boots” phase. We want each layer to prove exactly one thing.

Keyboard shortcuts