[v3] 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").

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v3:
- Apply suggestions from Quentin (thanks!)
- Link to v2: https://patch.msgid.link/20251216-image-container-v2-1-630e5f91c0d9@bootlin.com

Changes in v2:
- Review from Quentin (thanks!)
  - Merge patch 1 and 2.
  - Rephrase class and variable to highlight that IMAGE_FSTYPES should
    contain container, and that the class should not be inherited
    directly.
- Link to v1: https://patch.msgid.link/20251212-image-container-v1-0-fb6586d06813@bootlin.com
---
 documentation/ref-manual/classes.rst   | 46 ++++++++++++++++++++++++++++++++++
 documentation/ref-manual/variables.rst | 18 +++++++++++++
 2 files changed, 64 insertions(+)


---
base-commit: d84d916d4fc505e8386693306b6a90b0064c0518
change-id: 20251023-image-container-fdc6d79f6729

Hi Antonin,

Minor typos and one comments below, feel free to fix while applying.

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!

On 12/17/25 10:16 AM, Antonin Godard via lists.yoctoproject.org wrote:
> 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").
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
> Changes in v3:
> - Apply suggestions from Quentin (thanks!)
> - Link to v2: https://patch.msgid.link/20251216-image-container-v2-1-630e5f91c0d9@bootlin.com
> 
> Changes in v2:
> - Review from Quentin (thanks!)
>    - Merge patch 1 and 2.
>    - Rephrase class and variable to highlight that IMAGE_FSTYPES should
>      contain container, and that the class should not be inherited
>      directly.
> - Link to v1: https://patch.msgid.link/20251212-image-container-v1-0-fb6586d06813@bootlin.com
> ---
>   documentation/ref-manual/classes.rst   | 46 ++++++++++++++++++++++++++++++++++
>   documentation/ref-manual/variables.rst | 18 +++++++++++++
>   2 files changed, 64 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index a56a2f719..a46a5527f 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -1258,6 +1258,52 @@ 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.
>   

Unrelated to this patch, I'm wondering if image_types is at the right 
location in order for the classes to be alphabetically sorted.

It is currently between image-buildinfo and image-live.

> +.. _ref-classes-image-container:
> +
> +``image-container``
> +===================
> +
> +The :ref:`ref-classes-image-container` class is automatically inherited in
> +:doc:`image </ref-manual/images>` 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 <Open_Container_Initiative>`-compliant
> +container management tool, such as :wikipedia:`Podman <Podman>` or
> +:wikipedia:`Docker <Docker_(software)>`.
> +
> +.. note::
> +
> +   This class neither builds nor installs container management tools on the
> +   target. Those tools are available in the :yocto_git:`meta-virtualization
> +   </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 skip this check.
> +

Here it's the first time we say "check", before we say an error is 
triggered. This refers to the check that triggers to the error but it 
may not be clear for the user reading this for the first time. I guess 
we could say "to avoid triggering an error"?

> +The ``linux-dummy`` recipes acts as a Linux kernel recipe but builds nothing. It

s/recipes/recipe/

> +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 <Podman>` or :wikipedia:`Docker <Docker_(software)>`, the
> +`container file <https://docs.docker.com/reference/dockerfile/>`__ 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 71fe11b83..7c03dc138 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3955,6 +3955,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

s/The/the/