[PATCH] ref/dev-manual: Update multiconfig documentation

* [PATCH] ref/dev-manual: Update multiconfig documentation
@ 2022-06-09  9:40 Richard Purdie
  2022-06-09 13:00 ` [docs] " Marta Rybczynska
  2022-06-10 17:42 ` Michael Opdenacker
  0 siblings, 2 replies; 4+ messages in thread
From: Richard Purdie @ 2022-06-09  9:40 UTC (permalink / raw)
  To: docs

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



^ permalink raw reply related	[flat|nested] 4+ messages in thread