How the ISO is built
The distributable image is written by a script in this tree rather than by a standard tool, which was worth doing because the failure modes are otherwise opaque.
How UEFI boots an optical disc
Firmware does not read the ISO 9660 filesystem to find a boot loader. It reads the El Torito boot catalogue, finds an entry marked as a UEFI platform, and treats the extent that entry points at as a FAT filesystem image. It then looks inside that image for the usual boot path.
So a bootable image contains a whole FAT partition as a file, and the ISO around it exists mostly to be a container the firmware knows how to open.
Long file names are not optional
Plain ISO 9660 restricts names to eight characters, a dot, and three more, in upper case. The path the firmware looks for does not fit, so the image carries a Joliet extension with the real names in UCS-2.
Omitting it gives an image that mounts fine on a desktop operating system, which will happily read the Joliet names or fall back gracefully, and does not boot, because the firmware finds nothing at the path it wants.
FAT32 has a floor
FAT32 is defined by cluster count rather than by size. Below 65,525 clusters the filesystem is FAT16 by definition, whatever the header claims, and a driver following the specification will read it as FAT16 and find nothing.
A small embedded image therefore has to either use a small enough cluster size to clear the floor or be padded until it does. Getting that wrong produces an image that some drivers read and others do not, which is a worse outcome than one that fails everywhere.
Why write a FAT reader as well
Because a writer with no reader is a writer nobody can check. The same tooling reads the image back, walks the directory, and asserts that the boot path is present with the expected size. That has caught a wrong cluster count, a missing Joliet tree and an off-by-one in the boot catalogue, each of which would otherwise have presented as a machine that does not boot with no further information.
The same FAT writer builds the emulator's test partition, so the code path is exercised by ordinary development rather than only at release time.
Verifying the result
Every published image has a checksum file beside it. The largest is the 2B distill at about 1.9 GB, and the smallest carries no model at all for anybody who wants to supply their own. Booting the image under emulation before publishing it is one command, and it is the last step of building one.
