VesperOS/os-builder
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve build system, use configs for more control

Browse Source
This commit is contained in:
oxmc
2026-03-29 20:33:58 -07:00
parent 53ffdefe2e
commit 235a12a5ed
8 changed files with 124 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
build.sh
+22 -32
View File
@@ -143,11 +143,6 @@ run_stage() {
unmount "${WORK_DIR}/${STAGE}"
if [ ! -f SKIP_IMAGES ]; then
if [ -f "${STAGE_DIR}/EXPORT_IMG" ] || [ -f "${STAGE_DIR}/EXPORT_ISO" ] || [ -f "${STAGE_DIR}/EXPORT_SQUASHFS" ] || [ -f "${STAGE_DIR}/EXPORT_NOOBS" ]; then
EXPORT_DIRS="${EXPORT_DIRS} ${STAGE_DIR}"
fi
fi
if [ ! -f SKIP ]; then
if [ "${CLEAN}" = "1" ]; then
if [ -d "${ROOTFS_DIR}" ]; then
@@ -271,8 +266,6 @@ export PREV_STAGE_DIR
export ROOTFS_DIR
export PREV_ROOTFS_DIR
export IMG_SUFFIX
export NOOBS_NAME
export NOOBS_DESCRIPTION
export EXPORT_DIR
export EXPORT_ROOTFS_DIR
@@ -284,6 +277,7 @@ export QUILT_REFRESH_ARGS="-p ab"
export ENABLE_CLOUD_INIT=${ENABLE_CLOUD_INIT:-1}
export LIVEINSTALL=${LIVEINSTALL:-0}
export LIVEBOOT=${LIVEBOOT:-0}
export EXPORTS="${EXPORTS:-}"
# shellcheck source=scripts/common
source "${SCRIPT_DIR}/common"
@@ -335,43 +329,39 @@ log "Begin ${BASE_DIR}"
STAGE_LIST=${STAGE_LIST:-${BASE_DIR}/stage*}
export STAGE_LIST
EXPORT_CONFIG_DIR="${EXPORT_CONFIG_DIR:-"${BASE_DIR}/exports"}"
export EXPORT_CONFIG_DIR
for STAGE_DIR in $STAGE_LIST; do
STAGE_DIR=$(realpath "${STAGE_DIR}")
run_stage
done
CLEAN=1
for EXPORT_DIR in ${EXPORT_DIRS}; do
EXPORT_ROOTFS_DIR=${WORK_DIR}/$(basename "${EXPORT_DIR}")/rootfs
if [ -e "${EXPORT_DIR}/EXPORT_ISO" ]; then
STAGE_DIR=${EXPORT_CONFIG_DIR}
# shellcheck source=/dev/null
source "${EXPORT_DIR}/EXPORT_ISO"
STAGE_DIR="${BASE_DIR}/exports/iso"
run_stage
fi
if [ -e "${EXPORT_DIR}/EXPORT_IMG" ]; then
STAGE_DIR=${EXPORT_CONFIG_DIR}
# shellcheck source=/dev/null
source "${EXPORT_DIR}/EXPORT_IMG"
# Exports declared in config: EXPORTS="stage3:squashfs stage2:img ..."
for export_spec in ${EXPORTS}; do
stage_name="${export_spec%%:*}"
export_type="${export_spec##*:}"
EXPORT_DIR="${BASE_DIR}/${stage_name}"
EXPORT_ROOTFS_DIR="${WORK_DIR}/${stage_name}/rootfs"
case "${export_type}" in
img)
STAGE_DIR="${BASE_DIR}/exports/img"
run_stage
fi
if [ -e "${EXPORT_DIR}/EXPORT_SQUASHFS" ]; then
;;
squashfs)
STAGE_DIR="${BASE_DIR}/exports/squashfs"
run_stage
fi
if [ "${USE_QEMU}" != "1" ]; then
if [ -e "${EXPORT_DIR}/EXPORT_NOOBS" ]; then
# shellcheck source=/dev/null
source "${EXPORT_DIR}/EXPORT_NOOBS"
STAGE_DIR="${BASE_DIR}/export-noobs"
;;
noobs)
if [ "${USE_QEMU}" != "1" ]; then
STAGE_DIR="${BASE_DIR}/exports/noobs"
run_stage
fi
fi
;;
*)
log "Unknown export type '${export_type}' in EXPORTS spec '${export_spec}'"
false
;;
esac
done
if [ -x "${BASE_DIR}/postrun.sh" ]; then
configs/amd64
+14 -8
View File
@@ -1,16 +1,22 @@
# This builds VesperOS for amd64
ARCH=amd64
# Set LIVEINSTALL=1 to also produce a livefs.squashfs with Calamares installed
# for use with gen-installmedia. Outputs deploy/livefs.{squashfs,vmlinuz,initrd.img}
# alongside the clean deploy/rootfs.{squashfs,vmlinuz,initrd.img}
LIVEINSTALL=1
# Suffix to append to the image name.
# For example, if set to "amd64", the produced image will be named "vesperos-amd64.img".
IMG_SUFFIX="amd64"
# Set LIVEBOOT=1 to install live-boot packages and regenerate the initrd with
# squashfs/overlay support — required for booting rootfs.squashfs from an ISO via live-boot.
# Exports to produce
EXPORTS="stage3:squashfs"
# Weather to export the image with compression (zip, gz, xz) or not (none)
DEPLOY_COMPRESSION="none"
# Set LIVEBOOT=1 to also produce a livefs.squashfs with Calamares installed
# for use with gen-installmedia. Outputs deploy/livefs.{squashfs,vmlinuz,initrd.img}
# alongside the clean deploy/rootfs.squashfs.
LIVEBOOT=1
# Live session user credentials (written to /etc/live/config.conf)
# Live boot options
LIVE_USERNAME="vesper"
LIVE_USER_FULLNAME="VesperOS Live User"
LIVE_USER_PASSWORD="vesper"
LIVE_USER_PASSWORD="vesper"
configs/arm64
+8 -4
View File
@@ -1,7 +1,11 @@
# This builds VesperOS for arm64
ARCH=arm64
# Live session user credentials (written to /etc/live/config.conf)
LIVE_USERNAME="vesper"
LIVE_USER_FULLNAME="VesperOS Live User"
LIVE_USER_PASSWORD="vesper"
# Suffix to append to the image name
IMG_SUFFIX="arm64"
# Exports to produce
EXPORTS="stage3:squashfs"
# Weather to export the image with compression (zip, gz, xz) or not (none)
DEPLOY_COMPRESSION="none"
configs/rpi4
+14 -1
View File
@@ -1,4 +1,17 @@
# Raspberry Pi OS only targets arm64 since the rpi4.
# So VesperOs will also only target arm64 for the rpi4 and up.
# So VesperOS will also only target arm64 for the rpi4 and up.
# This builds VesperOS for arm64
ARCH=arm64
# This tells the build system we are targetting a raspberry pi
PLATFORM=rpi
# Suffix to append to the image name
IMG_SUFFIX="arm64-rpi"
# Exports to produce
EXPORTS="stage3:squashfs"
# Weather to export the image with compression (zip, gz, xz) or not (none)
DEPLOY_COMPRESSION="none"
docs/config.md
+38 -19
View File
@@ -32,10 +32,6 @@ sudo ./build.sh -c build_amd64
Where finished images and archives are placed.
* `EXPORT_CONFIG_DIR` (Default: `$BASE_DIR/export-image`)
Directory of scripts used when generating images. Rarely needs changing.
### Network / SSH
* `ENABLE_SSH` (Default: `0`)
@@ -88,31 +84,54 @@ sudo ./build.sh -c build_amd64
Override the list of stages to run. Example: `"stage0 stage1 mystage stage2"`.
* `EXPORTS` (Default: unset)
Space-separated list of `stage:type` pairs declaring what to export and from which stage. Supported types: `squashfs`, `img`, `noobs`. Example:
```bash
EXPORTS="stage3:squashfs"
EXPORTS="stage3:squashfs stage2:img"
```
### Live boot (squashfs only)
* `LIVEBOOT` (Default: `0`)
Set to `1` to produce a second `-live` squashfs alongside the raw one. Installs `live-boot`, configures GDM autologin, and rebuilds the initramfs. Only applies to `amd64`.
* `LIVEINSTALL` (Default: `0`)
Set to `1` (requires `LIVEBOOT=1`) to also install Calamares into the live squashfs.
* `LIVE_USERNAME` (Default: `vesperos`)
* `LIVE_USER_FULLNAME` (Default: `Live User`)
* `LIVE_USER_PASSWORD` (Default: `vesperos`)
### NOOBS
* `NOOBS_NAME` — Display name shown in the NOOBS menu.
* `NOOBS_DESCRIPTION` — Short description shown in the NOOBS menu.
Both must be set in the config when using `noobs` in `EXPORTS`.
## Example Config Files
### amd64 live ISO
### amd64 with live boot
```bash
IMG_NAME='vesperos'
RELEASE='trixie'
ARCH='amd64'
LOCALE_DEFAULT='en_US.UTF-8'
KEYBOARD_KEYMAP='us'
KEYBOARD_LAYOUT='English (US)'
TIMEZONE_DEFAULT='America/New_York'
ENABLE_SSH=1
EXPORTS="stage3:squashfs"
DEPLOY_COMPRESSION="none"
LIVEBOOT=1
LIVE_USERNAME="vesper"
LIVE_USER_PASSWORD="vesper"
```
### Raspberry Pi (arm64)
```bash
IMG_NAME='vesperos'
RELEASE='trixie'
ARCH='arm64'
LOCALE_DEFAULT='en_US.UTF-8'
KEYBOARD_KEYMAP='us'
KEYBOARD_LAYOUT='English (US)'
TIMEZONE_DEFAULT='America/New_York'
ENABLE_SSH=1
EXPORTS="stage3:squashfs"
DEPLOY_COMPRESSION="none"
ENABLE_CLOUD_INIT=1
```
docs/get-started.md
+14 -15
View File
@@ -6,9 +6,8 @@ VesperOS is a Debian Trixie-based OS for Raspberry Pi (arm64/armhf) and amd64, b
| Arch | Target | Output |
|---------|-------------------------------|----------------|
| `arm64` | Raspberry Pi 3/4/5 (64-bit) | `.img` |
| `armhf` | Raspberry Pi 2/3 (32-bit) | `.img` |
| `amd64` | x86_64 PCs | `.iso` / `.squashfs` |
| `arm64` | Raspberry Pi 3/4/5 (64-bit) | `.squashfs` / `.img` |
| `amd64` | x86_64 PCs | `.squashfs` |
## Build Host Requirements
@@ -35,40 +34,40 @@ Do not clone to a path containing spaces — `debootstrap` does not support them
## Configuration
Copy or create a config file:
Use one of the provided configs in `configs/`:
```bash
cp config.example config
# Edit config as needed
sudo ./build.sh -c configs/amd64
sudo ./build.sh -c configs/arm64
sudo ./build.sh -c configs/rpi4
```
See [config.md](config.md) for all available options. At minimum set:
Or create your own. See [config.md](config.md) for all available options. At minimum set:
```bash
IMG_NAME='vesperos'
RELEASE='trixie'
ARCH='amd64' # or arm64 / armhf
ARCH='amd64' # or arm64
EXPORTS="stage3:squashfs"
```
## Building
```bash
sudo ./build.sh -c config
sudo ./build.sh -c configs/amd64
```
Output files are placed in `deploy/`.
- RPi builds produce a `.img` file you can flash with Balena Etcher or `dd`.
- amd64 builds produce a `.iso` (bootable live image) and/or `.squashfs`.
- `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 stages you don't want to re-run, and `SKIP_IMAGES` to stages that would otherwise trigger an export:
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 config
sudo CLEAN=1 ./build.sh -c configs/amd64
```
Remove the `SKIP` files before a full clean build.
docs/how-the-build-process-works.md
+14 -17
View File
@@ -23,31 +23,28 @@ For each stage directory:
| `00-patches` | Directory of quilt patches applied to the rootfs |
| `00-patches-<arch>` | Arch-specific quilt patches |
5. If the stage contains `EXPORT_IMAGE`, `EXPORT_ISO`, or `EXPORT_SQUASHFS` (and `SKIP_IMAGES` is not present), add it to the export queue.
## Export Pipeline
After all stages are processed, the build runs the export pipeline for each queued stage:
After all stages are processed, the build runs the export pipelines declared in the config via the `EXPORTS` variable:
| Marker file | Export pipeline | Output |
|-------------|----------------|--------|
| `EXPORT_IMAGE` | `export-image/` | `.img` disk image (RPi) |
| `EXPORT_ISO` | `export-iso/` | `.iso` live image (amd64) |
| `EXPORT_SQUASHFS` | `export-squashfs/` | `.squashfs` filesystem archive |
```bash
EXPORTS="stage3:squashfs" # single export
EXPORTS="stage3:squashfs stage2:img" # multiple exports
```
Multiple marker files can coexist in the same stage — all matching exports will run.
| Export type | Pipeline | Output |
|-------------|----------|--------|
| `squashfs` | `exports/squashfs/` | `.squashfs` filesystem archive |
| `img` | `exports/img/` | `.img` disk image |
| `noobs` | `exports/noobs/` | NOOBS-compatible archive |
### export-iso pipeline
### squashfs pipeline
1. `prerun.sh` — rsync rootfs into work dir
2. `01-set-sources` — clean apt caches, run final upgrade
2. `01-set-sources` — clean apt sources
3. `02-network` — configure resolv.conf
4. `03-finalise` — rewrite fstab for live use, generate initramfs, build squashfs, build ISO with `grub-mkrescue`
### export-squashfs pipeline
1. `prerun.sh` — rsync rootfs into work dir
2. `00-finalise` — create squashfs and deploy
4. `03-finalise` — rebuild initramfs, clean up rootfs
5. `04-export` — build squashfs; if `LIVEBOOT=1`, also applies live-boot config and produces a second `-live` squashfs
## Arch-Specific Logic
stage3/EXPORT_SQUASHFS
View File