Running a build
The commands #
peiso root <spec.toml>... [--out <dir>] [--overwrite]
peiso iso <spec.toml>... [--out <dir>] [--overwrite]
peiso root composes the spec's edition into a root tree and stops — useful for inspecting what a release contains, or for a root that will be packed some other way. --out names the directory; without it the root goes to the same place iso would put it.
peiso iso runs the whole pipeline and prints the ISO's path on stdout as its last line; progress goes to stderr. Both commands work from any current directory — relative paths inside a spec resolve against that spec's own directory, and the output directory dist/peios-…/ is relative to where you run.
A build refuses an output path where a root already sits. --overwrite replaces it and rebuilds — the rebuild loop after republishing a package — but replaces only something recognisably a composed root (it carries the package database) or an empty directory, never an arbitrary directory the path happens to name. make iso passes it, so rebuilding is the default there.
Both also take more than one spec, layering them left to right, so a statement of where packages come from can be shared across many builds that each name only what they build. The spec has the rules.
There is no --version, --edition or --dwe flag. Everything that shapes an image is in the spec, so a build is reproducible from the file alone.
The Makefile #
dist/release/Makefile wraps the commands and the QEMU invocations that boot their output:
| Target | |
|---|---|
make iso | build peiso from the tree, then peiso iso experimental.toml |
make iso-dev | the same with the dev.toml layer: a low squashfs level, so the squash stage takes a fraction of the time and the image is somewhat larger — the edit-boot loop's target, never a release. It writes the same build directory as iso. |
make iso-dwe | the same from experimental-dwe.toml |
make boot | boot the newest plain build: UEFI, serial console (the Makefile appends console=ttyS0 through the stub's SMBIOS channel; the image itself names none), GXWI available at https://127.0.0.1:7780/ on the host |
make boot-cd | boot the newest plain build with the medium attached as an optical drive, the way a hypervisor attaches an ISO |
make boot-dwe | boot the newest DWE build with a vsock device (DWE_CID, default 3) |
make boot-quiet / boot-break | add peios.quiet=2 / rd.break to the command line via SMBIOS |
make boot-vga | boot with the framebuffer in a window and console=tty0 last, so the surface is drawn on a VT — what a real machine shows. The serial log stays on stdio. Combine with any target by hand: make boot-installed GRAPHICS='-display gtk -vga std' SMBIOS=… |
make boot-install | boot the DWE build with a blank 8 GiB disk.img attached as /dev/vdb |
make boot-installed | boot disk.img alone — no medium |
make clean-disk / make clean | start the install test over / remove every build directory |
The build directory a target uses is the newest ../peios-experimental-<version>[-dwe]/; only peiso knows a build's resolved version, so the Makefile looks rather than guesses.
Before signing in to GXWI, follow the Quick start's certificate check.
Driving the running system #
dist/release/drive.py boots a build by the direct kernel path, waits for the login prompt, feeds a script to the console, and prints what the guest said:
It talks to the ordinary autologin session — an administrator, not SYSTEM. For anything that needs SYSTEM, use a DWE build and dwe exec.
The legacy peios-install test #
An installation medium is only proven by installing from it and booting what it produced. The test below exercises the older peios-install script through DWE. For ordinary console or browser installation, follow Install Peios on a PC and Installing to disk: the current installerd daemon performs privileged disk operations as SYSTEM for its unprivileged surfaces and does not require this DWE test path.
The legacy script is supported only from a SYSTEM session. Its ordinary cp -ax must read SYSTEM-only source files such as /boot/initramfs/var/state/secrets; direct installation from an administrator session is unsupported. The console administrator can open the raw disk, and the PEI-549 kernel change separately allows partition maintenance through SeManageVolumePrivilege. DWE provides the SYSTEM session used below:
then, from another terminal:
DWE_TARGET=vsock:3
The script partitions and formats the disk, copies the live root, establishes trust in the medium repository on the target, replaces live-boot with disk-boot in both the root and its initramfs, writes a command line with the root filesystem's UUID, and rebuilds the target's initramfs and UKI. Then:
boots the disk with nothing else attached. The initramfs hook is now disk-boot's (mount-root-disk.sh); the login prompt on the serial console is the installed system. An installed system moves to the next release with upgrade-peios.
Variants #
A variant is another spec file. experimental-dwe.toml is the Experimental spec plus [devtools] dwe = true, and builds into its own …-dwe/ directory so it never overwrites the plain image. A spec that pins version = "2026.8" reproduces a release after newer ones exist; one that names a different [[packages.repository]] builds from another source.