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

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

Hi,

On Fri Dec 12, 2025 at 1:07 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 12/12/25 11:22 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.
>> 
>
> Wrong order of patches, patch 1 uses the reflink created in this patch.
>
> EDIT: and this patch depends on patch 1 as well, so just merge both of 
> them into one patch, they are related anyway.

Yeah, I thought I was being smart by making sure the order was right, turns out
they should be merged together!

>> This answers in part to questions asked in [YOCTO #14368].
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/ref-manual/classes.rst | 51 ++++++++++++++++++++++++++++++++++++
>>   1 file changed, 51 insertions(+)
>> 
>> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
>> index a56a2f719..0097b7c46 100644
>> --- a/documentation/ref-manual/classes.rst
>> +++ b/documentation/ref-manual/classes.rst
>> @@ -1258,6 +1258,57 @@ 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 meant to be inherited in
>> +:doc:`image </ref-manual/images>` recipes. It provides relevant settings to
>> +generate an image ready for use with an :wikipedia:`OCI
>> +<Open_Container_Initiative>`-compliant container management tool.
>
> such as....? podman and docker I assume, probably others.
>
>> +
>> +.. note::
>> +
>> +   This class does not build and install container management tools on the
>
> s/does not build and install/neither builds nor installs/
>
>> +   target. Support for this is available in the :yocto_git:`meta-virtualization
>
> s/Support for this is/Those tools are/?
>
>> +   </meta-virtualization>` layer.
>> +
>> +An image recipe inheriting this class should also add the ``container`` image
>> +type to the :term:`IMAGE_FSTYPES` variable::
>> +
>> +   IMAGE_FSTYPES += "container"
>> +
>
> Isn't that done by image.bbclass already anyway? This class is 
> automatically inherited when IMAGE_FSTYPES contains "container".
>
> c.f. 
> https://git.openembedded.org/openembedded-core/tree/meta/classes-recipe/image.bbclass#n20 
> and 
> https://git.openembedded.org/openembedded-core/tree/meta/classes-recipe/image.bbclass#n25 
> ?
>
>> +This image type does not deploy anything specific in :term:`DEPLOY_DIR_IMAGE`,
>> +but will simply add ``tar.bz2`` to the image types.
>> +
>> +You must also set the :term:`PREFERRED_PROVIDER` for the Linux kernel to
>
> No. You *can* (and you typically want).
>
>> +``linux-dummy`` in a :term:`configuration file`::
>> +
>> +   PREFERRED_PROVIDER_virtual/kernel = "linux-dummy"
>> +> +The ``linux-dummy`` recipes acts as a Linux kernel recipe but builds 
> nothing. It
>> +is relevant 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.
>> +
>> +If desired, the :term:`IMAGE_CONTAINER_NO_DUMMY` variable can be set to "1" to
>> +skip the ``PREFERRED_PROVIDER_virtual/kernel`` check.
>> +
>
> Ah scratch that review on patch 1, linux-dummy isn't the default.

I haven't seen your review on patch 1 (locally or on lore.kernel.org), did you
forget to send it?

>> +After the image is built, the generated ``tar.bz2`` archive can be used in a
>> +container generation file. For example, to be used with :wikipedia:`Podman
>
> Being curious, where did you see "container generation file" being used? 

Nowhere else, I made that up I guess. I'll reword this and mention
Containerfile/Dockerfile.

> First time I see Containerfile/Dockerfile named this way. You could keep 
> it but maybe specify that it's typically named Containerfile or 
> Dockerfile so people know what we're talking about?

Thanks!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com