From 71615e330caa7d60920874eaf6bde4ffe37dd6a9 Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Wed, 17 Dec 2025 10:16:30 +0100 Subject: [PATCH] ref-manual/classes.rst: document the image-container class Add documentation for the image-container class, which is a simple class to generate an image suitable for creating a container. This answers in part to questions asked in [YOCTO #14368]. It also adds documentation for IMAGE_CONTAINER_NO_DUMMY, which was added in OE-Core with commit f0645e172bb8 ("image-container.bbclass: Error if not using linux-dummy"). Reviewed-by: Quentin Schulz (From yocto-docs rev: 85fb6e4a964ea2dea9c3083ba2c4ceb336f34b1a) Signed-off-by: Antonin Godard (cherry picked from commit 6ce00e5875eb3469fefd55cc22acaaeaf620053a) Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/ref-manual/classes.rst | 47 ++++++++++++++++++++++++++ documentation/ref-manual/variables.rst | 18 ++++++++++ 2 files changed, 65 insertions(+) diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index bc7ccb8b71..a6cf586dd5 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -1248,6 +1248,53 @@ The :ref:`ref-classes-image_types` class also handles conversion and compression :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. +.. _ref-classes-image-container: + +``image-container`` +=================== + +The :ref:`ref-classes-image-container` class is automatically inherited in +:doc:`image ` recipes that have the ``container`` image type +in :term:`IMAGE_FSTYPES`. It provides relevant settings to generate an image +ready for use with an :wikipedia:`OCI `-compliant +container management tool, such as :wikipedia:`Podman ` or +:wikipedia:`Docker `. + +.. note:: + + This class neither builds nor installs container management tools on the + target. Those tools are available in the :yocto_git:`meta-virtualization + ` layer. + +You should set the :term:`PREFERRED_PROVIDER` for the Linux kernel to +``linux-dummy`` in a :term:`configuration file`:: + + PREFERRED_PROVIDER_virtual/kernel = "linux-dummy" + +Otherwise an error is triggered. If desired, the +:term:`IMAGE_CONTAINER_NO_DUMMY` variable can be set to "1" to avoid triggering +this error. + +The ``linux-dummy`` recipe acts as a Linux kernel recipe but builds nothing. It +is relevant to use as the preferred Linux kernel provider in this case as a +container image does not need to include a Linux kernel. Selecting it as the +preferred provider for the kernel will also decrease build time. + +Using this class only deploys an additional ``tar.bz2`` archive to +:term:`DEPLOY_DIR_IMAGE`. This archive can be used in a container file (a file +typically named ``Dockerfile`` or ``Containerfile``). For example, to be used with +:wikipedia:`Podman ` or :wikipedia:`Docker `, the +`container file `__ could contain +the following instructions: + +.. code-block:: dockerfile + + FROM scratch + ADD ./image-container-qemux86-64.rootfs.tar.bz2 / + ENTRYPOINT /bin/sh + +This is suitable to build a container using our generated root filesystem image. + .. _ref-classes-image-live: ``image-live`` diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 5b4561fc12..a67090308b 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -3837,6 +3837,24 @@ system and gives an overview of their function and contents. variable, see the :ref:`ref-classes-image_types` class file, which is ``meta/classes-recipe/image_types.bbclass``. + :term:`IMAGE_CONTAINER_NO_DUMMY` + When an image recipe has the ``container`` image type in + :term:`IMAGE_FSTYPES`, it expects the :term:`PREFERRED_PROVIDER` for + the Linux kernel (``virtual/kernel``) to be set to ``linux-dummy`` from a + :term:`configuration file`. Otherwise, an error is triggered. + + When set to "1", the :term:`IMAGE_CONTAINER_NO_DUMMY` variable allows the + :term:`PREFERRED_PROVIDER` variable to be set to another value, thus + skipping the check and not triggering the build error. Any other value + will keep the check. + + This variable should be set from the image recipe using the ``container`` + image type. + + See the documentation of the :ref:`ref-classes-image-container` class for + more information on why setting the :term:`PREFERRED_PROVIDER` to + ``linux-dummy`` is advised with this class. + :term:`IMAGE_DEVICE_TABLES` Specifies one or more files that contain custom device tables that are passed to the ``makedevs`` command as part of creating an image.