[v2] 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>
Cc: Antonin Godard <antonin.godard@bootlin.com>
---
changes in v2:
- apply suggested changes
---
 documentation/ref-manual/variables.rst | 50 ++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

Hi Pierre-Loup,

Thanks for the patch!

On 10/16/25 10:34 AM, Pierre-loup GOSSE via lists.yoctoproject.org wrote:
> [You don't often get email from pierre-loup.gosse=smile.fr@lists.yoctoproject.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> 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>
> Cc: Antonin Godard <antonin.godard@bootlin.com>
> ---
> changes in v2:
> - apply suggested changes
> ---
>   documentation/ref-manual/variables.rst | 50 ++++++++++++++++++++++++++
>   1 file changed, 50 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 591c03028..72791f8f3 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3956,6 +3956,56 @@ 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,

I don't believe we've ever explained what the extra_partition plugin 
does so it's a bit difficult to follow what to do here. How do I know if 
this applies to my setup? In which scenario should I use this source plugin?

First, I believe (reading 
scripts/lib/wic/plugins/source/extra_partition.py) we should say "extra 
partition(s)" in the above as there can be multiple ones (which is also 
implied with the later examples).

Then we should probably explain what this plugin is for (but probably 
better in documentation/dev-manual/wic.rst?) and how I know whether it's 
used (--source extra_partition in the wks file).

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

s/a/an/

> +      example::
> +
> +         IMAGE_EXTRA_PARTITION_FILES = "foo bar.conf;bar"
> +
> +      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

The million dollar questions:

1. does the glob pattern include "hidden files" (file/directory starting 
with dot ("."))?
2. does the glob pattern include recursively (if there is a directory in 
that foo/ directory, does it get included and its files as well?)?

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

It's not that it must have the same name (implying the user has to do 
something) is that it simply will as there's no way to change it. So, 
s/must/will/ in the sentence above. BUT, you can specify that the 
directory before the glob pattern can be renamed (and you provide the 
example below already, so that's neat).

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

s/example/line in this example/

> +      installs all files from ``${DEPLOY_DIR_IMAGE}/foo``

We are inconsistent here, all other examples do not specify foo/ 
directory is from DEPLOY_DIR_IMAGE (it is made explicit in the first few 
lines of this glossary entry so I think that ought to be enough?).

> +      into the root of the target partition. The second example installs

s/example/line in this example/

> +      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 partname if multiple

Should "partname" be "part-name" here maybe? To match the prefix used in 
the IMAGE_EXTRA_PARTITION_FILES_ below? Or rather say "partition name"?

> +      extra partitions coexist. Here are some examples::
> +
> +         IMAGE_EXTRA_PARTITION_FILES_label-config = "foo/*"
> +         IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d = "foo/*;bar/"
> +         IMAGE_EXTRA_PARTITION_FILES_part-name-foo = "foo"
> +
> +      Here are the simplified corresponding entries in the WKS file::> +
> +         part --source extra_partition --fstype=ext4 --label config
> +         part --source extra_partition --fstype=ext4 --uuid e7d0824e-cda3-4bed-9f54-9ef5312d105d
> +         part --source extra_partition --fstype=ext4 --part-name foo
> +

On first read, I thought the WKS file was another way to represent the 
example provided just above (the one with the variables), but it isn't 
at all, that's just the companion WKS setup so that the variables make 
sense :)

It'd be nice also to specify what would then happen, just to be on the 
safe side.

