holygetiso(8)

build and boot-test a Holy image from explicit inputs

NAME

holygetiso - build and boot-test a Holy image from explicit inputs

SYNOPSIS

holygetiso[ --check ]CONFIG holygetiso --export-inputsIMAGE_OUTPUT DIRECTORY

DESCRIPTION

The current command drives the repository's bootstrap-image builder. Run it from the Holy source directory after make. It accepts local or pinned-source core inputs and pinned native source packages for additional applications. It rejects unknown sections, keys, duplicate scalar keys, missing input paths and malformed quoting. It uses the holy.conf lexer; configuration text is not executed by a shell. A top-level "include PATH" reads another config relative to the containing file. Include cycles and duplicate scalar keys across files fail.

The builder packages the core inputs, asks holyinstall and holypkg to install them into a separate root, generates the documentation bundle and initramfs, creates an ISO, then runs the QEMU boot contract. The output directory must not exist. A successful exit requires a boot-tested image; the build log, install preview, frozen plan, package hashes and VM report remain there. The command writes one expanded effective config with resolved input paths. Its SHA-256 is included in build.record before the boot plan is hashed. The builder copies those exact bytes into output/inputs/image.conf and rejects a change between validation and copying. With --check, the command validates the config and existing input paths and prints the effective config hash, target architecture, profile and output path without starting a build.

--export-inputs copies the inputs, normalized packages, sealed native mirrors, build record and frozen plans from an existing build output into a new directory. It checks the input lock and source/install/boot plan hashes before copying. SHA256SUMS records each copied file and is checked before the command succeeds. The bundle preserves the exact package inputs for inspection or a repeated experiment. host-tools.jsonl names each direct executable used by the builder, its canonical path and SHA-256; the build record binds that file. The bundle does not include the host compiler, QEMU, firmware, their dependency closure or the Holy source checkout. The destination must not exist.

CONFIGURATION

Paths are resolved relative to the config file. Existing input paths must resolve at startup. The output path names a new directory; the ISO is written as holy-ARCH.iso inside it. Supported sections and keys follow.

[image]

[packages]

make source-ready-core

[resolver]

[source NAME]

[docs]

STATUS

The command returns 0 after a boot-tested build, 2 for invalid config, 6 for missing inputs or host requirements, and 1 for other failures. The output build.record says "result incomplete" when a build fails after the output directory is created. If QEMU is missing, or boot-test is build-only, the builder writes "result untested" after producing the image and returns 6. A successful process exit alone does not certify hardware, a desktop or all packages named in the Holy specification.

LIMITS

This bootstrap command supports holy-http and holy-git sources. For additional packages it uses holypkg's native resolver in a temporary root with every pinned mirror bound. The resolver can select a unique exact provider from another source. Explicitly listed packages from other sources become candidate providers; unresolved ambiguity stops the build. The builder copies only selected artifacts and their source IDs into the final install plan. Boot core packages may come from a pinned native source. Full package policy and a portable export of build tools remain open. The command stays in-tree while the source checkout provides build tools and profiles.