qemu

build targets

make kernel              # build kernel/bzImage
make userspace           # build static busybox
make rootfs              # stage rootfs tree
make initramfs           # pack rootfs to cpio.gz
make iso                 # build praxis.iso
make check               # validate syntax and staging
make check-owned         # verify no host tools in rootfs
make clean               # rm -rf build/

live boot

make qemu                # boot live iso in qemu window
make smoke               # headless boot, exit on praxis# prompt

install testing

make qemu-install        # boot iso with writable disk attached (manual install)
make qemu-chroot         # auto-stage disk, drop to praxis-chroot
make qemu-full           # auto-stage disk non-interactively
make qemu-installed      # boot the staged disk (uefi)

critical distinction

make qemu-installed calls scripts/repair-qemu-esp.sh, which only writes BOOTX64.EFI and limine.conf. it does NOT copy the kernel or initramfs. those are placed only by mkinitrd during make qemu-chroot or make qemu-full. if you run make qemu-installedwithout staging first, limine will panic with "Failed to open kernel."

fast path - automated test

make iso
make qemu-full DESKTOP=xfce   # auto-partition, install, initramfs
make qemu-installed            # boot the result

manual install loop

make iso
make qemu-install              # boots with writable disk

inside the vm:

praxis-disk /dev/vda /mnt/praxis
praxis-install --hostname praxisvm /mnt/praxis
mkinitrd /mnt/praxis
praxis-chroot /mnt/praxis
  passwd
  exit
targetcheck /mnt/praxis
sync && umount /mnt/praxis/boot && umount /mnt/praxis

then on host:

make qemu-installed

desktop profiles

make qemu-full DESKTOP=xfce
# or: make qemu-full-xfce (shorthand)

# supported: gnome, plasma, xfce, budgie, mate, lxqt, i3, openbox

disk artifacts

• build/praxis.iso - live iso (all targets)
• build/praxis.qcow2 - qemu disk (created/reused by qemu-install and qemu-chroot)
• QEMU_DISK_SIZE - default 16G, override: QEMU_DISK_SIZE=32G make qemu-full

delete build/praxis.qcow2 to start a fresh install test.

environment variables

PRAXIS_QEMU_SKIP_CHROOT=1    # skip chroot in qemu-full
QEMU_MODE=smoke              # headless boot with nographic
QEMU_UI=nographic            # terminal-only (no window)
DESKTOP=xfce                 # choose desktop profile

next: commands - praxis-install, mkinitrd, and tools reference.