# 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:

```bash
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

```bash
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/`:

```bash
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](config.md) for all available options. At minimum set:

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

## Building

```bash
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:

```bash
# 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.