ref/dev-manual: Update multiconfig documentation

Message ID 20220609094044.41131-1-richard.purdie@linuxfoundation.org
State New
Headers show
Series ref/dev-manual: Update multiconfig documentation | expand

Commit Message

Richard Purdie June 9, 2022, 9:40 a.m. UTC
Multiconfigs now work from layers. Update the documentation to match this change.
Also fix a incorrect reference to different distros working within the same TMPDIR,
that is incorrect.

[YOCTO #13566]

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/dev-manual/common-tasks.rst | 31 ++++++++++++-----------
 documentation/ref-manual/variables.rst    |  9 ++++---
 2 files changed, 21 insertions(+), 19 deletions(-)

Comments

Marta Rybczynska June 9, 2022, 1 p.m. UTC | #1
On Thu, Jun 9, 2022 at 11:40 AM Richard Purdie
<richard.purdie@linuxfoundation.org> wrote:
>
> Multiconfigs now work from layers. Update the documentation to match this change.
> Also fix a incorrect reference to different distros working within the same TMPDIR,
> that is incorrect.
>
> [YOCTO #13566]
>
> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
>  documentation/dev-manual/common-tasks.rst | 31 ++++++++++++-----------
>  documentation/ref-manual/variables.rst    |  9 ++++---
>  2 files changed, 21 insertions(+), 19 deletions(-)
>
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index ca6d59438..7d17f8d65 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -3704,7 +3704,7 @@ Setting Up and Running a Multiple Configuration Build
>
>  To accomplish a multiple configuration build, you must define each
>  target's configuration separately using a parallel configuration file in
> -the :term:`Build Directory`, and you
> +the :term:`Build Directory` or configuration directory within a layer, and you
>  must follow a required file hierarchy. Additionally, you must enable the
>  multiple configuration builds in your ``local.conf`` file.
>
> @@ -3712,16 +3712,19 @@ Follow these steps to set up and execute multiple configuration builds:
>
>  -  *Create Separate Configuration Files*: You need to create a single
>     configuration file for each build target (each multiconfig).
> -   Minimally, each configuration file must define the machine and the
> -   temporary directory BitBake uses for the build. Suggested practice
> -   dictates that you do not overlap the temporary directories used
> -   during the builds. However, it is possible that you can share the
> -   temporary directory
> -   (:term:`TMPDIR`). For example,
> -   consider a scenario with two different multiconfigs for the same
> +   The configuration definitions are implmentation dependency but often

A typo: implmentation -> implementation

Kind regards,
Marta
Michael Opdenacker June 10, 2022, 5:42 p.m. UTC | #2
Hi Richard,

Thanks a lot for the update!

On 6/9/22 11:40, Richard Purdie wrote:
> +   The configuration definitions are implmentation dependency but often

Did you mean "are implementation dependent"?
I'll be happy to fix this by myself.

Thanks again
Michael.
Richard Purdie June 13, 2022, 1:56 p.m. UTC | #3
On Fri, 2022-06-10 at 19:42 +0200, Michael Opdenacker wrote:
> Hi Richard,
> 
> Thanks a lot for the update!
> 
> On 6/9/22 11:40, Richard Purdie wrote:
> > +   The configuration definitions are implmentation dependency but often
> 
> Did you mean "are implementation dependent"?
> I'll be happy to fix this by myself.

Correct, thanks!

Cheers,

Richard

Patch

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index ca6d59438..7d17f8d65 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -3704,7 +3704,7 @@  Setting Up and Running a Multiple Configuration Build
 
 To accomplish a multiple configuration build, you must define each
 target's configuration separately using a parallel configuration file in
-the :term:`Build Directory`, and you
+the :term:`Build Directory` or configuration directory within a layer, and you
 must follow a required file hierarchy. Additionally, you must enable the
 multiple configuration builds in your ``local.conf`` file.
 
@@ -3712,16 +3712,19 @@  Follow these steps to set up and execute multiple configuration builds:
 
 -  *Create Separate Configuration Files*: You need to create a single
    configuration file for each build target (each multiconfig).
-   Minimally, each configuration file must define the machine and the
-   temporary directory BitBake uses for the build. Suggested practice
-   dictates that you do not overlap the temporary directories used
-   during the builds. However, it is possible that you can share the
-   temporary directory
-   (:term:`TMPDIR`). For example,
-   consider a scenario with two different multiconfigs for the same
+   The configuration definitions are implmentation dependency but often
+   each configuration file will define the machine and the
+   temporary directory BitBake uses for the build. Whether the same
+   temporary directory (:term:`TMPDIR`) can be shared will depend on what is
+   similar and what is different between the configurations. Multiple MACHINE
+   targets can share the same (:term:`TMPDIR`) as long as the rest of the
+   configuration is the same, multiple DISTRO settings would need separate
+   (:term:`TMPDIR`) directories.
+
+   For example, consider a scenario with two different multiconfigs for the same
    :term:`MACHINE`: "qemux86" built
    for two distributions such as "poky" and "poky-lsb". In this case,
-   you might want to use the same :term:`TMPDIR`.
+   you would need to use the different :term:`TMPDIR`.
 
    Here is an example showing the minimal statements needed in a
    configuration file for a "qemux86" target whose temporary build
@@ -3732,18 +3735,16 @@  Follow these steps to set up and execute multiple configuration builds:
 
    The location for these multiconfig configuration files is specific.
    They must reside in the current build directory in a sub-directory of
-   ``conf`` named ``multiconfig``. Following is an example that defines
+   ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory
+   under a directory named ``multiconfig``. Following is an example that defines
    two configuration files for the "x86" and "arm" multiconfigs:
 
    .. image:: figures/multiconfig_files.png
       :align: center
       :width: 50%
 
-   The reason for this required file hierarchy is because the :term:`BBPATH`
-   variable is not constructed until the layers are parsed.
-   Consequently, using the configuration file as a pre-configuration
-   file is not possible unless it is located in the current working
-   directory.
+   The usual :term:`BBPATH` search path is used to locate multiconfig files in
+   a similar way to other conf files.
 
 -  *Add the BitBake Multi-configuration Variable to the Local
    Configuration File*: Use the
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 367b4674e..76437d456 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -718,10 +718,11 @@  system and gives an overview of their function and contents.
 
          BBMULTICONFIG = "configA configB configC"
 
-      Each configuration file you
-      use must reside in the :term:`Build Directory`
-      ``conf/multiconfig`` directory (e.g.
-      ``build_directory/conf/multiconfig/configA.conf``).
+      Each configuration file you use must reside in a ``multiconfig``
+      subdirectory of a configuration directory within a layer, or
+      within the :term:`Build Directory` (e.g.
+      ``build_directory/conf/multiconfig/configA.conf`` or
+      ``mylayer/conf/multiconfig/configB.conf``).
 
       For information on how to use :term:`BBMULTICONFIG` in an environment
       that supports building targets with multiple configurations, see the