Skip to main content
Version: Next

Layers

Layers are defined by layer configuration files <layer name>.toml in the layers directory. As described in the introduction, a layer is built by executing recipes. For a given layer, the respective layer configuration file specifies the recipes to be executed as well as an optional parent layer that should be used as a base. Here is an example taken from the Debian template:

layers/customized.toml
#:schema https://raw.githubusercontent.com/silitics/rugix/refs/tags/v0.8.0/schemas/rugix-bakery-layer.schema.json

parent = "core/debian-bookworm"

recipes = [
    # Setup Debian for booting via Grub.
    "core/debian-grub-setup",
    # Set a static hostname.
    "core/set-hostname",
    # Persist `/root`.
    "core/persist-root-home",
    # Setup and enable SSH.
    "core/ssh",
    # Enable discovery of the system in the local network.
    "rugix-extra/avahi",
    # Setup the network.
    "setup-network",
    # Install a static website.
    "hello-world",
]

This file defines a layer, named customized, that is based on the layer core/debian-bookworm, a general-purpose layer to build Debian-based systems shipped with Rugix Bakery. The configuration file then specifies a bunch of recipes to set up and customize the system, for instance, setting up a bootloader integration with Grub and providing a network configuration.

In addition to project-specific layers and recipes defined in the project directory, you can use layers and recipes provided by repositories. In case of the example, these repositories are core and rugix-extra. We will explain repositories in detail later. The core repository is shipped with Rugix Bakery and includes the following layers for you to use as a parent layer:

  • core/debian-bookworm for Debian Bookworm,
  • core/alpine-3-20 for Alpine Linux 3.20,
  • core/raspios-bookworm for Raspberry Pi OS (Bookworm), and
  • core/raspios-bullseye for Raspberry Pi OS (Bullseye).

Root Layers​

If you do not want to use a parent layer, you can also start from scratch by omitting the parent setting and specifying root = true. For example, here is a layer configuration that bootstraps Debian using the core/debian-bootstrap recipe:

reproducible-debian.toml
#:schema https://raw.githubusercontent.com/silitics/rugix/refs/tags/v0.8.0/schemas/rugix-bakery-layer.schema.json

root = true

recipes = [
    "core/debian-bootstrap",
]

[parameters."core/debian-bootstrap"]
suite = "bookworm"
snapshot = "20240501T024440Z"

By setting the snapshot parameter of the core/debian-bootstrap recipe (more on parameters later), the resulting layer will be based on a particular Debian snapshot, thereby leading to a semi-reproducible1 build.

Importing Layers​

Rugix Bakery can import layers from external sources. To this end, you can specify a URL.

Here is an example for importing a layer from a Raspberry Pi OS (Bookworm) image:

raspios-bookworm.toml
#:schema https://raw.githubusercontent.com/silitics/rugix/refs/tags/v0.8.0/schemas/rugix-bakery-layer.schema.json

name = "Raspberry Pi OS (Bookworm)"
url = "https://downloads.raspberrypi.com/raspios_lite_arm64/images/raspios_lite_arm64-2024-03-15/2024-03-15-raspios-bookworm-arm64-lite.img.xz"

Rugix Bakery can download images and TAR archives from HTTP URLs and create layers from them. This is useful if one wants to take an existing system image as a basis, e.g., when building a customized variant of Raspberry Pi OS. In addition to HTTP URLs, file URLs starting with file:// are also supported. These URLs are resolved relative to the project directory.

tip

You can use this to import a root filesystem built with an external tool, e.g., Buildroot or Yocto.

Note that imported layers must not specify any recipes. Customizations are applied by using them as a parent.

Excluding recipes​

Recipes may depend on other recipes and as such will pull in their dependencies automatically when specified in the recipes list of a layer. To avoid that, e.g., when you want to replace some recipe with a local variant, you can exclude certain recipes from a layer. To this end, you can provide a list of recipes to exclude via the exclude property.

Configuration Reference​

For reference, here is the complete schema for layer configuration files:

Loading ....

You will find the most recent version of this schema on GitHub.

Footnotes​

  1. The layer should be fully reproducible, however, Rugix Bakery does currently not support building images reproducibly. We will add this functionality in the future such that images can be reproduced bit-by-bit. ↩