Hydra OS builds start from the pinned amd64 systemd stage3 and pinned Gentoo
repository in sources.json. Run the builder as the normal user with Python 3,
Podman and GnuPG available; temporary tool environments are sufficient. It
refuses host root and work/cache paths outside the primary project checkout.
scripts/hydra-build fetch
scripts/hydra-build prepare
scripts/hydra-build packages --pretend
scripts/hydra-build packages
scripts/hydra-build rootfs
scripts/hydra-build iso
scripts/hydra-build status
--work PATH, --cache PATH, --podman PATH and --gpg PATH override defaults.
Linked worktrees use the primary checkout's build/ and cache/. The build
lock prevents simultaneous writes in the same work directory. Interrupted
package installation resumes through Portage; successful steps write
build/manifest.json, signature evidence and the installed package/version/USE
inventory in build/artifacts/. Downloaded inputs are reverified on every
prepare; missing or changed files cannot be trusted from a checkpoint alone.
The dedicated rootless Podman store is build/podman, separate from default
Podman and Distrobox storage. The build container mounts inputs and repository
read-only and retains its writable layer across failures. Host networking makes
the existing local VPN/proxy available. SYS_ADMIN operates within the rootless
user namespace; package sandbox features incompatible with it are disabled.
No host disks or /dev/kvm are passed into the builder. Hydra never prunes
containers/images or changes host services.
Official Gentoo binpkgs require signatures. USE mismatches and selective testing
keywords can cause source builds; concurrency is four compiler processes and
one emerge job. Keep licenses and Portage's /var/db/pkg, world and repository
for installed-system updates. Rolling binhost contents can change; resulting
versions/USE are recorded without claiming bit-identical output. The pinned
service-keyring hash may need deliberate review when Gentoo rotates keys.
rootfs exports the dedicated builder into a private intermediate and assembles
an isolated sanitized payload, generic live initramfs and squashfs. iso checks
those artifacts and emits the UEFI HYDRA_OS ISO, SHA256 and build manifest in
build/artifacts/. The working builder is retained for package retries. The
installed Gentoo repository uses the standard rsync backend with signed
metamanifest verification; the builder continues to use its pinned snapshot.
QEMU and remote-viewer retain local patches and are excluded from upstream
binary packages on installed updates. Disposable boot/install validation is
required before treating an emitted ISO as release ready.
The x86_64 ISO disables GRUB's optional HFS+/APM hybrid. Otherwise that second
filesystem duplicates the HYDRA_OS label and can make dracut mount the wrong
live medium after raw USB writing. ISO inspection includes the system area and
rejects HFS+/APM. Test both optical and USB attachment with dev/iso-smoke.py --live-only --live-media cdrom and --live-only --live-media usb (plus the normal
ISO and OVMF arguments); optical boot alone is insufficient.