ChillcraftOS/docs/stage-anatomy.md

Stage Anatomy

Raspbian Stage Overview

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.

• 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 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.

• 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.

  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 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.

• 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.

• 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.

Stage specification

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.

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).

# 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

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