Stage Anatomy

ChillcraftOS is built in stages. Each stage builds on the previous one.

Stages

Stage 0 — Bootstrap

Bootstraps a minimal Debian Trixie filesystem using debootstrap. Configures apt sources (including the ChillcraftOS apt repo), installs firmware packages, and sets up the base package state. Does not produce a bootable system.

RPi: installs raspi-firmware, linux-image-rpi-v8, linux-image-rpi-2712
amd64: installs grub2, linux-image-amd64

Stage 1 — Minimal Bootable System

Makes the system bootable. Installs /etc/fstab (arch-specific), configures the hostname, locale, and basic networking. At this stage the system can boot to a console.

RPi fstab: /boot/firmware (vfat) + btrfs root with subvolumes
amd64 fstab: /boot (vfat) + /boot/efi + btrfs root with subvolumes

Both use btrfs subvolumes: @, @home, @var, @snapshots.

Stage 2 — System Layer

Installs the core system utilities, tools, and services. This is the "lite" layer.

Key additions:

zsh as the system-wide default shell
btrfs-progs + snapper for filesystem snapshots
cloud-init + netplan for first-boot configuration
Bluetooth, Wi-Fi, avahi, SSH, cups, and other system services
Python 3, Lua, build tools

Stage 3 — Desktop

Installs the full GNOME desktop environment and user-facing applications.

Key additions:

GNOME Shell and core apps
Firefox ESR
amd64: live-boot, live-config, live-config-systemd, grub-efi-amd64

This stage triggers the export pipeline via EXPORT_ISO and/or EXPORT_SQUASHFS for amd64, and EXPORT_IMAGE for RPi.

Export Outputs

Stage	Arch	Marker	Output
stage3	amd64	`EXPORT_ISO`	Bootable live ISO
stage3	amd64	`EXPORT_SQUASHFS`	Raw squashfs archive
stage3	arm64/armhf	`EXPORT_IMAGE`	Flashable `.img`

Skipping Stages for Development

Place a SKIP file in any stage directory to skip it. Use SKIP_IMAGES to prevent an export from running without skipping the stage itself.

# Only rebuild stage3 (assumes stage0-2 already built)
touch stage0/SKIP stage1/SKIP stage2/SKIP
sudo CLEAN=1 ./build.sh -c config

2.2 KiB Raw Blame History