[PATCH] manuals: add documentation for WKS_FILES

[PATCH] manuals: add documentation for WKS_FILES

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Fixes [YOCTO #14590]

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/common-tasks.rst |  4 +++-
 documentation/ref-manual/variables.rst    | 13 +++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 3a47a9ff27..ca6d594386 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -5481,7 +5481,9 @@ system needs to meet the following requirements:
    variable.
 
 -  Include the name of the :ref:`wic kickstart file <openembedded-kickstart-wks-reference>`
-   as part of the :term:`WKS_FILE` variable
+   as part of the :term:`WKS_FILE` variable. If multiple candidate files can
+   be provided by different layers, specify all the possible names through the
+   :term:`WKS_FILES` variable instead.
 
 Getting Help
 ------------
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 146af89e8c..ce2b6bf68a 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8767,6 +8767,19 @@ system and gives an overview of their function and contents.
       previous example, some-native-tool would be replaced with an actual
       native tool on which the build would depend.
 
+   :term:`WKS_FILES`
+      Specified a list of candidate Wic kickstart files to be used by the
+      OpenEmbedded build system to create a partitioned image. Only the
+      first one that is found, from left to right, will be used.
+
+      This is only useful when there are multiple ``.wks`` that can be used
+      to produce an image. A typical case is when multiple layers are used
+      for different hardware platforms, each supplying a different
+      ``.wks`` file. In this case, you specify all possible ones through
+      :term:`WKS_FILES`.
+
+      If only one ``.wks`` file is used, set :term:`WKS_FILE` instead.
+
    :term:`WORKDIR`
       The pathname of the work directory in which the OpenEmbedded build
       system builds a recipe. This directory is located within the
-- 
2.25.1

Re: [docs] [PATCH] manuals: add documentation for WKS_FILES

[Quentin Schulz]

Hi Michael,

On 5/20/22 20:35, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> Fixes [YOCTO #14590]
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>   documentation/dev-manual/common-tasks.rst |  4 +++-
>   documentation/ref-manual/variables.rst    | 13 +++++++++++++
>   2 files changed, 16 insertions(+), 1 deletion(-)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 3a47a9ff27..ca6d594386 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -5481,7 +5481,9 @@ system needs to meet the following requirements:
>      variable.
>   
>   -  Include the name of the :ref:`wic kickstart file <openembedded-kickstart-wks-reference>`
> -   as part of the :term:`WKS_FILE` variable
> +   as part of the :term:`WKS_FILE` variable. If multiple candidate files can
> +   be provided by different layers, specify all the possible names through the
> +   :term:`WKS_FILES` variable instead.
>   
>   Getting Help
>   ------------
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 146af89e8c..ce2b6bf68a 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -8767,6 +8767,19 @@ system and gives an overview of their function and contents.
>         previous example, some-native-tool would be replaced with an actual
>         native tool on which the build would depend.
>   
> +   :term:`WKS_FILES`
> +      Specified a list of candidate Wic kickstart files to be used by the

s/Specified/Specifies/

> +      OpenEmbedded build system to create a partitioned image. Only the
> +      first one that is found, from left to right, will be used.
> +
> +      This is only useful when there are multiple ``.wks`` that can be used

+files ?

Looks good otherwise, thanks!

Cheers,
Quentin

Re: [docs] [PATCH] manuals: add documentation for WKS_FILES

[Quentin Schulz]

Hi Michael,

On 5/23/22 10:28, Michael Opdenacker wrote:
> Hi Quentin
> 
> Many thanks for the review!
> 
> On 5/23/22 10:20, Quentin Schulz wrote:
>> Hi Michael,
>>
>> On 5/20/22 20:35, Michael Opdenacker via lists.yoctoproject.org wrote:
>>> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>>
>>> Fixes [YOCTO #14590]
>>>
>>> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>> ---
>>>    documentation/dev-manual/common-tasks.rst |  4 +++-
>>>    documentation/ref-manual/variables.rst    | 13 +++++++++++++
>>>    2 files changed, 16 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/documentation/dev-manual/common-tasks.rst
>>> b/documentation/dev-manual/common-tasks.rst
>>> index 3a47a9ff27..ca6d594386 100644
>>> --- a/documentation/dev-manual/common-tasks.rst
>>> +++ b/documentation/dev-manual/common-tasks.rst
>>> @@ -5481,7 +5481,9 @@ system needs to meet the following requirements:
>>>       variable.
>>>      -  Include the name of the :ref:`wic kickstart file
>>> <openembedded-kickstart-wks-reference>`
>>> -   as part of the :term:`WKS_FILE` variable
>>> +   as part of the :term:`WKS_FILE` variable. If multiple candidate
>>> files can
>>> +   be provided by different layers, specify all the possible names
>>> through the
>>> +   :term:`WKS_FILES` variable instead.
>>>      Getting Help
>>>    ------------
>>> diff --git a/documentation/ref-manual/variables.rst
>>> b/documentation/ref-manual/variables.rst
>>> index 146af89e8c..ce2b6bf68a 100644
>>> --- a/documentation/ref-manual/variables.rst
>>> +++ b/documentation/ref-manual/variables.rst
>>> @@ -8767,6 +8767,19 @@ system and gives an overview of their function
>>> and contents.
>>>          previous example, some-native-tool would be replaced with an
>>> actual
>>>          native tool on which the build would depend.
>>>    +   :term:`WKS_FILES`
>>> +      Specified a list of candidate Wic kickstart files to be used
>>> by the
>>
>> s/Specified/Specifies/
> 
> Oops, fixed.
>>
>>> +      OpenEmbedded build system to create a partitioned image. Only the
>>> +      first one that is found, from left to right, will be used.
>>> +
>>> +      This is only useful when there are multiple ``.wks`` that can
>>> be used
>>
>> +files ?
> 
> 
> Indeed. Good catch.
> 
>>
>>
>> Looks good otherwise, thanks!
> 
> 
> Great, can I add your "Reviewed-by"? The changes are now in master-next.

Sure. Don't worry if you forget it sometimes, I don't care too much 
about them as a reviewer :)

Cheers,
Quentin