[PATCH v2] ref-manual/classes.rst: document the image-container class

[Antonin Godard <antonin.godard@bootlin.com>]

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

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