From eeab7c00669283674182ca51341cca712013b0dd Mon Sep 17 00:00:00 2001 From: oxmc7769 Date: Thu, 5 Mar 2026 08:16:21 -0800 Subject: [PATCH] Main base maybe? --- docs/config.md | 182 +++++++----------- docs/docker-build.md | 54 +++--- docs/get-started.md | 86 ++++++--- docs/how-the-build-process-works.md | 74 ++++--- docs/stage-anatomy.md | 115 +++++------ docs/troubleshooting.md | 78 +++++--- export-iso/03-finalise/01-run.sh | 2 +- stage2/01-sys-tweaks/00-packages | 3 +- .../01-sys-tweaks/00-patches/01-useradd.diff | 2 +- stage2/01-sys-tweaks/00-patches/03-path.diff | 2 +- stage3/01-install-desktop/00-packages | 1 - stage3/01-install-desktop/01-packages | 1 + .../01-install-desktop/01-packages-arm-only | 2 +- 13 files changed, 297 insertions(+), 305 deletions(-) create mode 100644 stage3/01-install-desktop/01-packages diff --git a/docs/config.md b/docs/config.md index 744d022..ef529f1 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,168 +1,118 @@ -## Config +# Config -Upon execution, `build.sh` will source the file `config` in the current -working directory. This bash shell fragment is intended to set needed -environment variables. +`build.sh` sources the file `config` in the current working directory at startup. It can also be specified explicitly: -The following environment variables are supported: +```bash +sudo ./build.sh -c build_amd64 +``` - * `IMG_NAME` (Default: `raspios-$RELEASE-$ARCH`, for example: `raspios-trixie-armhf`) +## Variables - The name of the image to build with the current stage directories. Use this - variable to set the root name of your OS, eg `IMG_NAME=Frobulator`. - Export files in stages may add suffixes to `IMG_NAME`. +### Core - * `PI_GEN_RELEASE` (Default: `Raspberry Pi reference`) +* `IMG_NAME` (Default: `chillcraftos-$RELEASE-$ARCH`) - The release name to use in `/etc/issue.txt`. The default should only be used - for official Raspberry Pi builds. + Base name for output files. * `RELEASE` (Default: `trixie`) - The release version to build images against. Valid values are any supported - Debian release. However, since different releases will have different sets of - packages available, you'll need to either modify your stages accordingly, or - checkout the appropriate branch. For example, if you'd like to build a - `bullseye` image, you should do so from the `bullseye` branch. + Debian release to build against. - * `APT_PROXY` (Default: unset) +* `ARCH` (Default: `arm64`) - If you require the use of an apt proxy, set it here. This proxy setting - will not be included in the image, making it safe to use an `apt-cacher` or - similar package for development. + Target architecture. One of: `arm64`, `armhf`, `amd64`. - * `TEMP_REPO` (Default: unset) +### Directories - An additional temporary apt repo to be used during the build process. This - could be useful if you require pre-release software to be included in the - image. The variable should contain sources in [one-line-style format](https://manpages.debian.org/stable/apt/sources.list.5.en.html#ONE-LINE-STYLE_FORMAT). - "RELEASE" will be replaced with the RELEASE variable. +* `WORK_DIR` (Default: `$BASE_DIR/work`) - * `BASE_DIR` (Default: location of `build.sh`) + Where stage rootfs directories are built. Should be on a Linux filesystem — NTFS will not work. - **CAUTION**: Currently, changing this value will probably break build.sh +* `DEPLOY_DIR` (Default: `$BASE_DIR/deploy`) - Top-level directory for `pi-gen`. Contains stage directories, build - scripts, and by default both work and deployment directories. + Where finished images and archives are placed. - * `WORK_DIR` (Default: `$BASE_DIR/work`) +* `EXPORT_CONFIG_DIR` (Default: `$BASE_DIR/export-image`) - Directory in which `pi-gen` builds the target system. This value can be - changed if you have a suitably large, fast storage location for stages to - be built and cached. Note, `WORK_DIR` stores a complete copy of the target - system for each build stage, amounting to tens of gigabytes in the case of - Raspbian. + Directory of scripts used when generating images. Rarely needs changing. - **CAUTION**: If your working directory is on an NTFS partition you probably won't be able to build: make sure this is a proper Linux filesystem. +### Network / SSH - * `DEPLOY_DIR` (Default: `$BASE_DIR/deploy`) +* `ENABLE_SSH` (Default: `0`) - Output directory for target system images and NOOBS bundles. + Set to `1` to enable the SSH server in the built image. - * `DEPLOY_COMPRESSION` (Default: `zip`) +* `PUBKEY_SSH_FIRST_USER` (Default: unset) - Set to: - * `none` to deploy the actual image (`.img`). - * `zip` to deploy a zipped image (`.zip`). - * `gz` to deploy a gzipped image (`.img.gz`). - * `xz` to deploy a xzipped image (`.img.xz`). + If set, written to `~/.ssh/authorized_keys` for the first user. - * `COMPRESSION_LEVEL` (Default: `6`) +* `PUBKEY_ONLY_SSH` (Default: `0`) - Compression level to be used when using `zip`, `gz` or `xz` for - `DEPLOY_COMPRESSION`. From 0 to 9 (refer to the tool man page for more - information on this. Usually 0 is no compression but very fast, up to 9 with - the best compression but very slow ). + Set to `1` to disable password auth and require public key auth for SSH. - * `USE_QEMU` (Default: `0`) +* `APT_PROXY` (Default: unset) - Setting to '1' enables the QEMU mode - creating an image that can be mounted via QEMU for an emulated - environment. These images include "-qemu" in the image file name. + Apt proxy URL (e.g. `http://192.168.1.1:3142`). Not included in the final image. - * `LOCALE_DEFAULT` (Default: 'en_GB.UTF-8' ) +* `TEMP_REPO` (Default: unset) - Default system locale. + Additional temporary apt repo used only during the build. Supports `RELEASE` substitution. - * `TARGET_HOSTNAME` (Default: 'raspberrypi' ) +### Locale / Keyboard - Setting the hostname to the specified value. +* `LOCALE_DEFAULT` (Default: `en_US.UTF-8`) - * `KEYBOARD_KEYMAP` (Default: 'gb' ) +* `KEYBOARD_KEYMAP` (Default: `en`) - Default keyboard keymap. +* `KEYBOARD_LAYOUT` (Default: `English (US)`) - To get the current value from a running system, run `debconf-show - keyboard-configuration` and look at the - `keyboard-configuration/xkb-keymap` value. +* `TIMEZONE_DEFAULT` (Default: `America/Los Angeles`) - * `KEYBOARD_LAYOUT` (Default: 'English (UK)' ) +### Cloud-init - Default keyboard layout. +* `ENABLE_CLOUD_INIT` (Default: `1`) - To get the current value from a running system, run `debconf-show - keyboard-configuration` and look at the - `keyboard-configuration/variant` value. + Set to `1` to install and configure cloud-init. On RPi, seed files go to `/boot/firmware/`. On amd64, they go to `/var/lib/cloud/seed/nocloud/`. - * `TIMEZONE_DEFAULT` (Default: 'Europe/London' ) +### Other - Default time zone. +* `USE_QEMU` (Default: `0`) - To get the current value from a running system, look in - `/etc/timezone`. + Set to `1` to produce a QEMU-compatible image (adds `-qemu` suffix). - * `FIRST_USER_NAME` (Default: `system`) +* `SETFCAP` (Default: unset) - Username for the first user. This user only exists during the image creation process. + Set to `1` to preserve Linux capabilities in the rootfs. Only needed for NFS or capability-sensitive deployments. - * `WPA_COUNTRY` (Default: unset) +* `STAGE_LIST` (Default: `stage*`) - Sets the default WLAN regulatory domain and unblocks WLAN interfaces. This should be a 2-letter ISO/IEC 3166 country Code, i.e. `GB` + Override the list of stages to run. Example: `"stage0 stage1 mystage stage2"`. - * `ENABLE_SSH` (Default: `0`) +## Example Config Files - Setting to `1` will enable ssh server for remote log in. Note that if you are using a common password such as the defaults there is a high risk of attackers taking over you Raspberry Pi. - - * `PUBKEY_SSH_FIRST_USER` (Default: unset) - - Setting this to a value will make that value the contents of the FIRST_USER_NAME's ~/.ssh/authorized_keys. Obviously the value should - therefore be a valid authorized_keys file. Note that this does not - automatically enable SSH. - - * `PUBKEY_ONLY_SSH` (Default: `0`) - - * Setting to `1` will disable password authentication for SSH and enable - public key authentication. Note that if SSH is not enabled this will take - effect when SSH becomes enabled. - - * `SETFCAP` (Default: unset) - - * Setting to `1` will prevent pi-gen from dropping the "capabilities" - feature. Generating the root filesystem with capabilities enabled and running - it from a filesystem that does not support capabilities (like NFS) can cause - issues. Only enable this if you understand what it is. - - * `STAGE_LIST` (Default: `stage*`) - - If set, then instead of working through the numeric stages in order, this list will be followed. For example setting to `"stage0 stage1 mystage stage2"` will run the contents of `mystage` before stage2. Note that quotes are needed around the list. An absolute or relative path can be given for stages outside the pi-gen directory. - - * `EXPORT_CONFIG_DIR` (Default: `$BASE_DIR/export-image`) - - If set, use this directory path as the location of scripts to run when generating images. An absolute or relative path can be given for a location outside the pi-gen directory. - - * `ENABLE_CLOUD_INIT` (Default: `1`) - - If set to `1`, cloud-init and netplan will be installed and configured. This will allow you to configure your Raspberry Pi using cloud-init configuration files. The cloud-init configuration files should be placed in the bootfs or by editing the files in `stage2/04-cloud-init/files`. Cloud-init will be configured to read them on first boot. - -A simple example for building Raspberry Pi OS: +### amd64 live ISO ```bash -IMG_NAME='raspios' +IMG_NAME='chillcraftos' +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 ``` -The config file can also be specified on the command line as an argument the `build.sh` or `build-docker.sh` scripts. +### Raspberry Pi (arm64) +```bash +IMG_NAME='chillcraftos' +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 +ENABLE_CLOUD_INIT=1 ``` -./build.sh -c myconfig -``` - -This is parsed after `config` so can be used to override values set there. \ No newline at end of file diff --git a/docs/docker-build.md b/docs/docker-build.md index 2ac1e22..bc05dbf 100644 --- a/docs/docker-build.md +++ b/docs/docker-build.md @@ -1,47 +1,55 @@ -## Docker Build +# Docker Build -Docker can be used to perform the build inside a container. This partially isolates -the build from the host system, and allows using the script on non-debian based -systems (e.g. Fedora Linux). The isolation is not complete due to the need to use -some kernel level services for arm emulation (binfmt) and loop devices (losetup). +Docker can be used to run the build inside a container. This is useful on non-Debian hosts (e.g. Fedora, Arch, macOS with Linux VM) or to keep the build environment isolated from the host system. -To build: +> **Note**: The Docker build is not fully isolated — it still needs kernel-level access for `binfmt_misc` (ARM emulation) and `losetup` (loop devices for `.img` builds). + +## Building ```bash -vi config # Edit your config file. See above. +cp config.example config # edit as needed ./build-docker.sh ``` -If everything goes well, your finished image will be in the `deploy/` folder. -You can then remove the build container with `docker rm -v pigen_work` +Output will be in `deploy/`. -If you encounter errors during the build, you can edit the corresponding scripts, and -continue: +## Continuing After a Failure + +Edit the failing script, then resume without restarting from scratch: ```bash CONTINUE=1 ./build-docker.sh ``` -To examine the container after a failure you can enter a shell within it using: +## Inspecting the Container After a Failure ```bash -sudo docker run -it --privileged --volumes-from=pigen_work pi-gen /bin/bash +sudo docker run -it --privileged --volumes-from=pigen_work chillcraftos-build /bin/bash ``` -After successful build, the build container is by default removed. This may be undesired when making incremental changes to a customized build. To prevent the build script from remove the container add +## Preserving the Container Between Runs + +By default the container is removed after a successful build. To keep it for incremental development: ```bash PRESERVE_CONTAINER=1 ./build-docker.sh ``` -There is a possibility that even when running from a docker container, the -installation of `qemu-user-static` will silently fail when building the image -because `binfmt-support` _must be enabled on the underlying kernel_. An easy -fix is to ensure `binfmt-support` is installed on the host machine before -starting the `./build-docker.sh` script (or using your own docker build -solution). +## Passing Extra Docker Arguments -### Passing arguments to Docker +Use `PIGEN_DOCKER_OPTS` to pass additional flags to `docker run`: -When the docker image is run various required command line arguments are provided. For example the system mounts the `/dev` directory to the `/dev` directory within the docker container. If other arguments are required they may be specified in the PIGEN_DOCKER_OPTS environment variable. For example setting `PIGEN_DOCKER_OPTS="--add-host foo:192.168.0.23"` will add '192.168.0.23 foo' to the `/etc/hosts` file in the container. The `--name` -and `--privileged` options are already set by the script and should not be redefined. \ No newline at end of file +```bash +PIGEN_DOCKER_OPTS="--add-host myrepo:192.168.1.10" ./build-docker.sh +``` + +The `--name` and `--privileged` flags are already set by the script and should not be redefined. + +## binfmt_misc on Docker Hosts + +If building ARM images, `binfmt_misc` must be enabled on the host kernel before starting the build: + +```bash +sudo apt-get install binfmt-support qemu-user-static +sudo update-binfmts --enable +``` diff --git a/docs/get-started.md b/docs/get-started.md index ec94ede..adeec9b 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,48 +1,74 @@ -# pi-gen +# Getting Started -Tool used to create Raspberry Pi OS images, and custom images based on Raspberry Pi OS, -which was in turn derived from the Raspbian project. +ChillcraftOS is a Debian Trixie-based OS for Raspberry Pi (arm64/armhf) and amd64, built using a modified pi-gen pipeline. -**Note**: Raspberry Pi OS 32 bit images are based primarily on Raspbian, while -Raspberry Pi OS 64 bit images are based primarily on Debian. +## Supported Architectures -**Note**: 32 bit images should be built from the `master` branch. -64 bit images should be built from the `arm64` branch. +| 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` | -## Dependencies +## Build Host Requirements -pi-gen runs on Debian-based operating systems released after 2017, and we -always advise you use the latest OS for security reasons. +The build must run on a Debian-based Linux host. Ubuntu 22.04+ or Debian Bookworm/Trixie are recommended. -On other Linux distributions it may be possible to use the Docker build described -below. - -To install the required dependencies for `pi-gen` you should run: +Install dependencies: ```bash -apt-get install coreutils quilt parted qemu-user-static debootstrap zerofree zip \ +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 +gpg pigz xxd arch-test squashfs-tools xorriso grub-common ``` -The file `depends` contains a list of tools needed. The format of this -package is `[:]`. +The `depends` file in the repo root lists all required tools in `[:]` format. -## Getting started with building your images - -Getting started is as simple as cloning this repository on your build machine. You -can do so with: +## Cloning ```bash -git clone https://github.com/RPI-Distro/pi-gen.git +git clone https://github.com/oxmc/ChillcraftOS.git +cd ChillcraftOS ``` -`--depth 1` can be added after `git clone` to create a shallow clone, only containing -the latest revision of the repository. Do not do this on your development machine. +Do not clone to a path containing spaces — `debootstrap` does not support them. -Also, be careful to clone the repository to a base path **NOT** containing spaces. -This configuration is not supported by debootstrap and will lead to `pi-gen` not -running. +## Configuration -After cloning the repository, you can move to the next step and start configuring -your build. \ No newline at end of file +Copy or create a config file: + +```bash +cp config.example config +# Edit config as needed +``` + +See [config.md](config.md) for all available options. At minimum set: + +```bash +IMG_NAME='chillcraftos' +RELEASE='trixie' +ARCH='amd64' # or arm64 / armhf +``` + +## Building + +```bash +sudo ./build.sh -c config +``` + +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`. + +## 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: + +```bash +# Skip stages 0-2 to iterate on stage3 only +touch stage0/SKIP stage1/SKIP stage2/SKIP +sudo CLEAN=1 ./build.sh -c config +``` + +Remove the `SKIP` files before a full clean build. diff --git a/docs/how-the-build-process-works.md b/docs/how-the-build-process-works.md index 1116311..f5a8b5b 100644 --- a/docs/how-the-build-process-works.md +++ b/docs/how-the-build-process-works.md @@ -1,43 +1,59 @@ -## How the build process works +# How the Build Process Works -The following process is followed to build images: +`build.sh` iterates through stage directories in alphanumeric order and processes each one. - * Iterate through all of the stage directories in alphanumeric order +## Stage Processing - * Bypass a stage directory if it contains a file called - "SKIP" +For each stage directory: - * Run the script `prerun.sh` which is generally just used to copy the build - directory between stages. +1. Skip the stage entirely if a `SKIP` file is present. +2. Run `prerun.sh` — typically copies the rootfs from the previous stage. +3. Iterate through each numbered subdirectory (e.g. `00-configure-apt`, `01-sys-tweaks`) in order. +4. Within each subdirectory, process these files if present: - * In each stage directory iterate through each subdirectory and then run each of the - install scripts it contains, again in alphanumeric order. **These need to be named - with a two digit padded number at the beginning.** - There are a number of different files and directories which can be used to - control different parts of the build process: +| File | Description | +|------|-------------| +| `00-run.sh` | Shell script run on the host (must be executable) | +| `00-run-chroot.sh` | Shell script run inside the chroot (must be executable) | +| `00-debconf` | Passed to `debconf-set-selections` | +| `00-packages` | Packages installed via `apt-get install` | +| `00-packages-nr` | Same, but with `--no-install-recommends` | +| `00-packages-` | Arch-specific packages (e.g. `00-packages-amd64`, `00-packages-arm-only`) | +| `00-packages-nr-` | Arch-specific packages without recommends | +| `00-patches` | Directory of quilt patches applied to the rootfs | +| `00-patches-` | Arch-specific quilt patches | - - **00-run.sh** - A unix shell script. Needs to be made executable for it to run. +5. If the stage contains `EXPORT_IMAGE`, `EXPORT_ISO`, or `EXPORT_SQUASHFS` (and `SKIP_IMAGES` is not present), add it to the export queue. - - **00-run-chroot.sh** - A unix shell script which will be run in the chroot - of the image build directory. Needs to be made executable for it to run. +## Export Pipeline - - **00-debconf** - Contents of this file are passed to debconf-set-selections - to configure things like locale, etc. +After all stages are processed, the build runs the export pipeline for each queued stage: - - **00-packages** - A list of packages to install. Can have more than one, space - separated, per line. +| 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 | - - **00-packages-nr** - As 00-packages, except these will be installed using - the `--no-install-recommends -y` parameters to apt-get. +Multiple marker files can coexist in the same stage — all matching exports will run. - - **00-patches** - A directory containing patch files to be applied, using quilt. - If a file named 'EDIT' is present in the directory, the build process will - be interrupted with a bash session, allowing an opportunity to create/revise - the patches. +### export-iso pipeline - * If the stage directory contains files called "EXPORT_NOOBS" or "EXPORT_IMAGE" then - add this stage to a list of images to generate +1. `prerun.sh` — rsync rootfs into work dir +2. `01-set-sources` — clean apt caches, run final upgrade +3. `02-network` — configure resolv.conf +4. `03-finalise` — rewrite fstab for live use, generate initramfs, build squashfs, build ISO with `grub-mkrescue` - * Generate the images for any stages that have specified them +### export-squashfs pipeline -It is recommended to examine build.sh for finer details. \ No newline at end of file +1. `prerun.sh` — rsync rootfs into work dir +2. `00-finalise` — create squashfs and deploy + +## Arch-Specific Logic + +Scripts and package files support arch suffixes: +- `-arm-only` — runs on `arm64` and `armhf` only +- `-amd64` — runs on `amd64` only +- `-${ARCH}` — can be any specific arch string + +Scripts that handle arch themselves check `${ARCH}` and exit early if not applicable. diff --git a/docs/stage-anatomy.md b/docs/stage-anatomy.md index 295bd4c..ba8647a 100644 --- a/docs/stage-anatomy.md +++ b/docs/stage-anatomy.md @@ -1,84 +1,61 @@ -## Stage Anatomy +# Stage Anatomy -### Raspbian Stage Overview +ChillcraftOS is built in stages. Each stage builds on the previous one. -The build of Raspbian is divided up into several stages for logical clarity -and modularity. This causes some initial complexity, but it simplifies -maintenance and allows for more easy customization. +## Stages - - **Stage 0** - bootstrap. The primary purpose of this stage is to create a - usable filesystem. This is accomplished largely through the use of - `debootstrap`, which creates a minimal filesystem suitable for use as a - base.tgz on Debian systems. This stage also configures apt settings and - installs `raspberrypi-bootloader` which is missed by debootstrap. The - minimal core is installed but not configured. As a result, this stage will not boot. +### Stage 0 — Bootstrap - - **Stage 1** - truly minimal system. This stage makes the system bootable by - installing system files like `/etc/fstab`, configures the bootloader, makes - the network operable, and installs packages like raspi-config. At this - stage the system should boot to a local console from which you have the - means to perform basic tasks needed to configure and install the system. +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. - - **Stage 2** - lite system. This stage produces the Raspberry Pi OS Lite image. - Stage 2 installs some optimized memory functions, sets timezone and charmap - defaults, installs fake-hwclock and ntp, wireless LAN and bluetooth support, - dphys-swapfile, and other basics for managing the hardware. It also - creates necessary groups and gives the pi user access to sudo and the - standard console hardware permission groups. +- RPi: installs `raspi-firmware`, `linux-image-rpi-v8`, `linux-image-rpi-2712` +- amd64: installs `grub2`, `linux-image-amd64` - Note: Raspberry Pi OS Lite contains a number of tools for development, - including `Python`, `Lua` and the `build-essential` package. If you are - creating an image to deploy in products, be sure to remove extraneous development - tools before deployment. +### Stage 1 — Minimal Bootable System - - **Stage 3** - desktop system. Here's where you get the full desktop system - with X11 and LXDE, web browsers, git for development, Raspberry Pi OS custom UI - enhancements, etc. This is a base desktop system, with some development - tools installed. +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. - - **Stage 4** - Normal Raspberry Pi OS image. System meant to fit on a 4GB card. - This is the stage that installs most things that make Raspberry Pi OS friendly - to new users - e.g. system documentation. +- RPi fstab: `/boot/firmware` (vfat) + btrfs root with subvolumes +- amd64 fstab: `/boot` (vfat) + `/boot/efi` + btrfs root with subvolumes - - **Stage 5** - The Raspberry Pi OS Full image. More development - tools, an email client, learning tools like Scratch, specialized packages - like sonic-pi, office productivity, etc. +Both use btrfs subvolumes: `@`, `@home`, `@var`, `@snapshots`. -### Stage specification +### Stage 2 — System Layer -If you wish to build up to a specified stage (such as building up to stage 2 -for a lite system), place an empty file named `SKIP` in each of the `./stage` -directories you wish not to include. +Installs the core system utilities, tools, and services. This is the "lite" layer. -Then add an empty file named `SKIP_IMAGES` to `./stage4` and `./stage5` (if building up to stage 2) or -to `./stage2` (if building a minimal system). +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. ```bash -# Example for building a lite system -echo "IMG_NAME='raspios'" > config -touch ./stage3/SKIP ./stage4/SKIP ./stage5/SKIP -touch ./stage4/SKIP_IMAGES ./stage5/SKIP_IMAGES -sudo ./build.sh # or ./build-docker.sh +# Only rebuild stage3 (assumes stage0-2 already built) +touch stage0/SKIP stage1/SKIP stage2/SKIP +sudo CLEAN=1 ./build.sh -c config ``` - -If you wish to build further configurations upon (for example) the lite -system, you can also delete the contents of `./stage3` and `./stage4` and -replace with your own contents in the same format. - - -## Skipping stages to speed up development - -If you're working on a specific stage the recommended development process is as -follows: - - * Add a file called SKIP_IMAGES into the directories containing EXPORT_* files - (currently stage2, stage4 and stage5) - * Add SKIP files to the stages you don't want to build. For example, if you're - basing your image on the lite image you would add these to stages 3, 4 and 5. - * Run build.sh to build all stages - * Add SKIP files to the earlier successfully built stages - * Modify the last stage - * Rebuild just the last stage using `sudo CLEAN=1 ./build.sh` (or, for docker builds - `PRESERVE_CONTAINER=1 CONTINUE=1 CLEAN=1 ./build-docker.sh`) - * Once you're happy with the image you can remove the SKIP_IMAGES files and - export your image to test \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ee71b90..4aa4227 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,45 +1,59 @@ # Troubleshooting -## `64 Bit Systems` -A 64 bit image can be generated from the `arm64` branch in this repository. Just -replace the command from [this section](#getting-started-with-building-your-images) -by the one below, and follow the rest of the documentation: -```bash -git clone --branch arm64 https://github.com/RPI-Distro/pi-gen.git -``` +## binfmt_misc (cross-arch builds) -If you want to generate a 64 bits image from a Raspberry Pi running a 32 bits -version, you need to add `arm_64bit=1` to your `config.txt` file and reboot your -machine. This will restart your machine with a 64 bits kernel. This will only -work from a Raspberry Pi with a 64-bit capable processor (i.e. Raspberry Pi Zero -2, Raspberry Pi 3 or Raspberry Pi 4). - - -## `binfmt_misc` - -Linux is able to execute binaries from other architectures, meaning that it should be -possible to make use of `pi-gen` on an x86_64 system, even though it will be running -ARM binaries. This requires support from the [`binfmt_misc`](https://en.wikipedia.org/wiki/Binfmt_misc) -kernel module. - -You may see one of the following errors: +When building ARM images on an x86_64 host, Linux uses `binfmt_misc` to run ARM binaries via QEMU. If you see: ``` update-binfmts: warning: Couldn't load the binfmt_misc module. -``` -``` -W: Failure trying to run: chroot "/pi-gen/work/test/stage0/rootfs" /bin/true -and/or chroot: failed to run command '/bin/true': Exec format error ``` -To resolve this, ensure that the following files are available (install them if necessary): +Fix: -``` -/lib/modules/$(uname -r)/kernel/fs/binfmt_misc.ko -/usr/bin/qemu-aarch64-static +```bash +sudo modprobe binfmt_misc +sudo apt-get install qemu-user-static binfmt-support +sudo update-binfmts --enable ``` -You may also need to load the module by hand - run `modprobe binfmt_misc`. +On WSL2 you may need to install `binfmt-support` on the host Windows side or use Docker instead. -If you are using WSL to build you may have to enable the service `sudo update-binfmts --enable` \ No newline at end of file +## "Required dependencies not installed" + +The `depends` file lists tools that must be present on the build host. Read the README for the current install commands. + +Note: `grub-efi-amd64-bin` and `grub-pc-bin` are data packages with no associated binary — they are not checked by the dependency checker but must be installed for `grub-mkrescue` to work. + +## ISO doesn't boot + +- Verify the ISO was written correctly: use Balena Etcher or `dd` — do not just copy the file. +- In VMware/VirtualBox, set firmware to UEFI. +- If GRUB appears but the system hangs after selecting a menu entry, try the "safe mode" entry (adds `nomodeset`). + +## Squashfs / initramfs errors during export-iso + +- `mkinitramfs: failed to determine device for /` — This happens when `MODULES=dep` is set in a chroot. The build sets `MODULES=most` to avoid this. +- `W: Couldn't identify type of root file system` — Expected during initramfs generation in a live build; the fstab is rewritten for live-boot and has no real block devices to detect. + +## Stage fails despite SKIP file + +`SKIP` files only skip re-running the stage scripts. They do not skip the export pipeline. Use `SKIP_IMAGES` to skip exports while still running the stage. + +## Build fails on NTFS / exFAT partition + +The work directory must be on a Linux filesystem (ext4, btrfs, xfs). NTFS and exFAT do not support the required file attributes. Set `WORK_DIR` to a path on a Linux filesystem: + +```bash +export WORK_DIR=/mnt/linux-disk/chillcraftos-work +``` + +## Apt errors: "doesn't support architecture" + +The ChillcraftOS apt repo (`cdn.oxmc.me/apt`) currently only supports `arm64`/`armhf`. On amd64 builds you will see: + +``` +Notice: Skipping ... doesn't support architecture 'amd64' +``` + +This is expected and not an error — standard Debian repos are used for amd64 packages. diff --git a/export-iso/03-finalise/01-run.sh b/export-iso/03-finalise/01-run.sh index 27c6592..363ecb6 100755 --- a/export-iso/03-finalise/01-run.sh +++ b/export-iso/03-finalise/01-run.sh @@ -64,7 +64,7 @@ insmod all_video insmod gfxterm menuentry "ChillcraftOS Live" { - linux /boot/vmlinuz boot=live components live-config.nocomponents quiet splash + linux /boot/vmlinuz boot=live components live-config.nocomponents splash initrd /boot/initrd.img } diff --git a/stage2/01-sys-tweaks/00-packages b/stage2/01-sys-tweaks/00-packages index fcfc816..6eefc56 100644 --- a/stage2/01-sys-tweaks/00-packages +++ b/stage2/01-sys-tweaks/00-packages @@ -1,4 +1,4 @@ -ssh less fbset sudo psmisc strace ed ncdu +ssh less fbset sudo psmisc strace ed ncdu zsh zsh-common console-setup keyboard-configuration debconf-utils parted build-essential manpages-dev bash-completion gdb pkg-config btrfs-progs @@ -27,4 +27,5 @@ udisks2 unzip zip p7zip-full file python3-venv +hyfetch cups \ No newline at end of file diff --git a/stage2/01-sys-tweaks/00-patches/01-useradd.diff b/stage2/01-sys-tweaks/00-patches/01-useradd.diff index cc3476b..0feb437 100644 --- a/stage2/01-sys-tweaks/00-patches/01-useradd.diff +++ b/stage2/01-sys-tweaks/00-patches/01-useradd.diff @@ -5,7 +5,7 @@ # useradd is a low level utility and should be as general # as possible -SHELL=/bin/sh -+SHELL=/bin/bash ++SHELL=/bin/zsh # # The default group for users # 100=users on Debian systems diff --git a/stage2/01-sys-tweaks/00-patches/03-path.diff b/stage2/01-sys-tweaks/00-patches/03-path.diff index 29c5ee5..73c8fab 100644 --- a/stage2/01-sys-tweaks/00-patches/03-path.diff +++ b/stage2/01-sys-tweaks/00-patches/03-path.diff @@ -5,7 +5,7 @@ # (they are minimal, add the rest in the shell startup files) ENV_SUPATH PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin -ENV_PATH PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games -+ENV_PATH PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/games:/usr/games ++ENV_PATH PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/games:/usr/games # # Terminal permissions for terminals after login(1). diff --git a/stage3/01-install-desktop/00-packages b/stage3/01-install-desktop/00-packages index c8735a2..4a28170 100644 --- a/stage3/01-install-desktop/00-packages +++ b/stage3/01-install-desktop/00-packages @@ -1,7 +1,6 @@ python3-pip python3-numpy tree -hyfetch libgl1-mesa-dri libgles1 xcompmgr ffmpeg vlc diff --git a/stage3/01-install-desktop/01-packages b/stage3/01-install-desktop/01-packages new file mode 100644 index 0000000..636b83a --- /dev/null +++ b/stage3/01-install-desktop/01-packages @@ -0,0 +1 @@ +chillcraftos-plymouth-theme diff --git a/stage3/01-install-desktop/01-packages-arm-only b/stage3/01-install-desktop/01-packages-arm-only index b9d8120..c3decbb 100644 --- a/stage3/01-install-desktop/01-packages-arm-only +++ b/stage3/01-install-desktop/01-packages-arm-only @@ -1,2 +1,2 @@ pprompt -chillcraftos-plymouth-theme chillcraftos-default-settings hyfetch +chillcraftos-default-settings