os-builder/docs/get-started.md

Getting Started

VesperOS is a Debian Trixie-based OS for Raspberry Pi (arm64/armhf) and amd64, built using a modified pi-gen pipeline.

Supported Architectures

Arch	Target	Output
arm64	Raspberry Pi 3/4/5 (64-bit)	.squashfs / .img
amd64	x86_64 PCs	.squashfs

Build Host Requirements

The build must run on a Debian-based Linux host. Ubuntu 22.04+ or Debian Bookworm/Trixie are recommended.

Install dependencies:

sudo apt-get install coreutils quilt parted qemu-user-static debootstrap zerofree zip \
dosfstools libarchive-tools libcap2-bin grep rsync xz-utils file git curl bc \
gpg pigz xxd arch-test squashfs-tools xorriso grub-common

The depends file in the repo root lists all required tools in <tool>[:<debian-package>] format.

Cloning

git clone https://github.com/oxmc/VesperOS.git
cd VesperOS

Do not clone to a path containing spaces — debootstrap does not support them.

Configuration

Use one of the provided configs in configs/:

sudo ./build.sh -c configs/amd64
sudo ./build.sh -c configs/arm64
sudo ./build.sh -c configs/rpi4

Or create your own. See config.md for all available options. At minimum set:

ARCH='amd64'          # or arm64
EXPORTS="stage3:squashfs"

Building

sudo ./build.sh -c configs/amd64

Output files are placed in deploy/.

• squashfs builds produce a .squashfs (and -live.squashfs if LIVEBOOT=1).
• img builds produce a .img file you can flash with Balena Etcher or dd.

Skipping Stages (Faster Iteration)

Add a SKIP file to any stage you don't want to re-run:

# Skip stages 0-2 to iterate on stage3 only
touch stage0/SKIP stage1/SKIP stage2/SKIP
sudo CLEAN=1 ./build.sh -c configs/amd64

Remove the SKIP files before a full clean build.