[v3,1/2] ref-manual/variables.rst: document IMAGE_EXTRA_PARTITION_FILES

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>
---
changes in v2:
- apply suggested changes

changes in v3:
- rename example filenames for clarity
- specify that hidden files are ignored and that the glob pattern is non-recursive
- change 'partname' with 'partition name'
- expand the last example
---
 documentation/ref-manual/variables.rst | 61 ++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

Hi Pierre-loup,

Only nitpicks below, check with Antonin if there's a need to send 
another version just for that.

On 10/24/25 10:44 AM, 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>
> ---
> changes in v2:
> - apply suggested changes
> 
> changes in v3:
> - rename example filenames for clarity
> - specify that hidden files are ignored and that the glob pattern is non-recursive
> - change 'partname' with 'partition name'
> - expand the last example
> ---
>   documentation/ref-manual/variables.rst | 61 ++++++++++++++++++++++++++
>   1 file changed, 61 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 591c03028..a608a61f2 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3956,6 +3956,67 @@ 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(s)
> +      when preparing an image using the Wic tool with the
> +      ``extra_partition`` source plugin. By default,
> +      the files are

Odd line wrapping?

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

Maybe we should use
(``;``)
here.

> +      :term:`DEPLOY_DIR_IMAGE`. Here is an

Unnecessary newline here I believe as well?

> +      example::
> +
> +         IMAGE_EXTRA_PARTITION_FILES = "foobar file.conf;config"
> +
> +      In the above example, the file ``foobar`` is installed with its original name
> +      ``foobar``, while the file ``file.conf`` is installed and renamed to ``config``.
> +
> +      Alternatively, source files can be picked up using a glob pattern.
> +      However, hidden files are ignored, and the pattern is non-recursive
> +      (subdirectories are ignored).
> +      The destination file will have the same name as the base
> +      name of the source file path. To install files into a renamed directory
> +      within the target location, pass its name after a semi-colon (;).

Same remark as above.

> +      Here are two examples::
> +
> +         IMAGE_EXTRA_PARTITION_FILES = "foo/*"
> +         IMAGE_EXTRA_PARTITION_FILES = "foo/*;bar/"
> +
> +      The first line in this example> +      installs all files from ``foo`` directory

Odd line wrapping?

> +      into the root of the target partition. The second line in this example installs
> +      the same files into a ``bar`` directory within the target partition.
> +      The ``bar/`` directory is automatically created if it does not exist.
> +
> +      You can also specify the target by label, UUID or partition name if multiple
> +      extra partitions coexist. Let's take the following example. This would be
> +      the WKS file for the image currently being built::
> +
> +         part --source extra_partition --fstype=ext4 --label foo
> +         part --source extra_partition --fstype=ext4 --uuid e7d0824e-cda3-4bed-9f54-9ef5312d105d
> +         part --source extra_partition --fstype=ext4 --part-name config
> +
> +      And the following configuration::
> +
> +         IMAGE_EXTRA_PARTITION_FILES_label-foo = "foo/*"
> +         IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d = "foo/*;bar/"
> +         IMAGE_EXTRA_PARTITION_FILES_part-name-config = "config"
> +
> +      Then:
> +
> +      - The partition labeled foo would get all files from the ``foo`` directory.
> +

Replace the first foo with ``foo``

> +      - The partition whose UUID is e7d0824e-cda3-4bed-9f54-9ef5312d105d would get all files from the ``foo`` directory, installed into a ``bar`` directory.

Tick quote the UUID

> +
> +      - The partition named config would get the file ``config``.
> +

Tick quote the partition name config

Looking good otherwise, thus

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

Thanks!
Quentin