This philosophy enables a user to have self-contained projects with external dependencies.

Validate input arguments, parse configuration files, and establish the initial environment for subsequent stages.

Discover, validate, and order all layers specified in the configuration, and expand all configuration variables to their final values.

Set up the build environment and assemble bdebstrap parameters with the necessary configuration.

Create the filesystem and generate the Software Bill of Materials.

Create disk images from the prepared filesystem using the provider.

Install output assets from the build to a defined location for distribution.

Install and compress:

Two distinct kinds of hook exist. A layer may declare hooks natively inline in its own YAML (eg mmdebstrap: customize-hooks:) - these run as bdebstrap merges and executes each phase’s hook list, and are documented alongside the rest of a layer’s YAML, not here.

rpi-image-gen runs the other kind - standalone hook files - in phases via script bin/runner. Runner is the single entry point every standalone hook runs through. bdebstrap invokes it for each lifecycle phase (setup, customize, etc.), wired in as the last hook bdebstrap runs for that phase - so every standalone hook runner finds (per-layer, source tree, or built-in) always runs after every layer’s own inline YAML hooks for the same phase. The main script calls runner directly for image, SBOM, and deploy phases, which have no YAML-native hook equivalent since they run outside bdebstrap entirely. Runner:

The phase name is the only key runner works from - it is the prefix every hook and overlay is discovered by, and every phase takes the same path through runner. Within a phase, work happens in a fixed order, and any step with nothing to do is simply skipped:

Consequently a phase needs no special-casing to gain a hook or an overlay: shipping a file whose name starts with the phase, in the right place, is the whole of it.

For every phase, runner scans two kinds of location, always in this order:

Runner scans for <phase>* hooks (eg customize*, preimage05-do-something) inside hooks/ subdirectories at each location, executing matching hooks (alphanumeric basename) in lexicographic order - hence the numbered-prefix convention used throughout (customize01-, essential01, cleanup50-apt-cache, etc), which controls run order for multiple hooks at the same location and phase. Subdirectories aren’t traversed; the file extension is ignored.

A per-layer hook runs from its own directory, so anything else the layer ships must be reached through the environment runner provides it:

A hook reading a template the layer ships alongside its YAML therefore writes "$LAYER_DIR/genimage.cfg.in" rather than relying on the working directory.

Two independent overlay mechanisms exist, applied at different times for different reasons.

Per-layer overlays are named after the phase that applies them. A layer ships <layer-stem>.d/<phase>.overlay (eg my-layer.yaml has my-layer.d/customize.overlay/) and it is applied when that phase runs, immediately before that layer’s own hooks for the same phase. Any phase will do - no table lists them - though in practice three are useful:

No metadata declares the timing - the directory name is the whole declaration, so deferring content until after filesystem construction is a matter of naming the directory preimage.overlay rather than customize.overlay.

customize.overlay is the one runner does not apply itself; it is applied by the layer’s synthesised pre-config, which is what buys it the position ahead of that layer’s own customize-hooks.

Overlays are applied with rsync and include --chmod=go-w, so a file keeps whatever mode it declares except that the transfer cannot make it group or world writable. Anything needing to be widely writable in the built filesystem must be made so by a hook rather than by shipping it that way.

<layer-stem>.d/rootfs-overlay and <layer-stem>.d/overlay are both accepted as compat spellings of customize.overlay, offering perhaps a more intuitive or human-readable name for an overlay directory. It’s not recommended to mix more than one of these.

A layer needs no mmdebstrap: mapping of its own to ship an overlay - every layer in the plan is offered pre/post synthesis.

Source-tree overlays are applied during the customize phase by bin/runner:

These apply once, after every layer’s own customize-hooks have already run.

rpi-image-gen ships its own hooks to perform generic tasks. Depending on requirements, there may not be a need to add custom hooks at these stages as the generic hooks execute after SRCROOT hooks.

IGconf_device_assetdir and IGconf_image_assetdir no longer resolve hooks or initramfs content on their own - a device or image layer’s hooks belong in its own <layer-stem>.d/hooks/, found through the build plan like any other layer’s, and initramfs content follows the same pattern, described below. The variables themselves are still ordinary config values a layer’s own hooks can read directly for whatever they need - eg installing a file that lives in the asset directory, or locating a template by a naming convention of the layer’s own choosing.

dracut and initramfs-tools are mutually exclusive initramfs generators, so a layer contributing to either ships its content under its own <layer-stem>.d/device/, in the directory matching the generator it targets:

Every layer that ships any of these has its content copied in, in build plan order, during customize, via a built-in hook - one for whichever of dracut/initramfs-tools is actually installed in the chroot, immediately before it (re)generates the initramfs.