[v2] 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 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   | 48 ++++++++++++++++++++++++++++++++++
 documentation/ref-manual/variables.rst | 17 ++++++++++++
 2 files changed, 65 insertions(+)


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

Hi Antonin,

Only blocker to me is the last comment, otherwise looks good to me.

On 12/16/25 2:59 PM, 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 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   | 48 ++++++++++++++++++++++++++++++++++
>   documentation/ref-manual/variables.rst | 17 ++++++++++++
>   2 files changed, 65 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index a56a2f719..6781c5294 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -1258,6 +1258,54 @@ 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 </ref-manual/images>` recipes that set the ``container`` image type

s/set the/have/ ?

> +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 this variable equals to another value. If

s/ if this variable equals to another value//

that is implied by the use of "otherwise"?

> +desired, the :term:`IMAGE_CONTAINER_NO_DUMMY` variable can be set to "1" to
> +skip this check.
> +
> +The ``linux-dummy`` recipes 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 does not deploy anything specific in :term:`DEPLOY_DIR_IMAGE`,
> +except for an additional ``tar.bz2`` archive. This archive can be used

Simplify by saying "only deploys to :term:`DEPLOY_DIR_IMAGE` an 
additional ``tar.bz2`` archive"?

> +in a container file (a file typically named "Dockerfile" or "Containerfile").

s/"/``/ ?

> +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

I do always go to the docker documentation when writing Containerfiles 
but I now wondered if there was one for Containerfile that isn't 
hosted/written by Docker. Seems like the podman docs hints at 
https://github.com/containers/container-libs/blob/main/common/docs/Containerfile.5.md. 
No action to be taken, just wanted to raise this.

> +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..63fb7fa79 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3955,6 +3955,23 @@ 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.
> +
> +      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.
> +
> +      This variable should be set from the image recipe using the ``container``
> +      image type.
> +

Please specify what the value should (not) be (not 1).

This is the only blocker. Other comments are suggestions, up to you.

Cheers,
Quentin