.TH HOLYINSTALL 8
.SH NAME
holyinstall \- prepare a disk or image and install packages to an existing Holy root
.SH SYNOPSIS
.B holyinstall --menu --config FILE --plan NEW_FILE [--holypkg FILE]
.br
.B holyinstall --config FILE --plan NEW_FILE [--holypkg FILE]
.br
.B holyinstall --apply PLAN [--holypkg FILE]
.br
.B holyinstall disk plan --config FILE --output NEW_PLAN
.br
.B holyinstall disk show --plan PLAN
.br
.B holyinstall disk apply --plan PLAN --confirm IMAGE_OR_DEVICE
.br
.B holyinstall disk finalize-plan --disk-plan PLAN --esp FILE --root-image FILE --output NEW_PLAN
.br
.B holyinstall disk finalize-apply --plan PLAN --confirm IMAGE
.SH DESCRIPTION
holyinstall supports a disk-image preparation stage and a separate package
transaction for a pre-mounted root. Disk preparation does not mount the image
or connect it to the package transaction.
The target must already contain an initialized holypkg database and cached
.holy artifacts. The first artifact is the explicit package; later artifacts
are dependency candidates. It invokes holypkg with argv, without a shell.
The default manager path is /usr/bin/holypkg.
It must be Holy's C package manager; the separate Slackware converter named
holypkg does not implement this transaction interface.
The caller must already have permission to modify the target; this stage does
not invoke doas.
.PP
--menu opens a numbered text menu on a terminal. It shows the current root,
package count and selected disk image. It edits the root and disk image, and
opens a package list with add, delete and back actions. Preview calls the
same holypkg planner as config-driven mode. Save writes a normalized config
atomically.
Prepare plan writes the same frozen plan as noninteractive mode. Install shows
the root, set hash and artifact count, then requires the literal answer yes.
Abort and end-of-input leave the target unchanged before apply. Without a TTY,
--menu exits with status 3. The text menu accepts [install] and [disk]; it
rejects other sections to avoid silently discarding them on save.
.PP
The menu saves [disk] in the same config as [install]. It creates a separate
disk plan at PACKAGE_PLAN.disk, shows the exact image path, GPT geometry and
the plan's first and last MiB hashes. It asks for that full path before
formatting. Disk selection may be left
unset while working on packages. Disk planning and package installation remain
separate steps; selecting an image does not mount it as the package target.
.PP
Planning runs holypkg db plan-set read-only. It prints the selected providers
and requirements, then creates a new plan file with mode 0600. The plan binds
the SHA-256 of the effective parsed config, canonical target-root path, target
directory device/inode, ordered artifact identities and holypkg set hash. An existing
plan file is not overwritten. Apply reads only the fixed plan schema; it never
reopens the user config or its includes under elevated privileges. It verifies
the target directory and passes the recorded set hash to holypkg db apply-set.
holypkg rejects a changed database
generation, artifact, ownership or dependency result. Apply retains holypkg's
incomplete transaction journal if mutation fails.
.PP
The config uses the holy.conf lexer, including relative includes and quoted
paths. A minimal config is:
.PP
.RS
.nf
[install]
root "/mnt/holy"
artifact SHA256_OF_ROOT_PACKAGE
artifact SHA256_OF_DEPENDENCY_CANDIDATE
accept-arch SHA256_OF_CONFIRMED_CROSS_ARCH_PACKAGE
accept-privileged SHA256_OF_REVIEWED_SETUID_PACKAGE
source SHA256_OF_SELECTED_PACKAGE REGISTERED_SOURCE_ID
.fi
.RE
.PP
SHA256 values must be lowercase. The root path cannot be /. Config comments
do not change the effective-config hash. Changes to parsed values or artifact
order require a new plan. The plan must be reviewed before apply; the config
is no longer consulted at that step.
.PP
accept-arch names an artifact already selected in [install]. It preserves an
explicit architecture-placement decision in plan format 2. Preview and apply
pass the same approval to holypkg. It permits placement; it does not claim the
target executable can run on the host. The text menu toggles this decision in
the package list and shows accepted artifacts before installation.
.PP
accept-privileged names a selected artifact whose setuid executable and full
payload the caller has reviewed. Plan format 3 records its exact SHA-256 and
apply passes the same decision to holypkg. Without the approval, planning
returns decision-required. The package menu toggles this decision separately
from architecture placement. A changed artifact needs a new approval and plan.
.PP
source associates one selected artifact with an active registered source ID.
The target database must already contain that registration. Plan format 4
freezes each artifact-to-source binding and passes it to holypkg during both
planning and apply. Unknown sources, duplicate bindings and changed source
registries fail before package mutation. The text menu can set or clear a
source ID and keeps the binding when saving config.
.SH DISK PREPARATION
The disk command accepts a regular file or a block disk of at least 1 GiB. The supported
layout is GPT with a 1 MiB BIOS boot partition, a 256 MiB FAT32 ESP and an
ext4 root partition. Image mode uses sfdisk, mkfs.fat and mke2fs, and requires
losetup to confirm that the image is not attached to a loop device.
A minimal image config is:
.PP
.RS
.nf
[disk]
image "/tmp/holy.img"
layout gpt-ext4
.fi
.RE
.PP
Create the image before planning, for example with truncate. Planning prints
the exact image path, device/inode identity, size and partition geometry. It
hashes the first and last MiB and writes a new mode-0600 plan. Apply requires
--confirm to equal the canonical image path in that plan. It checks the
identity and both hashes again, then records prepared, partitioning and
formatting stages in PLAN.journal. An existing journal blocks another apply.
The show command prints the saved geometry without changing the image.
After an interrupted stage, inspect the image and journal before starting a
new plan. The command does not silently repeat a format operation.
.PP
For a block disk, use device instead of image in [disk]. Planning records
the disk node, block-device number, size, serial, first and last MiB hashes,
and SHA-256 of the four static tools used by apply: sfdisk, mkfs.fat,
mke2fs and Limine. Apply requires the exact device path as --confirm and
rechecks those inputs before mutation. It holds an exclusive disk descriptor,
writes the GPT, asks the kernel to reread the partition table, checks the
partition geometry, formats FAT32 and ext4, and installs the Limine BIOS
stage. The journal records each stage. This operation destroys existing
partitions and filesystems. It does not mount the new root or install packages.
.PP
Disk preparation destroys existing image contents. It does not mount the
partitions or generate an initramfs. The finalize-plan command requires a
committed disk preparation journal, a valid GPT, an exact-size ESP image and
an exact-size ext4 root image. It records the full SHA-256, device, inode and
size of the disk, both input images and /usr/bin/limine in a new mode-0600
plan. Review that plan before applying it. Finalize-apply requires the exact
disk path as --confirm and rechecks all inputs before changing the disk. It
copies the two images into their partitions, verifies the written bytes,
installs the Limine BIOS stage and verifies GPT. The adjacent journal records
each stage. A changed input requires a new plan; an existing finalize journal
requires inspection before recovery. The command does not configure UEFI,
mount the partitions or prove the image can boot. Boot and account menus and
the full interactive install acceptance matrix remain pending.
.PP
The optional install VM fixture described in holy-image(7) gives the live
guest a blank disk. holyinstall creates the GPT and filesystems and installs
the Limine BIOS stage inside that guest before applying a package plan to its
root. The runner then boots the installed disk through BIOS and UEFI.
.SH EXIT STATUS
0 means the requested step completed. 1 means an operational error. 2 means
invalid arguments, config or plan. Disk apply returns 3 for a changed image
or missing confirmation, 5 for an existing journal or failed mutation, and
6 for a missing image, tool or available capability. holypkg statuses 3
through 6 propagate from the package transaction.
.SH SEE ALSO
.BR holypkg (8),
.BR holy.conf (5),
.BR holy-image (7)