_ Example variables: IGconf_device_class=pi5 IGconf_device_storage_type=sd IGconf_image_compression=zstd ``` -------------------------------- ### Environment Variable Validation Examples Source: https://raspberrypi.github.io/rpi-image-gen/layer/variable-validation Demonstrates how to define environment variables with various validation rules, including integer ranges, allowed values, regular expressions, boolean types, and keyword selections. These examples are crucial for ensuring data integrity within the build configuration. ```shell # Port number validation X-Env-Var-port-Valid: int:1024-65535 # Environment selection X-Env-Var-env-Valid: development,staging,production # Hostname validation X-Env-Var-hostname-Valid: regex:^[a-zA-Z0-9.-]+$ # Boolean flag X-Env-Var-debug-Valid: bool # Component selection with keywords X-Env-Var-component-Valid: keywords:frontend,backend,database ``` -------------------------------- ### Skip Splash Screen Installation Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-splash-screen Shows how to configure the rpi-splash-screen layer to skip the installation of the splash screen by setting the `image_path` to an empty string. ```yaml layer: base: trixie-minbase splash: rpi-splash-screen splash: image_path: "" # Empty string skips installation ``` -------------------------------- ### Environment Variable Expansion in rpi-image-gen Source: https://raspberrypi.github.io/rpi-image-gen/config/index Provides examples of environment variable expansion within rpi-image-gen configuration files. Variables enclosed in '${...}' are resolved during the pipeline phase, allowing for dynamic values based on other variables or system information. This supports forward declarations and deferred resolution. ```yaml device: name: controllerbox rev: 2 hostname: ${IGconf_device_name}-$(uuidgen | cut -d'-' -f1) image: assetdir: ${WORKSPACE}/build/assets/${IGconf_device_name}-rev${IGconf_device_rev} ssh: pubkey_user1: ${DEPLOY}/device/baseassets/id_rsa.pub pubkey_only: y ``` -------------------------------- ### Provision Image with IDP Helper Script Source: https://raspberrypi.github.io/rpi-image-gen/provisioning/index This command uses the `idp.sh` helper script from rpi-image-gen to provision an image on a target device using a JSON description file. Ensure `rpiboot` and the `pi-gen-micro` fastboot gadget are set up on the target device. ```bash ./bin/idp.sh -f /path/to/image.json ``` -------------------------------- ### Flash Sparse Image using Fastboot Source: https://raspberrypi.github.io/rpi-image-gen/provisioning/index This command demonstrates how to directly flash a sparse image to device storage using conventional fastboot commands. This is an alternative to using the `idp.sh` script and is useful for direct image writing. ```bash fastboot flash mmcblk0 /path/to/fullimage.sparse ``` -------------------------------- ### Set Authentication Key via Command Line Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-connect-lite Demonstrates how to set the `IGconf_connect_authkey` configuration variable using the command line during the image build process. This allows for automated linking of the device to a Raspberry Pi Connect account. ```bash rpi-image-gen build -- IGconf_connect_authkey=$KEY ``` -------------------------------- ### Lenient Validation for Splash Screen Testing Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-splash-screen Provides an example of configuring the rpi-splash-screen layer for testing purposes by skipping image validation checks. This is achieved by setting `skip_image_checks` to 'y'. ```yaml layer: base: trixie-minbase splash: rpi-splash-screen splash: image_path: /path/to/test-splash.tga skip_image_checks: y # For testing only ``` -------------------------------- ### Configuration Variable Naming Convention Source: https://raspberrypi.github.io/rpi-image-gen/layer/index Demonstrates the standard naming convention for configuration variables in rpi-image-gen, which follows the pattern `IGconf__`. It shows how layer-declared variables are transformed into environment variables and how they can be referenced in templates. ```text Layer declares : X-Env-Var-hostname with prefix device Environment variable : IGconf_device_hostname Template expansion : Can reference as ${IGconf_device_hostname} in YAML values ``` -------------------------------- ### Placeholder Support in Configuration Source: https://raspberrypi.github.io/rpi-image-gen/layer/index Illustrates the use of dynamic placeholders within configuration variable values. These placeholders allow for dynamic insertion of information related to the layer file's location and name during the build process. ```text ${DIRECTORY}: Directory containing the layer file ${FILENAME}: Name of the layer file (without extension) ${FILEPATH}: Full path to the layer file ``` -------------------------------- ### Specifying Arbitrary Layers in Configuration Source: https://raspberrypi.github.io/rpi-image-gen/layer/index Demonstrates how to specify multiple arbitrary layers in the configuration file. The names of the variables holding the layer names are flexible, allowing users to organize their layer specifications as needed. ```yaml layer: foo: trixie-minbase bar: rpi5 app: my-app ``` -------------------------------- ### Command for Validation Help Source: https://raspberrypi.github.io/rpi-image-gen/layer/index Shows the command to access help information regarding variable validation rules and policies within rpi-image-gen. This command is essential for understanding how configuration variables are validated during the build process. ```bash rpi-image-gen metadata --help-validation ``` -------------------------------- ### Include Configuration Files in rpi-image-gen (YAML) Source: https://raspberrypi.github.io/rpi-image-gen/config/index Demonstrates how to include other YAML configuration files within the rpi-image-gen build system. This promotes modularity by allowing shared configurations to be reused across different build definitions. The inclusion mechanism respects a defined precedence order. ```yaml include: file: shared/base.yaml ``` -------------------------------- ### Specifying Device/Image Layers in Configuration Source: https://raspberrypi.github.io/rpi-image-gen/layer/index Presents two methods for specifying device and image layers in the configuration file. The first method directly embeds the layer name, while the second allows the user to define a variable for the layer name, offering more customization. ```yaml device: layer: rpi5 ``` ```yaml layer: myvar: rpi5 ``` -------------------------------- ### Resulting Environment Variables for Layer Specification Source: https://raspberrypi.github.io/rpi-image-gen/layer/index Illustrates the environment variables generated from the configuration snippets for specifying device and image layers. This shows how rpi-image-gen translates the configuration into internal variables for layer resolution. ```text IGconf_device_layer=rpi5 IGconf_layer_myvar=rpi5 ``` -------------------------------- ### Basic Configuration for rpi-splash-screen Layer Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-splash-screen Demonstrates the basic configuration for enabling the rpi-splash-screen layer, including specifying the base layer and the path to the custom splash image. ```yaml layer: base: trixie-minbase splash: rpi-splash-screen splash: image_path: /home/user/my-logo.tga ``` -------------------------------- ### Set Authentication Key via Configuration File (Value) Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-connect-lite Shows how to set the `IGconf_connect_authkey` variable directly within a configuration file using the authentication key value. This is an alternative to providing a file path for automatic device linking to a Raspberry Pi Connect account. ```yaml connect: authkey: $KEY ``` -------------------------------- ### Set Authentication Key via Configuration File (Path) Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-connect-lite Illustrates setting the `IGconf_connect_authkey` variable in a configuration file to an absolute path. This method is used to automatically link the device to a Raspberry Pi Connect account by referencing a file containing the authentication key. ```yaml connect: authkey: /path/to/file ``` -------------------------------- ### Layer Variable Dependencies in rpi-image-gen Source: https://raspberrypi.github.io/rpi-image-gen/config/index Illustrates how layer dependencies in rpi-image-gen can be dynamically resolved using configuration or command-line variables. This allows layers to specify requirements that adapt based on build-time parameters like architecture or distribution. ```yaml # METABEGIN # X-Env-Layer-Name: arch-specific-tools # X-Env-Layer-Requires: base-layer,${ARCH}-toolchain,${DISTRO}-packages # METAEND ``` -------------------------------- ### Command Substitution with Variable Assignment in rpi-image-gen Source: https://raspberrypi.github.io/rpi-image-gen/config/index Demonstrates how to use command substitution within variable assignments on the rpi-image-gen command line. This allows the output of a shell command to be assigned to a configuration variable. Proper shell quoting is essential to ensure correct expansion. ```bash rpi-image-gen build -c config.yaml -- "IGconf_ssh_pubkey_user1=$(< /path/to/.ssh/id_rsa.pub)" ``` ```bash rpi-image-gen build -c config.yaml -- 'IGconf_ssh_pubkey_user1=$(cat /path/to/.ssh/id_rsa.pub)' ``` -------------------------------- ### Cross-Reference Variable Expansion in rpi-image-gen Source: https://raspberrypi.github.io/rpi-image-gen/config/index Shows how variables within rpi-image-gen configuration files can reference other defined variables. This enables dynamic configuration where values depend on previously set variables, promoting flexibility and reducing redundancy. ```yaml device: class: pi5 hostname: ${IGconf_device_class}-server image: name: ${IGconf_device_class}-custom-image ``` -------------------------------- ### Custom Boot Configuration with rpi-splash-screen Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-splash-screen Illustrates how to use the rpi-splash-screen layer while disabling automatic modification of `cmdline.txt` by setting `update_cmdline` to 'n'. This is useful for custom boot configurations. ```yaml layer: base: trixie-minbase splash: rpi-splash-screen splash: image_path: /path/to/splash.tga update_cmdline: n # Don't modify cmdline.txt automatically ``` -------------------------------- ### Include Configuration Files in rpi-image-gen (INI) Source: https://raspberrypi.github.io/rpi-image-gen/config/index Illustrates the INI file include syntax for rpi-image-gen. Similar to YAML includes, this feature allows for the reuse of configuration snippets, enhancing project organization. The system resolves included files based on parent directory and search paths. ```ini !include shared/base.cfg ```