bee/bible-local/docs/iso-build-rules.md

ISO Build Rules

Verify package names before use

ISO builds take 30–60 minutes. A wrong package name wastes an entire build cycle.

Rule: before adding any Debian package name to the ISO config, verify it exists and check its file list.

Use one of:

• https://packages.debian.org/bookworm/<package-name> — existence + description
• https://packages.debian.org/bookworm/amd64/<package-name>/filelist — exact files installed
• apt-cache show <package> inside a Debian bookworm container

This applies to:

• iso/builder/config/package-lists/*.list.chroot
• Any package referenced in bootloader configs, hooks, or overlay scripts

Bootloader sync rule

The ISO has two independent bootloader configs that must be kept in sync manually:

File	Used by
config/bootloaders/grub-efi/grub.cfg	UEFI (all modern servers)
config/bootloaders/isolinux/live.cfg.in	CSM / legacy BIOS (syslinux)

live-build does NOT derive one from the other. Any new boot entry, kernel parameter change, or new mode added to one file must be manually mirrored in the other.

Canonical entry list (both files must have all of these):

Label	Key params
normal (default)	nomodeset bee.nvidia.mode=normal + full param set
load to RAM	toram nomodeset bee.nvidia.mode=normal + full param set
GSP=off	nomodeset bee.nvidia.mode=gsp-off + full param set
KMS	no nomodeset, bee.nvidia.mode=normal + full param set
KMS + GSP=off	no nomodeset, bee.nvidia.mode=gsp-off + full param set
fail-safe	nomodeset bee.nvidia.mode=gsp-off noapic noapm nodma nomce nolapic nosmp

Full standard param set (append after @APPEND_LIVE@ / nomodeset flags):

net.ifnames=0 biosdevname=0 mitigations=off transparent_hugepage=always
numa_balancing=disable pcie_aspm=off intel_idle.max_cstate=1 processor.max_cstate=1
nowatchdog nosoftlockup

(fail-safe is the exception — it deliberately uses minimal params.)

Historical note: grub-pc/ was mistakenly used instead of grub-efi/ until v8.25. live-build reads config/bootloaders/grub-efi/ for UEFI because the build is configured with --bootloaders "grub-efi,syslinux". Directory grub-pc is ignored.

Memtest rule

Do not assume live-build's built-in memtest integration is sufficient for bee. We already tried that path and regressed again on 2026-04-01: lb binary_memtest ran, but the final ISO still lacked memtest binaries and menu entries.

For this project, memtest is accepted only when the produced ISO actually contains all of the following:

• boot/memtest86+x64.bin
• boot/memtest86+x64.efi
• a memtest entry in boot/grub/grub.cfg
• a memtest entry in isolinux/live.cfg

Rules:

• Keep explicit post-build memtest validation in build.sh.
• Treat ISO reader success as a separate prerequisite from memtest content. If the reader cannot list or extract from the ISO, that is a validator failure, not proof that memtest is missing.
• If built-in integration does not produce the artifacts above, use a deterministic project-owned copy/extract step instead of hoping live-build will "start working".
• Do not switch back to built-in-only memtest without fresh build evidence from a real ISO.
• If you reference memtest files manually, verify the exact package file list first for the target Debian release.

Known bad loops for this repository:

• Do not retry built-in-only memtest without new evidence. We already proved that lb binary_memtest can run while the final ISO still has no memtest.
• Do not assume fixing memtest file names is enough. Correct names did not fix the final artifact path.
• Do not assume chroot/boot/ contains memtest payloads at the time hooks run.
• Do not assume source grub.cfg / live.cfg.in are the final writers of ISO bootloader configs.
• Do not assume the current config/hooks/normal/9100-memtest.hook.binary timing is late enough to patch final binary/boot/grub/grub.cfg or binary/isolinux/live.cfg; logs from 2026-04-01 showed those files were not present yet when the hook executed.
• Do not treat a validator warning as ground truth until you have confirmed the ISO reader actually succeeded. On 2026-04-01 we misdiagnosed another memtest regression because the final ISO was correct but the validator produced a false negative.