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:

YAML provides the most flexible configuration format with native support for hierarchical data and includes.

INI format provides traditional section-based configuration:

Both formats support including other configuration files to promote reusability and modularity. The include precedence order is shown in the table below.

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.

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 example configuration files:

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:

Use the built-in migration tool:

The migration tool:

The configuration system maintains compatibility with: