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

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

[Trevor Woerner]

Fixes [YOCTO #15509]

Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
 documentation/ref-manual/variables.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index d17f81036b7d..29f34f5b029d 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -10942,6 +10942,24 @@ system and gives an overview of their function and contents.
       Specifies the timeout in seconds used by the ``watchdog-config`` recipe
       and also by ``systemd`` during reboot. The default is 60 seconds.
 
+   :term:`WIC_CREATE_EXTRA_ARGS`
+      If the :term:`IMAGE_FSTYPES` variable contains "wic", the build
+      will generate a Wic image automatically when BitBake builds an
+      image recipe. As part of this process the Wic bbclass will call the
+      "`wic create`" command. The `WIC_CREATE_EXTRA_ARGS` variable is
+      appended to the internal "`wic create`" command to provide a
+      mechanism for the user to supply extra arguments to the
+      "`wic create`" command that is automatically run by BitBake.
+
+      One such useful purpose for this mechanism is to add the "-D|--debug"
+      argument to the "`wic create`" command. This increases the amount of
+      debugging information written out to the Wic log during the Wic creation
+      process.
+
+      For more information about creating Wic images, see the
+      ":ref:`dev-manual/wic:creating partitioned images using wic`" section in
+      the Yocto Project Development Tasks Manual.
+
    :term:`WIC_SECTOR_SIZE`
       The variable :term:`WIC_SECTOR_SIZE` controls the sector size of Wic
       images. In the background, this controls the value of the
-- 
2.44.0.501.g19981daefd7c

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

[Quentin Schulz]

Hi Trevor,

On 5/6/25 7:23 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> Fixes [YOCTO #15509]
> 
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
>   documentation/ref-manual/variables.rst | 18 ++++++++++++++++++
>   1 file changed, 18 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index d17f81036b7d..29f34f5b029d 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -10942,6 +10942,24 @@ system and gives an overview of their function and contents.
>         Specifies the timeout in seconds used by the ``watchdog-config`` recipe
>         and also by ``systemd`` during reboot. The default is 60 seconds.
>   
> +   :term:`WIC_CREATE_EXTRA_ARGS`
> +      If the :term:`IMAGE_FSTYPES` variable contains "wic", the build
> +      will generate a Wic image automatically when BitBake builds an

Maybe we could point Wic image to 
https://docs.yoctoproject.org/dev-manual/wic.html#creating-partitioned-images-using-wic?

> +      image recipe. As part of this process the Wic bbclass will call the

There's no wic bbclass. I think you meant to say image_types_wic 
bbclass? It would be nice to provide a :ref: there but we actually do 
not have the class explained yet so cannot do a 
:ref:`ref-classes-image_types_wic` like we could for image_types.

> +      "`wic create`" command. The `WIC_CREATE_EXTRA_ARGS` variable is
> +      appended to the internal "`wic create`" command to provide a
> +      mechanism for the user to supply extra arguments to the
> +      "`wic create`" command that is automatically run by BitBake.
> +

A bit too many

the "`wic create`" command

to my taste, can suggest:

To allow the user to supply extra arguments,
the `WIC_CREATE_EXTRA_ARGS` variable is
appended to the internal "`wic create`" command
that is automatically run by BitBake.

What do you think?

> +      One such useful purpose for this mechanism is to add the "-D|--debug"

-D (or --debug)

maybe? I believe this would otherwise break the search or not be crystal 
clear what the option is supposed to be.

Looks good to me otherwise,

Cheers,
Quentin

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

[Trevor Woerner]

On Mon 2025-05-12 @ 09:31:27 AM, Quentin Schulz wrote:
> Hi Trevor,
> 
> On 5/6/25 7:23 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > Fixes [YOCTO #15509]
> > 
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> >   documentation/ref-manual/variables.rst | 18 ++++++++++++++++++
> >   1 file changed, 18 insertions(+)
> > 
> > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > index d17f81036b7d..29f34f5b029d 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -10942,6 +10942,24 @@ system and gives an overview of their function and contents.
> >         Specifies the timeout in seconds used by the ``watchdog-config`` recipe
> >         and also by ``systemd`` during reboot. The default is 60 seconds.
> > +   :term:`WIC_CREATE_EXTRA_ARGS`
> > +      If the :term:`IMAGE_FSTYPES` variable contains "wic", the build
> > +      will generate a Wic image automatically when BitBake builds an
> 
> Maybe we could point Wic image to https://docs.yoctoproject.org/dev-manual/wic.html#creating-partitioned-images-using-wic?

ok

> > +      image recipe. As part of this process the Wic bbclass will call the
> 
> There's no wic bbclass.

I know. That's why I didn't write "wic.bbclass". I wrote, generically, the Wic
bbclass.

> I think you meant to say image_types_wic bbclass? It
> would be nice to provide a :ref: there but we actually do not have the class
> explained yet so cannot do a :ref:`ref-classes-image_types_wic` like we
> could for image_types.

I didn't want to give a specific name and wanted to write something that would
be immune from changes in the bbclass's name. Also, layers might implement
their own bbclass that uses wic, so I wanted to include those as well.

> 
> > +      "`wic create`" command. The `WIC_CREATE_EXTRA_ARGS` variable is
> > +      appended to the internal "`wic create`" command to provide a
> > +      mechanism for the user to supply extra arguments to the
> > +      "`wic create`" command that is automatically run by BitBake.
> > +
> 
> A bit too many
> 
> the "`wic create`" command
> 
> to my taste, can suggest:
> 
> To allow the user to supply extra arguments,
> the `WIC_CREATE_EXTRA_ARGS` variable is
> appended to the internal "`wic create`" command
> that is automatically run by BitBake.
> 
> What do you think?

sounds good

> > +      One such useful purpose for this mechanism is to add the "-D|--debug"
> 
> -D (or --debug)

ok

> maybe? I believe this would otherwise break the search or not be crystal
> clear what the option is supposed to be.
> 
> Looks good to me otherwise,
> 
> Cheers,
> Quentin

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

[Quentin Schulz]

Hi Trevor,

On 5/12/25 11:01 PM, Trevor Woerner wrote:
> On Mon 2025-05-12 @ 09:31:27 AM, Quentin Schulz wrote:
>> Hi Trevor,
>>
>> On 5/6/25 7:23 PM, Trevor Woerner via lists.yoctoproject.org wrote:

[...]

>>> +      image recipe. As part of this process the Wic bbclass will call the
>>
>> There's no wic bbclass.
> 
> I know. That's why I didn't write "wic.bbclass". I wrote, generically, the Wic
> bbclass.
> 
>> I think you meant to say image_types_wic bbclass? It
>> would be nice to provide a :ref: there but we actually do not have the class
>> explained yet so cannot do a :ref:`ref-classes-image_types_wic` like we
>> could for image_types.
> 
> I didn't want to give a specific name and wanted to write something that would
> be immune from changes in the bbclass's name. Also, layers might implement
> their own bbclass that uses wic, so I wanted to include those as well.
> 

If they have their own bbclass that uses wic, they wouldn't necessarily 
be using WIC_CREATE_EXTRA_ARGS as this variable is specific to 
image_types_wic.bbclass, we also already list the name of some classes 
so it isn't a new problem.

Cheers,
Quentin

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

[Trevor Woerner]

On Tue 2025-05-13 @ 09:59:58 AM, Quentin Schulz wrote:
> Hi Trevor,
> 
> On 5/12/25 11:01 PM, Trevor Woerner wrote:
> > On Mon 2025-05-12 @ 09:31:27 AM, Quentin Schulz wrote:
> > > Hi Trevor,
> > > 
> > > On 5/6/25 7:23 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> 
> [...]
> 
> > > > +      image recipe. As part of this process the Wic bbclass will call the
> > > 
> > > There's no wic bbclass.
> > 
> > I know. That's why I didn't write "wic.bbclass". I wrote, generically, the Wic
> > bbclass.
> > 
> > > I think you meant to say image_types_wic bbclass? It
> > > would be nice to provide a :ref: there but we actually do not have the class
> > > explained yet so cannot do a :ref:`ref-classes-image_types_wic` like we
> > > could for image_types.
> > 
> > I didn't want to give a specific name and wanted to write something that would
> > be immune from changes in the bbclass's name. Also, layers might implement
> > their own bbclass that uses wic, so I wanted to include those as well.
> > 
> 
> If they have their own bbclass that uses wic, they wouldn't necessarily be
> using WIC_CREATE_EXTRA_ARGS as this variable is specific to
> image_types_wic.bbclass, we also already list the name of some classes so it
> isn't a new problem.

I'll just rewrite the part to avoid mentioning the bbclass. How the command is
invoked is irrelevant.