[PATCH] ref-manual/variables.rst: document IMAGE_EXTRA_PARTITION_FILES

[PATCH] ref-manual/variables.rst: document IMAGE_EXTRA_PARTITION_FILES

[pierre-loup.gosse]

From: Pierre-Loup GOSSE <pierre-loup.gosse@smile.fr>

Added by commit 3892912bd7e0 ("wic: extra partition plugin") in OE-Core.

Signed-off-by: Pierre-Loup GOSSE <pierre-loup.gosse@smile.fr>
---
 documentation/ref-manual/variables.rst | 39 ++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 591c03028..cdcc8b877 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3956,6 +3956,45 @@ system and gives an overview of their function and contents.
       material for Wic is located in the
       ":doc:`/ref-manual/kickstart`" chapter.
 
+   :term:`IMAGE_EXTRA_PARTITION_FILES`
+      A space-separated list of files installed into the extra partition
+      when preparing an image using the Wic tool with the
+      ``extra_partition`` source plugin. By default,
+      the files are
+      installed under the same name as the source files. To change the
+      installed name, separate it from the original name with a semi-colon
+      (;). Source files need to be located in
+      :term:`DEPLOY_DIR_IMAGE`. Here is a
+      example::
+
+         IMAGE_EXTRA_PARTITION_FILES = "foo bar.conf;bar"
+
+      Alternatively, source files can be picked up using a glob pattern. In
+      this case, the destination file must have the same name as the base
+      name of the source file path. To install files into a directory
+      within the target location, pass its name after a semi-colon (;).
+      Here are two examples::
+
+         IMAGE_EXTRA_PARTITION_FILES = "foo/*"
+         IMAGE_EXTRA_PARTITION_FILES = "foo/*;bar/"
+
+      The first example
+      installs all files from ``${DEPLOY_DIR_IMAGE}/foo``
+      into the root of the target partition. The second example installs
+      the same files into a ``bar`` directory within the target partition.
+
+      You can also specify the target by label, UUID or partname if multiple
+      extra partitions coexist. Here are two examples::
+
+         IMAGE_EXTRA_PARTITION_FILES_label-config = "foo/*"
+         IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d = "foo/*;bar/"
+
+      You can find information on how to use the Wic tool in the
+      ":ref:`dev-manual/wic:creating partitioned images using wic`"
+      section of the Yocto Project Development Tasks Manual. Reference
+      material for Wic is located in the
+      ":doc:`/ref-manual/kickstart`" chapter.
+
    :term:`IMAGE_FEATURES`
       The primary list of features to include in an image. Typically, you
       configure this variable in an image recipe. Although you can use this
-- 
2.34.1

Re: [docs] [PATCH] ref-manual/variables.rst: document IMAGE_EXTRA_PARTITION_FILES

[Antonin Godard]

Hi,

On Tue Oct 14, 2025 at 2:30 PM CEST, Pierre-loup GOSSE via lists.yoctoproject.org wrote:
> From: Pierre-Loup GOSSE <pierre-loup.gosse@smile.fr>
>
> Added by commit 3892912bd7e0 ("wic: extra partition plugin") in OE-Core.
>
> Signed-off-by: Pierre-Loup GOSSE <pierre-loup.gosse@smile.fr>
> ---
>  documentation/ref-manual/variables.rst | 39 ++++++++++++++++++++++++++
>  1 file changed, 39 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 591c03028..cdcc8b877 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3956,6 +3956,45 @@ system and gives an overview of their function and contents.
>        material for Wic is located in the
>        ":doc:`/ref-manual/kickstart`" chapter.
>  
> +   :term:`IMAGE_EXTRA_PARTITION_FILES`
> +      A space-separated list of files installed into the extra partition
> +      when preparing an image using the Wic tool with the
> +      ``extra_partition`` source plugin. By default,
> +      the files are
> +      installed under the same name as the source files. To change the
> +      installed name, separate it from the original name with a semi-colon
> +      (;). Source files need to be located in
> +      :term:`DEPLOY_DIR_IMAGE`. Here is a
> +      example::
> +
> +         IMAGE_EXTRA_PARTITION_FILES = "foo bar.conf;bar"

Here I think you can close this explanation with:

"""
In the above example, the file ``foo`` is installed with its original name
``foo``, while the file ``bar.conf`` is installed and renamed to ``bar``.
"""

> +
> +      Alternatively, source files can be picked up using a glob pattern. In
> +      this case, the destination file must have the same name as the base
> +      name of the source file path. To install files into a directory
> +      within the target location, pass its name after a semi-colon (;).
> +      Here are two examples::
> +
> +         IMAGE_EXTRA_PARTITION_FILES = "foo/*"
> +         IMAGE_EXTRA_PARTITION_FILES = "foo/*;bar/"
> +
> +      The first example
> +      installs all files from ``${DEPLOY_DIR_IMAGE}/foo``
> +      into the root of the target partition. The second example installs
> +      the same files into a ``bar`` directory within the target partition.

Add:

"""
The ``bar/`` directory is automatically created if it does not exist.
"""

?

> +
> +      You can also specify the target by label, UUID or partname if multiple
> +      extra partitions coexist. Here are two examples::
> +
> +         IMAGE_EXTRA_PARTITION_FILES_label-config = "foo/*"
> +         IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d = "foo/*;bar/"

I think it would be nice to also show an example for partname.

And for each of these, the corresponding entries in the WKS file could be
listed, with each corresponding parameter. Maybe truncated to highlight the
matching WIC option.

> +
> +      You can find information on how to use the Wic tool in the
> +      ":ref:`dev-manual/wic:creating partitioned images using wic`"
> +      section of the Yocto Project Development Tasks Manual. Reference
> +      material for Wic is located in the
> +      ":doc:`/ref-manual/kickstart`" chapter.
> +
>     :term:`IMAGE_FEATURES`
>        The primary list of features to include in an image. Typically, you
>        configure this variable in an image recipe. Although you can use this

Thanks!
Antonin

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