From 27e41b91d68d4adb6cd967871c59fd1e32830fe6 Mon Sep 17 00:00:00 2001 From: Bruce Ashfield Date: Fri, 12 Jun 2026 17:13:19 +0000 Subject: docs/container-bundling: refresh multi-layer mode section Three related updates to the multi-layer documentation, all driven by patterns that came up reviewing recent OCI image recipes: - Drop the "IMAGE_INSTALL must include all packages to trigger builds" guidance from the example. As of the matching bbclass change, image-oci.bbclass folds OCI_LAYERS packages: entries into IMAGE_INSTALL automatically, so recipes only set the package list once. The example used to demonstrate the dual-source-of-truth workaround for the original limitation; with the limitation gone the example was actively misleading. - Add a "Conditional Packages per Layer" subsection documenting the bb.utils.contains() pattern for adding/omitting packages from a packages: layer based on PACKAGECONFIG (or any other variable), without duplicating the whole OCI_LAYERS declaration in two branches. This is a real, useful idiom that recipes have started using; previously undocumented. - Fill in the "host" layer type row in the layer-type table. The type was already supported and explained in image-oci.bbclass inline docs, but the user-facing reference table only listed packages / directories / files. Signed-off-by: Bruce Ashfield --- docs/container-bundling.md | 39 +++++++++++++++++++++++++++++++++++---- 1 file changed, 35 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/container-bundling.md b/docs/container-bundling.md index f4587a99..0a0209ec 100644 --- a/docs/container-bundling.md +++ b/docs/container-bundling.md @@ -155,11 +155,15 @@ Create explicit layers with fine-grained control: app:packages:curl \ " - # IMAGE_INSTALL must include all packages to trigger builds - IMAGE_INSTALL = "base-files base-passwd netbase busybox curl" - Result: 3 layers (base, shell, app) +Packages named in any `packages:` layer are automatically folded into +`IMAGE_INSTALL`, so do_rootfs's recrdeptask builds them. You do not +need to repeat the package list in `IMAGE_INSTALL`. If a recipe needs +additional packages that aren't part of any final layer (e.g. for a +rootfs-only postprocess fixup), it can still add to `IMAGE_INSTALL` +itself — the auto-derivation is additive. + #### Layer Definition Format name:type:content @@ -169,6 +173,7 @@ Result: 3 layers (base, shell, app) | `packages` | `pkg1+pkg2+pkg3` | Install packages (use + delimiter) | | `directories` | `/path1+/path2` | Copy directories from IMAGE_ROOTFS | | `files` | `/file1+/file2` | Copy specific files from IMAGE_ROOTFS | +| `host` | `src:dst+src:dst` | Copy from build machine (sparingly — see below) | #### Example Recipes @@ -180,7 +185,6 @@ OCI_LAYERS = "\ python:packages:python3+python3-pip \ app:directories:/opt/myapp \ " -IMAGE_INSTALL = "base-files base-passwd netbase python3 python3-pip myapp" ``` **Two-layer with base image + multi-layer app:** @@ -193,6 +197,33 @@ OCI_LAYERS = "\ " ``` +#### Conditional Packages per Layer + +Use `${@bb.utils.contains(...)}` directly inside a layer's package list +to add or omit packages based on `PACKAGECONFIG` (or any other +distro/recipe variable) without duplicating the whole `OCI_LAYERS` +declaration in two branches: + +```bitbake +PACKAGECONFIG ??= "" +PACKAGECONFIG[dev] = "" + +OCI_LAYER_MODE = "multi" +OCI_LAYERS = "\ + base:packages:base-files+base-passwd+netbase \ + python:packages:python3+coreutils${@bb.utils.contains('PACKAGECONFIG', 'dev', '+python3-pip', '', d)} \ +" +``` + +The expression expands to `+python3-pip` when `dev` is enabled and to +nothing otherwise. Because the `+` delimiter is folded into the +substituted text, the resulting layer string is well-formed in both +cases (`python3+coreutils` or `python3+coreutils+python3-pip`). + +This composes with the auto-derivation above: `python3-pip` is added to +`IMAGE_INSTALL` only when the `dev` config is active, exactly as if you +had written it out by hand. + ### Layer Caching Multi-layer builds cache pre-installed package layers for faster rebuilds. -- cgit v1.2.3-54-g00ecf