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

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.
• 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.