I can suggest the following rewording (replace starting from "Here are 
some examples::" above):

"""
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 config
    part --source extra_partition --fstype=ext4 --uuid 
e7d0824e-cda3-4bed-9f54-9ef5312d105d
    part --source extra_partition --fstype=ext4 --part-name foo

and the following part of the image recipe::

    IMAGE_EXTRA_PARTITION_FILES_label-config = "foo/*"
  
IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d = 
"foo/*;bar/"
    IMAGE_EXTRA_PARTITION_FILES_part-name-foo = "foo"

Then:

-  The partition labeled config would get [...].
-  The partition whose UUID is e7d0824e-cda3-4bed-9f54-9ef5312d105d 
would get [...]
-  The partition named foo would get [...]
"""

Cheers,
Quentin

Hi Quentin,

Thank you for your review.

I don't believe we've ever explained what the extra_partition plugin
> does so it's a bit difficult to follow what to do here. How do I know if
> this applies to my setup? In which scenario should I use this source
> plugin?


The extra_partition plugin is inspired by the bootimg_partition plugin. Its
purpose is to install files from the deploy directory onto partition other
than the boot partition. For consistency, I kept the same structure as the
IMAGE_BOOT_FILES variable, which only describes the variable itself.

Then we should probably explain what this plugin is for (but probably
> better in documentation/dev-manual/wic.rst?) and how I know whether it's
> used (--source extra_partition in the wks file).
>

I agree. I think the dev-manual/wic.rst is missing of a dedicated section
explaining the plugins.

1. does the glob pattern include "hidden files" (file/directory starting
> with dot ("."))?
> 2. does the glob pattern include recursively (if there is a directory in
> that foo/ directory, does it get included and its files as well?)?


Hidden files are not included, and the glob pattern is not recursive. I
will clarify these points.

I will submit a new version with your suggested changes.

Pierre-Loup,

On Mon, Oct 20, 2025 at 6:34 PM Quentin Schulz <quentin.schulz@cherry.de>
wrote:

> Hi Pierre-Loup,
>
> Thanks for the patch!
>
> On 10/16/25 10:34 AM, Pierre-loup GOSSE via lists.yoctoproject.org wrote:
> > [You don't often get email from pierre-loup.gosse=
> smile.fr@lists.yoctoproject.org. Learn why this is important at
> https://aka.ms/LearnAboutSenderIdentification ]
> >
> > 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>
> > Cc: Antonin Godard <antonin.godard@bootlin.com>
> > ---
> > changes in v2:
> > - apply suggested changes
> > ---
> >   documentation/ref-manual/variables.rst | 50 ++++++++++++++++++++++++++
> >   1 file changed, 50 insertions(+)
> >
> > diff --git a/documentation/ref-manual/variables.rst
> b/documentation/ref-manual/variables.rst
> > index 591c03028..72791f8f3 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -3956,6 +3956,56 @@ 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,
>
> I don't believe we've ever explained what the extra_partition plugin
> does so it's a bit difficult to follow what to do here. How do I know if
> this applies to my setup? In which scenario should I use this source
> plugin?
>
> First, I believe (reading
> scripts/lib/wic/plugins/source/extra_partition.py) we should say "extra
> partition(s)" in the above as there can be multiple ones (which is also
> implied with the later examples).
>
> Then we should probably explain what this plugin is for (but probably
> better in documentation/dev-manual/wic.rst?) and how I know whether it's
> used (--source extra_partition in the wks file).
>
> > +      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
>
> s/a/an/
>
> > +      example::
> > +
> > +         IMAGE_EXTRA_PARTITION_FILES = "foo bar.conf;bar"
> > +
> > +      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
>
> The million dollar questions:
>
> 1. does the glob pattern include "hidden files" (file/directory starting
> with dot ("."))?
> 2. does the glob pattern include recursively (if there is a directory in
> that foo/ directory, does it get included and its files as well?)?
>
> > +      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
>
> It's not that it must have the same name (implying the user has to do
> something) is that it simply will as there's no way to change it. So,
> s/must/will/ in the sentence above. BUT, you can specify that the
> directory before the glob pattern can be renamed (and you provide the
> example below already, so that's neat).
>
> > +      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
>
> s/example/line in this example/
>
> > +      installs all files from ``${DEPLOY_DIR_IMAGE}/foo``
>
> We are inconsistent here, all other examples do not specify foo/
> directory is from DEPLOY_DIR_IMAGE (it is made explicit in the first few
> lines of this glossary entry so I think that ought to be enough?).
>
> > +      into the root of the target partition. The second example installs
>
> s/example/line in this example/
>
> > +      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 partname if
> multiple
>
> Should "partname" be "part-name" here maybe? To match the prefix used in
> the IMAGE_EXTRA_PARTITION_FILES_ below? Or rather say "partition name"?
>
> > +      extra partitions coexist. Here are some examples::
> > +
> > +         IMAGE_EXTRA_PARTITION_FILES_label-config = "foo/*"
> > +
>  IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d =
> "foo/*;bar/"
> > +         IMAGE_EXTRA_PARTITION_FILES_part-name-foo = "foo"
> > +
> > +      Here are the simplified corresponding entries in the WKS file::> +
> > +         part --source extra_partition --fstype=ext4 --label config
> > +         part --source extra_partition --fstype=ext4 --uuid
> e7d0824e-cda3-4bed-9f54-9ef5312d105d
> > +         part --source extra_partition --fstype=ext4 --part-name foo
> > +
>
> On first read, I thought the WKS file was another way to represent the
> example provided just above (the one with the variables), but it isn't
> at all, that's just the companion WKS setup so that the variables make
> sense :)
>
> It'd be nice also to specify what would then happen, just to be on the
> safe side.
>
> I can suggest the following rewording (replace starting from "Here are
> some examples::" above):
>
> """
> 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 config
>     part --source extra_partition --fstype=ext4 --uuid
> e7d0824e-cda3-4bed-9f54-9ef5312d105d
>     part --source extra_partition --fstype=ext4 --part-name foo
>
> and the following part of the image recipe::
>
>     IMAGE_EXTRA_PARTITION_FILES_label-config = "foo/*"
>
> IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d =
> "foo/*;bar/"
>     IMAGE_EXTRA_PARTITION_FILES_part-name-foo = "foo"
>
> Then:
>
> -  The partition labeled config would get [...].
> -  The partition whose UUID is e7d0824e-cda3-4bed-9f54-9ef5312d105d
> would get [...]
> -  The partition named foo would get [...]
> """
>
> Cheers,
> Quentin
>