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

SquashFS layer rule

The NVIDIA live medium is not one squashfs. build.sh splits the monolith into semantic layers (filesystem-v<ver>-NN-*.squashfs) after the full lb build, driven by iso/builder/lib/squashfs-layers.sh. See bible-local/architecture/squashfs-layers.md for the layer model and decisions/2026-09-04-squashfs-semantic-layers.md for why.

Rules:

• Classify by dpkg file ownership, not path substring. New non-.deb files injected by build.sh must get an explicit entry in bee_layer_injected_rules (or they fall to 00-base).
• live/filesystem.module is authoritative for layer order; keep it in sync with the NN- prefixes. Later layer wins a conflict, in live-boot, bee-install, and any rebuild.
• Keep each layer a self-contained valid squashfs under the 800 MiB ceiling. Split a semantic layer further rather than blindly slicing bytes.
• Never let an upper layer carry a real top-level bin/sbin/lib/lib64 path - that breaks merged-usr the same way the fast-path bug did.
• The builder deletes the monolith only after every layer verifies and re-merges into a bootable rootfs. Any failure must abort before ISO assembly.
• The fast path stays disabled for a multi-layer medium until a layer-aware repack exists. Do not "take the first squashfs".
• test-squashfs-layers.sh and test-build-libs.sh run at the top of every build; keep them green.

Bootloader sync rule

The ISO has two canonical bootloader templates whose live entries must remain semantically equivalent:

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. lib/bootloader.sh renders both templates into the final binary/ tree after live-build has created it, and the ISO validator checks every live entry. Any menu or kernel-parameter change must still be made in both templates.

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
no GUI	nomodeset bee.gui=off bee.nvidia.mode=normal + full param set
fail-safe	normal parameters plus pci=realloc iommu.strict=1
wipe	toram nomodeset bee.gui=off bee.wipe=all + reduced performance params

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 udev.children_max=1 intel_iommu=on
iommu.passthrough=0 efi=disable_early_pci_dma

The fail-safe entry alone adds pci=realloc iommu.strict=1. pci=realloc must not be copied into normal entries. Memtest and firmware-setup entries are not Linux live entries and therefore do not carry these parameters.

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.