Main base maybe?
This commit is contained in:
+66
-116
@@ -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.
|
||||
+31
-23
@@ -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.
|
||||
```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
|
||||
```
|
||||
|
||||
+56
-30
@@ -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 `<tool>[:<debian-package>]`.
|
||||
The `depends` file in the repo root lists all required tools in `<tool>[:<debian-package>]` 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.
|
||||
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.
|
||||
|
||||
@@ -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>` | Arch-specific packages (e.g. `00-packages-amd64`, `00-packages-arm-only`) |
|
||||
| `00-packages-nr-<arch>` | Arch-specific packages without recommends |
|
||||
| `00-patches` | Directory of quilt patches applied to the rootfs |
|
||||
| `00-patches-<arch>` | 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.
|
||||
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.
|
||||
|
||||
+46
-69
@@ -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
|
||||
+46
-32
@@ -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`
|
||||
## "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.
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
python3-pip
|
||||
python3-numpy
|
||||
tree
|
||||
hyfetch
|
||||
libgl1-mesa-dri libgles1 xcompmgr
|
||||
ffmpeg
|
||||
vlc
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
chillcraftos-plymouth-theme
|
||||
@@ -1,2 +1,2 @@
|
||||
pprompt
|
||||
chillcraftos-plymouth-theme chillcraftos-default-settings hyfetch
|
||||
chillcraftos-default-settings
|
||||
|
||||
Reference in New Issue
Block a user