Excluding environment keys, configuration variables in rpi-image-gen use the IGconf_ prefix followed by a structured naming pattern:

Where:

Example variables:

Variables are declared by layer YAML files using metadata headers within comment blocks:

Anchors are declared in a variable’s metadata and are definitive remapping points for paths and other environment values. They allow locations to be described in an abstract way (eg, @IGROOT, @SRCROOT) and are resolved by the engine automatically, never leaking to the shell. Anchors enable support of different contexts (eg, host vs. container, with different root paths) without rewriting layer or config files. The resolver replaces ${@ANCHOR} with the concrete value from the anchor registry when producing the final environment. From a simplistic viewpoint, an anchor is essentially a shortcut to a variable’s value.

The engine automatically sets a small number of default anchors. These are listed below:

An Anchor is declared in layer metadata as follows:

An anchor can be used in a config file as follows:

In this case, when building sources via -S, IGconf_splash_image_path resolves to /path/to/source/dir/my.tga. This can be observed in the output:

In addition to mapping (key-value) sections, YAML configuration files support sequence (list) sections. List items are assigned 0-based numeric keys, producing the same IGconf_<section>_<key> variable format as mapping sections.

This produces the following variables:

This is equivalent to the explicit mapping form:

List sections are useful when the key names are not meaningful and only ordering matters. They follow the same include merging and override rules as mapping sections.

Configuration files support includes to promote reusability and modularity.

A single file is included using a mapping with a file key:

Multiple files are included using a list of filenames. Files are processed in order - later entries override earlier ones. The including file overrides all included content.

Include files are resolved using the following search order:

The device section (X-Env-VarPrefix: device) holds variables describing the target hardware. Variables in this section are declared by device-base and downstream device layers.

The device.layer key has functional meaning: it’s one way to specify the device layer to include in the build.

The image section (X-Env-VarPrefix: image) holds variables that control image construction. Variables in this section are declared by image-base and downstream image layers.

The image.layer key has functional meaning: it’s one way to specify the image layer to include in the build.

The layer section is used to specify layers to include in the build. Each key names an extra layer:

The key names are arbitrary - only the values matter. Lists are also supported. This is the primary mechanism for composing a build from multiple optional layers. Device and image layers can be specified here, too:

The packages section triggers automatic package installation into the target rootfs during the build. Each entry is either an apt package name or a path to a local .deb file on the build host.

Local .deb files are specified by path and are detected by the presence of the file on the build host at the time the hook runs:

Both list and mapping forms are supported. Local .deb files are installed before apt packages so that apt can satisfy any dependencies they introduce.

Absolute paths are fully supported. Relative paths are resolved from the source directory and require -S to be specified, falling back to the rpi-image-gen root directory.

Unlike every other section, trait: is never translated to IGconf_<section>_* variables. It’s a reserved top-level key, passed through as-is and applied directly as a build-time override to the trait registry - taking precedence over anything declared by the registry itself or by a layer’s X-Env-Layer-Provides.

false removes the named token (and any of its children, by prefix match) from the build’s provider index, even if a layer in the build declares it. Any other value - true for a boolean trait, or an explicit typed value otherwise - injects the token, exactly as if a layer had declared it. Trait overrides merge across includes like any other section - the including file’s entries win over an included file’s on a shared token, and non-overlapping tokens from both are kept.

See trait.adoc for the full trait registry reference, including token namespaces, hierarchy, and has().

Variables can be set directly on the command line as overrides after --, taking the highest precedence:

Command-line overrides are handled by the calling shell before the engine sees them.

Variable values may include parameter expansion or command substitution. To be expanded by the engine, they must use one of these forms:

Any other $ (eg, $VAR or $6$…​) is treated as literal and will be escaped.

Care must be taken if using the command line to assign a value to a variable if the value contains spaces or newlines. Making sure the calling shell expands it into a single argument ensures the command substitution happens once and stays on one line:

Assigning a variable and preserving the literal value can be performed using single quotes:

The above yield identical results in the build configuration for the value of IGconf_ssh_pubkey_user1. The difference is that the first expands the value immediately upon assignment using the calling shell (eg Bash) before engine processing. The second keeps the literal text, which is expanded during engine processing using POSIX-sh.

Variables are resolved after configuration parsing and layer assembly, and then expanded. Expansion is performed with a strict policy using /bin/sh with POSIXLY_CORRECT=1 under set -eu in a 'clean room' environment. This means:

Variables can reference other configuration variables:

Layer dependencies can use config or command line variable assignments to create dynamic dependency resolution:

This allows layers to dynamically depend on other layers based on build-time set variables:

This feature enables dynamic layer selection. For example, one usage could be to use the same layer across different build environments to support toolchain selection based on target architecture. By using variables in the 'parent' layer, dynamic dependency resolution pulls in an architecture specific toolchain 'child' layer.

The configuration system processes files using the following steps:

The config command provides direct access to configuration functionality:

Generate an example YAML configuration:

The configuration system integrates with the layer management system to:

Variables support different assignment policies:

Refer to the layer documentation for further details.

Variables are processed in layer dependency order, ensuring that:

Configuration loading outputs show variable sources:

Layer collection output shows variable policy and evaluated value: