Docs: Installation Tools Overview

Documentation

Installation Tools Overview

Command-line tools for manual LevitateOS and AcornOS installation, equivalent to Arch Linux's partitioning tools, pacstrap, genfstab and arch-chroot.

Overview

LevitateOS and AcornOS ship the same five installation tools that mirror Arch Linux's manual installation workflow. They give you complete control over the installation process, and they are also the backends of the install screen's step apps, so the same commands work with or without a TUI.

ToolArch LinuxPurpose
recpartfdisk + mkfs + mountPartition, format and mount the target disk
recstrappacstrapExtract the base system to the target directory
recfstabgenfstabGenerate fstab from mounted filesystems
recsetupthe configuration stepsTime zone, locale, keymap, hostname, users, bootloader and services
recchrootarch-chrootEnter chroot with proper bind mounts

Scope note: the repo also ships rec* tooling for the A/B roots and for building and testing images: recab, recinit, reciso, recqemu. See the rec* Tooling Overview.

Installation Workflow

The tools are used in sequence. The Installation Guide walks through each step.

Complete installation workflow:

  1. recpart apply --disk /dev/nvme0n1 --confirm DESTROY

    Create the A/B layout and mount it at /mnt (--mode mutable for one root)

  2. recstrap /mnt

    Extract the base system

  3. recfstab --write /mnt

    Generate fstab entries

  4. recsetup inspect --root /mnt --json

    List the time zones, locales, keymaps and services the target offers

  5. recsetup apply --root /mnt --timezone Europe/Brussels --locale en_US.UTF-8

    Apply the machine settings

  6. recchroot /mnt -- passwd

    Set the installed root password

  7. recsetup apply --root /mnt --boot ab --slot-a /dev/nvme0n1p2 --slot-b /dev/nvme0n1p3 --machine-id && recab verify-installation --root /mnt

    Install systemd-boot and the A/B boot entries

  8. umount /mnt/boot

    Unmount the installed system, deepest mount first

  9. umount /mnt/var

    Unmount the installed system, deepest mount first

  10. umount /mnt

    Unmount the installed system, deepest mount first

  11. reboot

    Reboot into the installed system

Design Philosophy

Each tool does one thing and does it well:

  • recpart only prepares the disk. It plans, shows every command, refuses unsafe layouts, and applies the plan only with --confirm DESTROY.
  • recstrap only extracts files. It does not partition, format, mount, configure, or install bootloaders.
  • recfstab only generates fstab. It outputs to stdout; you redirect to a file.
  • recsetup only configures and boots the extracted system. It plans first and prints the exact commands it runs.
  • recchroot only enters chroot. It sets up mounts, runs your command, and cleans up.

This separation means you understand exactly what each step does. If something goes wrong, you know which tool to debug.

Error Codes

recstrap, recfstab, recchroot and recsetup share one error table: each failure prints a code such as E004, which is also the exit status. The table is the Code enum in tools/recstrap/src/error.rs. recpart has its own (tools/recpart/src/error.rs).

See Also