Recipes
As part of the build process, recipes perform the actual work, creating and modifying build outputs. Each recipe consists of a sequence of steps to be executed. Recipes are defined by directories in the recipes directory. Each recipe gets its own directory with a recipe configuration file recipe.toml and a steps subdirectory defining the individual steps to be executed. The configuration file may specify a description, a priority, dependencies of the recipe, and parameters.
Here is the configuration of the core/ssh recipe as an example:
#:schema https://raw.githubusercontent.com/silitics/rugix/refs/tags/v0.8.0/schemas/rugix-bakery-layer.schema.json
description = "enabling SSH"
priority = 80_000
dependencies = ["pkg-update"]
[parameters]
root_authorized_keys = { default = "" }
The ssh recipe depends on the pkg-update recipe1 from Rugix Bakery's core repository. The pkg-update recipe will update the package lists of the distribution (Debian or Alpine), which is required to be able to install SSH. It will also later remove the package lists from the build, as they are unnecessary at runtime. The configuration further defines a parameter, root_authorized_keys, with an empty default value. The steps of the recipe use this parameter to install public keys for SSH access.
Recipes are always applied in the order of their priority (higher means earlier). In particular, this means that dependencies may be applied after recipes that depend on them, if they have a lower priority. Note that priorities can also be negative.
Check out the set of core recipes for examples.
Parameters
The parameters of a recipe are defined in the parameters section of its configuration. Every parameter has a name and an optional default value. Here is an example for how to define parameters with and without default values:
[parameters]
parameter_name = { default = "a default value" }
other_parameter = {} # Required parameter without a default value.
Parameter values are provided by layer configurations in the parameters section. For the details, we refer back to the layers section of this documentation. Layer configurations must provide values for all parameters that do not have a default.
Parameter values are exposed to a recipe's steps (see below) via environment variables of the form RECIPE_PARAM_<PARAM_NAME>. So, in case of our example, RECIPE_PARAM_PARAMETER_NAME and RECIPE_PARAM_OTHER_PARAMETER.
Avoid hard-coding configuration values in your recipes and use parameters instead.
Steps
Each recipe consists of a sequence of steps to be executed. Each step is defined by a file in the steps directory of a recipe. The names of the files in that directory must start with an integer followed by a - and a step kind. The integer indicates the position of the step in the recipe, e.g., 00 to 99. Currently, Rugix Bakery supports three kinds of steps.
packages
Steps of the kind packages can be used to provide lists of packages to install:
a
list
of
packages
Rugix Bakery supports APT (Debian) and APK (Alpine) and will automatically select the correct package manager for a given system. The step filenames can also be suffixed with .apt and .apk to provide different package lists for APT and APK.
run
Steps of the kind run can be used to run scripts on the host/within the build environment:
#!/usr/bin/env bash
echo "This runs on the host system."
These scripts are not limited to bash and can have an arbitrary file extension, e.g., .py for Python scripts. They must have a shebang (first line starting with #!) and must have the executable bit set (chmod +x).
Rugix Bakery exposes multiple environment variables that can be used in such scripts. You will find more details below.
When using run steps, you have to be a bit careful to not modify the build environment itself. For instance, when you install files or packages into the build environment, then they may persist and affect later steps.2
You can use run steps to perform all kinds of tasks. For instance, the yocto-build recipe of the Yocto template sets up a temporary Python virtual environment to install KAS and will then run an entire Yocto build via KAS.
install
Steps of the kind install can be used to run scripts inside the system being built:
#!/usr/bin/env bash
echo "This runs via chroot in the system being built."
Rugix Bakery will set up a semi-isolated environment (similar to a container) that mimics the system being built. It will then run the script inside that environment as the root user. The same considerations as for run steps apply analogously.
You can use install steps to customize a system in the same way you normally would when you set up a system and perform customizations manually via a local shell. For instance, you can install packages or enable certain system services. Note that services will not run when executing a run step, you can, however, start them as part of the step.
Note that the architecture reported by uname -m during an install step may not match the actual CPU and architecture of the device the system is intended for.
For instance, when building an armhf system based on Rasbperry Pi OS, the architecture reported by uname -m during the build process is armv7l, however, when running the system later on a non-ARMv7 board (e.g., Pi Zero or Pi 1), then the architecture will be armv6l.
We recommend always using the Rugix architecture instead of uname -m.
Environment Variables
Rugix Bakery will expose the following environment variables when running steps:
RUGPI_ARCH: Architecture of the build (arm64orarmhf).RUGPI_ROOT_DIR: Directory of the root filesystem.RUGPI_PROJECT_DIR: Directory of the Rugpi Bakery project.RUGPI_BUNDLE_DIR: Directory of the layer being built.RUGIX_CACHE_DIR: Directory for global caching.RECIPE_DIR: Directory of the recipe which is applied.RECIPE_STEP_PATH: Path of the step being executed.
In addition, the recipe parameters are exposed as explained above.
Configuration Reference
For reference, here is the complete schema for recipe configuration files:
You will find the most recent version of this schema on GitHub.