[PATCH 0/6] Improve multiconfig documentation

[PATCH 0/6] Improve multiconfig documentation

[Antonin Godard]

This series moves the multiconfig doc to its own document in the dev
manual, and adds 2 sections to improve it.

It also adds BB_CURRENT_MC to variables.rst, and fixes previous
references of that variable in the doc.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (6):
      dev-manual: move multiconfig documentation to its own document
      variables.rst: add a reference to BB_CURRENT_MC from bbdocs
      migration-5.2: fix references to BB_CURRENT_MC
      dev-manual/multiconfig: rename to use Multiconfig term
      dev-manual/multiconfig: improve the current doc
      dev-manual/multiconfig: add suggested best practices and baremetal sections

 documentation/dev-manual/building.rst            | 156 +------------
 documentation/dev-manual/index.rst               |   1 +
 documentation/dev-manual/multiconfig.rst         | 279 +++++++++++++++++++++++
 documentation/migration-guides/migration-5.2.rst |   4 +-
 documentation/ref-manual/variables.rst           |   3 +
 5 files changed, 287 insertions(+), 156 deletions(-)
---
base-commit: e2b6ee590a3a790b41636077e702724c9869d7f5
change-id: 20250129-multiconfig-doc-c37342a6ab91

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>

[PATCH 1/6] dev-manual: move multiconfig documentation to its own document

[Antonin Godard]

In preparation of more section and examples to multiconfig, move the
section about it in building.rst into its own document.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/dev-manual/building.rst    | 156 +-----------------------------
 documentation/dev-manual/index.rst       |   1 +
 documentation/dev-manual/multiconfig.rst | 160 +++++++++++++++++++++++++++++++
 3 files changed, 163 insertions(+), 154 deletions(-)

diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst
index 4770a5a18..62b5e6b2e 100644
--- a/documentation/dev-manual/building.rst
+++ b/documentation/dev-manual/building.rst
@@ -113,160 +113,8 @@ The following figure and list overviews the build process:
 Building Images for Multiple Targets Using Multiple Configurations
 ==================================================================
 
-You can use a single ``bitbake`` command to build multiple images or
-packages for different targets where each image or package requires a
-different configuration (multiple configuration builds). The builds, in
-this scenario, are sometimes referred to as "multiconfigs", and this
-section uses that term throughout.
-
-This section describes how to set up for multiple configuration builds
-and how to account for cross-build dependencies between the
-multiconfigs.
-
-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` 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.
-
-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).
-   The configuration definitions are implementation dependent 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 :term:`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 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
-   directory is ``tmpmultix86``::
-
-      MACHINE = "qemux86"
-      TMPDIR = "${TOPDIR}/tmpmultix86"
-
-   The location for these multiconfig configuration files is specific.
-   They must reside in the current :term:`Build Directory` in a sub-directory of
-   ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory
-   under a directory named ``multiconfig``. Here is an example that defines
-   two configuration files for the "x86" and "arm" multiconfigs:
-
-   .. image:: figures/multiconfig_files.png
-      :align: center
-      :width: 50%
-
-   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
-   :term:`BBMULTICONFIG`
-   variable in your ``conf/local.conf`` configuration file to specify
-   each multiconfig. Continuing with the example from the previous
-   figure, the :term:`BBMULTICONFIG` variable needs to enable two
-   multiconfigs: "x86" and "arm" by specifying each configuration file::
-
-      BBMULTICONFIG = "x86 arm"
-
-   .. note::
-
-      A "default" configuration already exists by definition. This
-      configuration is named: "" (i.e. empty string) and is defined by
-      the variables coming from your ``local.conf``
-      file. Consequently, the previous example actually adds two
-      additional configurations to your build: "arm" and "x86" along
-      with "".
-
--  *Launch BitBake*: Use the following BitBake command form to launch
-   the multiple configuration build::
-
-      $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
-
-   For the example in this section, the following command applies::
-
-      $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base
-
-   The previous BitBake command builds a ``core-image-minimal`` image
-   that is configured through the ``x86.conf`` configuration file, a
-   ``core-image-sato`` image that is configured through the ``arm.conf``
-   configuration file and a ``core-image-base`` that is configured
-   through your ``local.conf`` configuration file.
-
-.. note::
-
-   Support for multiple configuration builds in the Yocto Project &DISTRO;
-   (&DISTRO_NAME;) Release does not include Shared State (sstate)
-   optimizations. Consequently, if a build uses the same object twice
-   in, for example, two different :term:`TMPDIR`
-   directories, the build either loads from an existing sstate cache for
-   that build at the start or builds the object fresh.
-
-Enabling Multiple Configuration Build Dependencies
---------------------------------------------------
-
-Sometimes dependencies can exist between targets (multiconfigs) in a
-multiple configuration build. For example, suppose that in order to
-build a ``core-image-sato`` image for an "x86" multiconfig, the root
-filesystem of an "arm" multiconfig must exist. This dependency is
-essentially that the
-:ref:`ref-tasks-image` task in the
-``core-image-sato`` recipe depends on the completion of the
-:ref:`ref-tasks-rootfs` task of the
-``core-image-minimal`` recipe.
-
-To enable dependencies in a multiple configuration build, you must
-declare the dependencies in the recipe using the following statement
-form::
-
-   task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"
-
-To better show how to use this statement, consider the example scenario
-from the first paragraph of this section. The following statement needs
-to be added to the recipe that builds the ``core-image-sato`` image::
-
-   do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs"
-
-In this example, the `from_multiconfig` is "x86". The `to_multiconfig` is "arm". The
-task on which the :ref:`ref-tasks-image` task in the recipe depends is the
-:ref:`ref-tasks-rootfs` task from the ``core-image-minimal`` recipe associated
-with the "arm" multiconfig.
-
-Once you set up this dependency, you can build the "x86" multiconfig
-using a BitBake command as follows::
-
-   $ bitbake mc:x86:core-image-sato
-
-This command executes all the tasks needed to create the
-``core-image-sato`` image for the "x86" multiconfig. Because of the
-dependency, BitBake also executes through the :ref:`ref-tasks-rootfs` task for the
-"arm" multiconfig build.
-
-Having a recipe depend on the root filesystem of another build might not
-seem that useful. Consider this change to the statement in the
-``core-image-sato`` recipe::
-
-   do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image"
-
-In this case, BitBake must
-create the ``core-image-minimal`` image for the "arm" build since the
-"x86" build depends on it.
-
-Because "x86" and "arm" are enabled for multiple configuration builds
-and have separate configuration files, BitBake places the artifacts for
-each build in the respective temporary build directories (i.e.
-:term:`TMPDIR`).
+See the :ref:`dev-manual/multiconfig` section of the Yocto Project Development
+Tasks Manual.
 
 Building an Initial RAM Filesystem (Initramfs) Image
 ====================================================
diff --git a/documentation/dev-manual/index.rst b/documentation/dev-manual/index.rst
index 760108f60..63736e0ab 100644
--- a/documentation/dev-manual/index.rst
+++ b/documentation/dev-manual/index.rst
@@ -20,6 +20,7 @@ Yocto Project Development Tasks Manual
    development-shell
    python-development-shell
    building
+   multiconfig
    speeding-up-build
    libraries
    prebuilt-libraries
diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
new file mode 100644
index 000000000..8464f80c3
--- /dev/null
+++ b/documentation/dev-manual/multiconfig.rst
@@ -0,0 +1,160 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+Building Images for Multiple Targets Using Multiple Configurations
+******************************************************************
+
+You can use a single ``bitbake`` command to build multiple images or
+packages for different targets where each image or package requires a
+different configuration (multiple configuration builds). The builds, in
+this scenario, are sometimes referred to as "multiconfigs", and this
+section uses that term throughout.
+
+This section describes how to set up for multiple configuration builds
+and how to account for cross-build dependencies between the
+multiconfigs.
+
+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` 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.
+
+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).
+   The configuration definitions are implementation dependent 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 :term:`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 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
+   directory is ``tmpmultix86``::
+
+      MACHINE = "qemux86"
+      TMPDIR = "${TOPDIR}/tmpmultix86"
+
+   The location for these multiconfig configuration files is specific.
+   They must reside in the current :term:`Build Directory` in a sub-directory of
+   ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory
+   under a directory named ``multiconfig``. Here is an example that defines
+   two configuration files for the "x86" and "arm" multiconfigs:
+
+   .. image:: figures/multiconfig_files.png
+      :align: center
+      :width: 50%
+
+   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
+   :term:`BBMULTICONFIG`
+   variable in your ``conf/local.conf`` configuration file to specify
+   each multiconfig. Continuing with the example from the previous
+   figure, the :term:`BBMULTICONFIG` variable needs to enable two
+   multiconfigs: "x86" and "arm" by specifying each configuration file::
+
+      BBMULTICONFIG = "x86 arm"
+
+   .. note::
+
+      A "default" configuration already exists by definition. This
+      configuration is named: "" (i.e. empty string) and is defined by
+      the variables coming from your ``local.conf``
+      file. Consequently, the previous example actually adds two
+      additional configurations to your build: "arm" and "x86" along
+      with "".
+
+-  *Launch BitBake*: Use the following BitBake command form to launch
+   the multiple configuration build::
+
+      $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
+
+   For the example in this section, the following command applies::
+
+      $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base
+
+   The previous BitBake command builds a ``core-image-minimal`` image
+   that is configured through the ``x86.conf`` configuration file, a
+   ``core-image-sato`` image that is configured through the ``arm.conf``
+   configuration file and a ``core-image-base`` that is configured
+   through your ``local.conf`` configuration file.
+
+.. note::
+
+   Support for multiple configuration builds in the Yocto Project &DISTRO;
+   (&DISTRO_NAME;) Release does not include Shared State (sstate)
+   optimizations. Consequently, if a build uses the same object twice
+   in, for example, two different :term:`TMPDIR`
+   directories, the build either loads from an existing sstate cache for
+   that build at the start or builds the object fresh.
+
+Enabling Multiple Configuration Build Dependencies
+==================================================
+
+Sometimes dependencies can exist between targets (multiconfigs) in a
+multiple configuration build. For example, suppose that in order to
+build a ``core-image-sato`` image for an "x86" multiconfig, the root
+filesystem of an "arm" multiconfig must exist. This dependency is
+essentially that the
+:ref:`ref-tasks-image` task in the
+``core-image-sato`` recipe depends on the completion of the
+:ref:`ref-tasks-rootfs` task of the
+``core-image-minimal`` recipe.
+
+To enable dependencies in a multiple configuration build, you must
+declare the dependencies in the recipe using the following statement
+form::
+
+   task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"
+
+To better show how to use this statement, consider the example scenario
+from the first paragraph of this section. The following statement needs
+to be added to the recipe that builds the ``core-image-sato`` image::
+
+   do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs"
+
+In this example, the `from_multiconfig` is "x86". The `to_multiconfig` is "arm". The
+task on which the :ref:`ref-tasks-image` task in the recipe depends is the
+:ref:`ref-tasks-rootfs` task from the ``core-image-minimal`` recipe associated
+with the "arm" multiconfig.
+
+Once you set up this dependency, you can build the "x86" multiconfig
+using a BitBake command as follows::
+
+   $ bitbake mc:x86:core-image-sato
+
+This command executes all the tasks needed to create the
+``core-image-sato`` image for the "x86" multiconfig. Because of the
+dependency, BitBake also executes through the :ref:`ref-tasks-rootfs` task for the
+"arm" multiconfig build.
+
+Having a recipe depend on the root filesystem of another build might not
+seem that useful. Consider this change to the statement in the
+``core-image-sato`` recipe::
+
+   do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image"
+
+In this case, BitBake must
+create the ``core-image-minimal`` image for the "arm" build since the
+"x86" build depends on it.
+
+Because "x86" and "arm" are enabled for multiple configuration builds
+and have separate configuration files, BitBake places the artifacts for
+each build in the respective temporary build directories (i.e.
+:term:`TMPDIR`).
+

-- 
2.47.0

Re: [docs] [PATCH 1/6] dev-manual: move multiconfig documentation to its own document

[Quentin Schulz]

Hi Antonin,

On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
> In preparation of more section and examples to multiconfig, move the
> section about it in building.rst into its own document.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [docs] [PATCH 1/6] dev-manual: move multiconfig documentation to its own document

[Quentin Schulz]

Hi Antonin,

On 2/11/25 11:41 AM, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
> 
> On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> In preparation of more section and examples to multiconfig, move the
>> section about it in building.rst into its own document.
>>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> 
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> 

Rescinded actually.

This doesn't build.

yocto-docs/documentation/dev-manual/building.rst:116: WARNING: undefined 
label: 'dev-manual/multiconfig' [ref.ref]

You did fix it in patch 4 during the rename but it should be fixed here 
as well, so please do :)

You can use either:

:doc:`multiconfig`

or

:ref:`dev-manual/multiconfig:Building Images for Multiple Targets Using 
Multiple Configurations`

The benefit of the former is that you don't need to modify when you 
change the title in patch 4.

Cheers,
Quentin

[PATCH 2/6] variables.rst: add a reference to BB_CURRENT_MC from bbdocs

[Antonin Godard]

BB_CURRENT_MC is documented in the Bitbake user manual. Add a reference
to it here.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/variables.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index adbef69d8..a402815b6 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -390,6 +390,9 @@ system and gives an overview of their function and contents.
    :term:`BB_CURRENTTASK`
       See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual.
 
+   :term:`BB_CURRENT_MC`
+      See :term:`bitbake:BB_CURRENT_MC` in the BitBake manual.
+
    :term:`BB_DEFAULT_TASK`
       See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual.
 

-- 
2.47.0

Re: [docs] [PATCH 2/6] variables.rst: add a reference to BB_CURRENT_MC from bbdocs

[Quentin Schulz]

Hi Antonin,

On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
> BB_CURRENT_MC is documented in the Bitbake user manual. Add a reference
> to it here.
> 

Not merged in master yet though? Did you forget to add a dependency on 
another patch series in the cover letter maybe?

Cheers,
Quentin

[PATCH 3/6] migration-5.2: fix references to BB_CURRENT_MC

[Antonin Godard]

Now part of the documentation.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/migration-guides/migration-5.2.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
index de2ea773e..75bc4dbc6 100644
--- a/documentation/migration-guides/migration-5.2.rst
+++ b/documentation/migration-guides/migration-5.2.rst
@@ -97,12 +97,12 @@ systemd changes
 Multiconfig changes
 ~~~~~~~~~~~~~~~~~~~
 
-The value of ``BB_CURRENT_MC`` was changed from ``default`` to an empty string
+The value of :term:`BB_CURRENT_MC` was changed from ``default`` to an empty string
 for the default multiconfig configuration to avoid needing to map the values
 within BitBake. This was already not happening in some cases so this fixes
 some obscure bugs.
 
-Any logic based on ``BB_CURRENT_MC`` equalling to ``default`` by default should
+Any logic based on :term:`BB_CURRENT_MC` equalling to ``default`` by default should
 be changed to be equal to an empty string.
 
 Virtual toolchain provider changes

-- 
2.47.0

[PATCH 4/6] dev-manual/multiconfig: rename to use Multiconfig term

[Antonin Godard]

Rename this section to explicitely name the multiple configuration feature
"multiconfig".

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/dev-manual/building.rst    | 4 ++--
 documentation/dev-manual/multiconfig.rst | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst
index 62b5e6b2e..2ac898881 100644
--- a/documentation/dev-manual/building.rst
+++ b/documentation/dev-manual/building.rst
@@ -113,8 +113,8 @@ The following figure and list overviews the build process:
 Building Images for Multiple Targets Using Multiple Configurations
 ==================================================================
 
-See the :ref:`dev-manual/multiconfig` section of the Yocto Project Development
-Tasks Manual.
+See the :ref:`dev-manual/multiconfig:Building Images for Multiple Targets With
+Multiconfig` section of the Yocto Project Development Tasks Manual.
 
 Building an Initial RAM Filesystem (Initramfs) Image
 ====================================================
diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
index 8464f80c3..d8f6470d5 100644
--- a/documentation/dev-manual/multiconfig.rst
+++ b/documentation/dev-manual/multiconfig.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
 
-Building Images for Multiple Targets Using Multiple Configurations
-******************************************************************
+Building Images for Multiple Targets With Multiconfig
+*****************************************************
 
 You can use a single ``bitbake`` command to build multiple images or
 packages for different targets where each image or package requires a

-- 
2.47.0

Re: [docs] [PATCH 4/6] dev-manual/multiconfig: rename to use Multiconfig term

[Quentin Schulz]

Hi Antonin,

On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Rename this section to explicitely name the multiple configuration feature
> "multiconfig".
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

[PATCH 5/6] dev-manual/multiconfig: improve the current doc

[Antonin Godard]

After the suggestions from Mark Hatle on the list
(https://lists.yoctoproject.org/g/docs/topic/110487932), rewrite the
introduction to multiconfig with the following changes:

- Move the part of overriding TMPDIR or not to a note.
- Use BB_CURRENT_MC in the example.
- Various additions of references & improved formatting.

Suggested-by: Mark Hatle <mark.hatle@kernel.crashing.org>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/dev-manual/multiconfig.rst | 65 +++++++++++++++++++-------------
 1 file changed, 39 insertions(+), 26 deletions(-)

diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
index d8f6470d5..27442a042 100644
--- a/documentation/dev-manual/multiconfig.rst
+++ b/documentation/dev-manual/multiconfig.rst
@@ -17,7 +17,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
+target's configuration separately using a parallel :term:`configuration file` in
 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.
@@ -25,31 +25,27 @@ multiple configuration builds in your ``local.conf`` file.
 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).
+   :term:`Configuration File` for each build target (each multiconfig).
    The configuration definitions are implementation dependent 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 :term:`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 would need to use the different :term:`TMPDIR`.
+   each configuration file will define the :term:`MACHINE` and the
+   temporary directory BitBake uses for the build.
 
-   Here is an example showing the minimal statements needed in a
-   configuration file for a "qemux86" target whose temporary build
-   directory is ``tmpmultix86``::
+   .. note::
 
-      MACHINE = "qemux86"
-      TMPDIR = "${TOPDIR}/tmpmultix86"
+      Whether the same temporary directory (:term:`TMPDIR`) can be shared will
+      depend on what is similar and what is different between the
+      configurations. Multiple :term:`MACHINE` targets can share the same
+      :term:`TMPDIR` as long as the rest of the configuration is the same,
+      multiple :term:`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 would need to use two different :term:`TMPDIR`.
 
    The location for these multiconfig configuration files is specific.
    They must reside in the current :term:`Build Directory` in a sub-directory of
-   ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory
+   ``conf`` named ``multiconfig`` or within a :term:`Layer`'s ``conf`` directory
    under a directory named ``multiconfig``. Here is an example that defines
    two configuration files for the "x86" and "arm" multiconfigs:
 
@@ -58,7 +54,19 @@ Follow these steps to set up and execute multiple configuration builds:
       :width: 50%
 
    The usual :term:`BBPATH` search path is used to locate multiconfig files in
-   a similar way to other conf files.
+   a similar way to other configuration files.
+
+   Here is an example showing the minimal statements needed in a
+   :term:`configuration file` named ``qemux86.conf`` for a ``qemux86`` target
+   whose temporary build directory is ``tmp-qemux86``::
+
+      MACHINE = "qemux86"
+      TMPDIR .= "-${BB_CURRENT_MC}"
+
+   BitBake will expand the :term:`BB_CURRENT_MC` variable to the value of the
+   current multiconfig in use. We append this value to :term:`TMPDIR` so that
+   any change on the definition of :term:`TMPDIR` will automatically affect the
+   value of :term:`TMPDIR` for each multiconfig.
 
 -  *Add the BitBake Multi-configuration Variable to the Local
    Configuration File*: Use the
@@ -88,11 +96,16 @@ Follow these steps to set up and execute multiple configuration builds:
 
       $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base
 
-   The previous BitBake command builds a ``core-image-minimal`` image
-   that is configured through the ``x86.conf`` configuration file, a
-   ``core-image-sato`` image that is configured through the ``arm.conf``
-   configuration file and a ``core-image-base`` that is configured
-   through your ``local.conf`` configuration file.
+   The previous BitBake command builds several components:
+
+   -  A ``core-image-minimal`` image that is configured through the ``x86.conf``
+      configuration file
+
+   -  A ``core-image-sato`` image that is configured through the ``arm.conf``
+      configuration file
+
+   -  A ``core-image-base`` that is configured through your ``local.conf``
+      configuration file
 
 .. note::
 

-- 
2.47.0

Re: [docs] [PATCH 5/6] dev-manual/multiconfig: improve the current doc

[Quentin Schulz]

Hi Antonin,

On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
> After the suggestions from Mark Hatle on the list
> (https://lists.yoctoproject.org/g/docs/topic/110487932), rewrite the
> introduction to multiconfig with the following changes:
> 
> - Move the part of overriding TMPDIR or not to a note.
> - Use BB_CURRENT_MC in the example.
> - Various additions of references & improved formatting.
> 
> Suggested-by: Mark Hatle <mark.hatle@kernel.crashing.org>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/dev-manual/multiconfig.rst | 65 +++++++++++++++++++-------------
>   1 file changed, 39 insertions(+), 26 deletions(-)
> 
> diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
> index d8f6470d5..27442a042 100644
> --- a/documentation/dev-manual/multiconfig.rst
> +++ b/documentation/dev-manual/multiconfig.rst
> @@ -17,7 +17,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
> +target's configuration separately using a parallel :term:`configuration file` in
>   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.
> @@ -25,31 +25,27 @@ multiple configuration builds in your ``local.conf`` file.
>   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).
> +   :term:`Configuration File` for each build target (each multiconfig).
>      The configuration definitions are implementation dependent 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 :term:`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 would need to use the different :term:`TMPDIR`.
> +   each configuration file will define the :term:`MACHINE` and the
> +   temporary directory BitBake uses for the build.

Add that temporary directory = :term:`TMPDIR` maybe?

>   
> -   Here is an example showing the minimal statements needed in a
> -   configuration file for a "qemux86" target whose temporary build
> -   directory is ``tmpmultix86``::
> +   .. note::
>   
> -      MACHINE = "qemux86"
> -      TMPDIR = "${TOPDIR}/tmpmultix86"
> +      Whether the same temporary directory (:term:`TMPDIR`) can be shared will
> +      depend on what is similar and what is different between the
> +      configurations. Multiple :term:`MACHINE` targets can share the same
> +      :term:`TMPDIR` as long as the rest of the configuration is the same,
> +      multiple :term:`DISTRO` settings would need separate :term:`TMPDIR`
> +      directories.
> +

I have zero experience with multiconfig, but I think the only case where 
we should be able to share a TMPDIR is whenever all recipes but the ones 
whose PACKAGE_ARCH is MACHINE_ARCH are the same for both machines (or do 
not conflict, e.g. a different TUNE_PKGARCH for each machine). This 
includes not overriding anything for a machine (e.g. 
do_install:my-machine-a() or SRC_URI:append:my-machine-b, etc..; though 
I believe this must require adding PACKAGE_ARCH = MACHINE_ARCH for those 
recipes?). Overall, I guess this is a VERY niche corner case?

Cheers,
Quentin

> +      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 would need to use two different :term:`TMPDIR`.
>   
>      The location for these multiconfig configuration files is specific.
>      They must reside in the current :term:`Build Directory` in a sub-directory of
> -   ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory
> +   ``conf`` named ``multiconfig`` or within a :term:`Layer`'s ``conf`` directory
>      under a directory named ``multiconfig``. Here is an example that defines
>      two configuration files for the "x86" and "arm" multiconfigs:
>   
> @@ -58,7 +54,19 @@ Follow these steps to set up and execute multiple configuration builds:
>         :width: 50%
>   
>      The usual :term:`BBPATH` search path is used to locate multiconfig files in
> -   a similar way to other conf files.
> +   a similar way to other configuration files.
> +

Using

:term:`configuration files<configuration file>`

here maybe?

The changes look fine to me, just an issue around using BB_CURRENT_MC 
when it's not actually usable yet (not merged in BitBake just yet).

Cheers,
Quentin

Re: [docs] [PATCH 5/6] dev-manual/multiconfig: improve the current doc

[Antonin Godard]

Hi Quentin,

On Tue Feb 11, 2025 at 12:19 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> After the suggestions from Mark Hatle on the list
>> (https://lists.yoctoproject.org/g/docs/topic/110487932), rewrite the
>> introduction to multiconfig with the following changes:
>> 
>> - Move the part of overriding TMPDIR or not to a note.
>> - Use BB_CURRENT_MC in the example.
>> - Various additions of references & improved formatting.
>> 
>> Suggested-by: Mark Hatle <mark.hatle@kernel.crashing.org>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/dev-manual/multiconfig.rst | 65 +++++++++++++++++++-------------
>>   1 file changed, 39 insertions(+), 26 deletions(-)
>> 
>> diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
>> index d8f6470d5..27442a042 100644
>> --- a/documentation/dev-manual/multiconfig.rst
>> +++ b/documentation/dev-manual/multiconfig.rst
>> @@ -17,7 +17,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
>> +target's configuration separately using a parallel :term:`configuration file` in
>>   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.
>> @@ -25,31 +25,27 @@ multiple configuration builds in your ``local.conf`` file.
>>   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).
>> +   :term:`Configuration File` for each build target (each multiconfig).
>>      The configuration definitions are implementation dependent 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 :term:`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 would need to use the different :term:`TMPDIR`.
>> +   each configuration file will define the :term:`MACHINE` and the
>> +   temporary directory BitBake uses for the build.
>
> Add that temporary directory = :term:`TMPDIR` maybe?

Will do in v2.

>>   
>> -   Here is an example showing the minimal statements needed in a
>> -   configuration file for a "qemux86" target whose temporary build
>> -   directory is ``tmpmultix86``::
>> +   .. note::
>>   
>> -      MACHINE = "qemux86"
>> -      TMPDIR = "${TOPDIR}/tmpmultix86"
>> +      Whether the same temporary directory (:term:`TMPDIR`) can be shared will
>> +      depend on what is similar and what is different between the
>> +      configurations. Multiple :term:`MACHINE` targets can share the same
>> +      :term:`TMPDIR` as long as the rest of the configuration is the same,
>> +      multiple :term:`DISTRO` settings would need separate :term:`TMPDIR`
>> +      directories.
>> +
>
> I have zero experience with multiconfig, but I think the only case where 
> we should be able to share a TMPDIR is whenever all recipes but the ones 
> whose PACKAGE_ARCH is MACHINE_ARCH are the same for both machines (or do 
> not conflict, e.g. a different TUNE_PKGARCH for each machine). This 
> includes not overriding anything for a machine (e.g. 
> do_install:my-machine-a() or SRC_URI:append:my-machine-b, etc..; though 
> I believe this must require adding PACKAGE_ARCH = MACHINE_ARCH for those 
> recipes?). Overall, I guess this is a VERY niche corner case?

To be fair, I can hardly think of a use-case where you would use the same
TMPDIR, and it doesn't seem to be the general use-case. This is why I moved that
to a note, so the "proper" way is emphasized below.

Maybe someone more experienced can confirm your thoughts on this!

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH 5/6] dev-manual/multiconfig: improve the current doc

[Quentin Schulz]

Hi Antonin,

On 2/12/25 1:49 PM, Antonin Godard wrote:
> Hi Quentin,
> 
> On Tue Feb 11, 2025 at 12:19 PM CET, Quentin Schulz wrote:
>> Hi Antonin,
>>
>> On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
[...]

>>> -   Here is an example showing the minimal statements needed in a
>>> -   configuration file for a "qemux86" target whose temporary build
>>> -   directory is ``tmpmultix86``::
>>> +   .. note::
>>>    
>>> -      MACHINE = "qemux86"
>>> -      TMPDIR = "${TOPDIR}/tmpmultix86"
>>> +      Whether the same temporary directory (:term:`TMPDIR`) can be shared will
>>> +      depend on what is similar and what is different between the
>>> +      configurations. Multiple :term:`MACHINE` targets can share the same
>>> +      :term:`TMPDIR` as long as the rest of the configuration is the same,
>>> +      multiple :term:`DISTRO` settings would need separate :term:`TMPDIR`
>>> +      directories.
>>> +
>>
>> I have zero experience with multiconfig, but I think the only case where
>> we should be able to share a TMPDIR is whenever all recipes but the ones
>> whose PACKAGE_ARCH is MACHINE_ARCH are the same for both machines (or do
>> not conflict, e.g. a different TUNE_PKGARCH for each machine). This
>> includes not overriding anything for a machine (e.g.
>> do_install:my-machine-a() or SRC_URI:append:my-machine-b, etc..; though
>> I believe this must require adding PACKAGE_ARCH = MACHINE_ARCH for those
>> recipes?). Overall, I guess this is a VERY niche corner case?
> 
> To be fair, I can hardly think of a use-case where you would use the same
> TMPDIR, and it doesn't seem to be the general use-case. This is why I moved that
> to a note, so the "proper" way is emphasized below.
> 
> Maybe someone more experienced can confirm your thoughts on this!
> 

Maybe we should simply not suggest it at all so people don't get ideas :)

Cheers,
Quentin

[PATCH 6/6] dev-manual/multiconfig: add suggested best practices and baremetal sections

[Antonin Godard]

After the suggestions from Mark Hatle on the list
(https://lists.yoctoproject.org/g/docs/topic/110487932), add two
sections to the multiconfig doc:

- Suggested best practices: suggestion for better design of multiconfig
  builds.

- Common use case: baremetal build.

  This section applies the guidelines from the first sections and apply
  it to a real-life example of how to use multiconfig. This one to build
  some baremetal firmware alongside a regular Linux build.

Suggested-by: Mark Hatle <mark.hatle@kernel.crashing.org>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/dev-manual/multiconfig.rst | 106 +++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
index 27442a042..9560ce5a0 100644
--- a/documentation/dev-manual/multiconfig.rst
+++ b/documentation/dev-manual/multiconfig.rst
@@ -171,3 +171,109 @@ and have separate configuration files, BitBake places the artifacts for
 each build in the respective temporary build directories (i.e.
 :term:`TMPDIR`).
 
+Suggested best practices
+========================
+
+-  :term:`TMPDIR` (other then the default set in bitbake.conf) is only set in
+   ``local.conf`` by the user. This means that we should **not** manipulate
+   :term:`TMPDIR` in any way within the Machine or Distro :term:`configuration
+   file`.
+
+-  A multiconfig should specify a :term:`TMPDIR`, and should specify it by
+   appending the multiconfig name via :term:`BB_CURRENT_MC`.
+
+-  Recipes that are used to transfer the output from a multiconfig build should
+   use ``task[mcdepends]`` to trigger the build of the component, and then
+   transfer the item to the current configuration in :ref:`ref-tasks-install`
+   :ref:`ref-tasks-deploy`, assuming the value of the deployed item based on
+   :term:`TMPDIR`.
+
+-  Firmware recipes can set the :term:`INHIBIT_DEFAULT_DEPS` variable to ``1``
+   if they don't rely on default dependencies such as the standard C library.
+
+Common use case: building baremetal firmware alongside a Linux build
+====================================================================
+
+A common use for multiconfig is to use the default configuration as the regular
+Linux build, while one or more multiconfigs can be used to build special
+components, such as baremetal firmware. This section details how one can achieve
+this scenario.
+
+Adding a multiconfig configuration file and recipe for a baremetal firmware
+---------------------------------------------------------------------------
+
+As described in :ref:`dev-manual/multiconfig:Setting Up and Running a Multiple
+Configuration Build`, each multiconfig will require a separate
+:term:`Configuration File`. In our case, we will make a separate temporary
+directory for our baremetal firmware build configuration.
+
+For example, we will define a new ``conf/multiconfig/baremetal-firmware.conf``
+as follows::
+
+   TMPDIR .= "-${BB_CURRENT_MC}"
+   TCLIBC = "newlib"
+
+The ``baremetal-firmware.conf`` configure a separate :term:`TMPDIR` for holding
+binaries compiled with the `newlib <https://sourceware.org/newlib/>`__ toolchain
+(see :term:`TCLIBC`).
+
+We then create a recipe ``my-firmware.bb`` that defines how the baremetal
+firmware is built. The recipe should contain enough information for the
+:term:`OpenEmbedded build system` to properly compile the firmware with our
+toolchain. The building tasks may vary depending on the nature of the firmware.
+However, the recipe should define a :ref:`ref-classes-deploy` task that deploys
+the output into the :term:`DEPLOYDIR` directory. We will consider in the
+following that the file is named ``my-firmware.elf``.
+
+Building the firmware
+---------------------
+
+The firmware can be built with BitBake with the following command::
+
+   $ bitbake mc:baremetal-firmware:my-firmware
+
+However, we would prefer for ``my-firmware`` to be automatically built when
+triggering a normal Linux build.
+
+Using an ``mcdepend``, a recipe belonging to the Linux build can trigger the
+build of ``my-firmware``. For example, let's consider that our Linux build needs
+to assemble a "special" firmware that uses the output of our ``my-firmware``
+recipe - let's call it ``my-parent-firmware.bb``. Then, we should specify this
+dependency in ``my-parent-firmware.bb`` with::
+
+   do_compile[mcdepends] = "mc::baremetal-firmware:my-firmware:do_deploy"
+
+The above will ensure that when the :ref:`ref-tasks-compile` task of
+``my-parent-firmware`` is triggered, the :ref:`ref-tasks-deploy` task of
+``my-firmware`` will already have run successfully.
+
+Using the output of ``my-firmware``
+-----------------------------------
+
+After we have deployed ``my-firmware`` by using ``mcdepends``, we need to use
+the output in some way. We can make a series of assumptions, based on the
+default Yocto Project variables in order to get the binary for packaging.
+
+First, we can set the following in ``my-parent-firmware.bb``::
+
+   FIRMWARE_FILE ??= "${TMPDIR}-baremetal-firmware/deploy/images/<machine>/my-firmware.elf"
+   FIRMWARE_FILE[vardepsexclude] += "TMPDIR"
+
+The first assignment stores the value of the path to the firmware built and
+deployed by the ``my-firmware.bb`` recipe. The second assignment excludes the
+:term:`TMPDIR` variable from being part of ``FIRMWARE_FILE``'s dependencies -
+meaning that changing the value of :term:`TMPDIR` (for example, changing the
+host on which the firmware is built) will not invalidate the :ref:`shared state
+cache <overview-manual/concepts:shared state cache>`.
+
+Additionally, ``<machine>`` should be replaced by the machine for which we are
+building in the Linux context.
+
+We can add an :ref:`ref-tasks-install` task to the ``my-parent-firmware``::
+
+   do_install() {
+       install -Dm 0644 ${FIRMWARE_FILE} ${D}/lib/firmware/my-firmware.elf
+   }
+
+Doing the above will allow the firmware binary to be transferred and packaged
+into the Linux context and rootfs.

-- 
2.47.0

Re: [docs] [PATCH 6/6] dev-manual/multiconfig: add suggested best practices and baremetal sections

[Quentin Schulz]

Hi Antonin,

On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
> After the suggestions from Mark Hatle on the list
> (https://lists.yoctoproject.org/g/docs/topic/110487932), add two
> sections to the multiconfig doc:
> 
> - Suggested best practices: suggestion for better design of multiconfig
>    builds.
> 
> - Common use case: baremetal build.
> 
>    This section applies the guidelines from the first sections and apply
>    it to a real-life example of how to use multiconfig. This one to build
>    some baremetal firmware alongside a regular Linux build.
> 
> Suggested-by: Mark Hatle <mark.hatle@kernel.crashing.org>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/dev-manual/multiconfig.rst | 106 +++++++++++++++++++++++++++++++
>   1 file changed, 106 insertions(+)
> 
> diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
> index 27442a042..9560ce5a0 100644
> --- a/documentation/dev-manual/multiconfig.rst
> +++ b/documentation/dev-manual/multiconfig.rst
> @@ -171,3 +171,109 @@ and have separate configuration files, BitBake places the artifacts for
>   each build in the respective temporary build directories (i.e.
>   :term:`TMPDIR`).
>   
> +Suggested best practices
> +========================
> +
> +-  :term:`TMPDIR` (other then the default set in bitbake.conf) is only set in

s/then/than/

and tick quote bitbake.conf

> +   ``local.conf`` by the user. This means that we should **not** manipulate
> +   :term:`TMPDIR` in any way within the Machine or Distro :term:`configuration
> +   file`.
> +
> +-  A multiconfig should specify a :term:`TMPDIR`, and should specify it by
> +   appending the multiconfig name via :term:`BB_CURRENT_MC`.
> +

Provide the example you gave in the previous patch.

> +-  Recipes that are used to transfer the output from a multiconfig build should

+to another

i.e.

from a multiconfig build to another

?

> +   use ``task[mcdepends]`` to trigger the build of the component, and then

maybe use do_task[mcdepends] here?

> +   transfer the item to the current configuration in :ref:`ref-tasks-install`
> +   :ref:`ref-tasks-deploy`, assuming the value of the deployed item based on
> +   :term:`TMPDIR`.
> +

Please provide an example with fictitious recipes and tasks?

There's also a missing word between the install and deploy task refs.

> +-  Firmware recipes can set the :term:`INHIBIT_DEFAULT_DEPS` variable to ``1``
> +   if they don't rely on default dependencies such as the standard C library.
> +
> +Common use case: building baremetal firmware alongside a Linux build
> +====================================================================
> +
> +A common use for multiconfig is to use the default configuration as the regular
> +Linux build, while one or more multiconfigs can be used to build special
> +components, such as baremetal firmware. This section details how one can achieve
> +this scenario.
> +
> +Adding a multiconfig configuration file and recipe for a baremetal firmware
> +---------------------------------------------------------------------------
> +
> +As described in :ref:`dev-manual/multiconfig:Setting Up and Running a Multiple
> +Configuration Build`, each multiconfig will require a separate
> +:term:`Configuration File`. In our case, we will make a separate temporary
> +directory for our baremetal firmware build configuration.
> +
> +For example, we will define a new ``conf/multiconfig/baremetal-firmware.conf``
> +as follows::
> +
> +   TMPDIR .= "-${BB_CURRENT_MC}"
> +   TCLIBC = "newlib"
> +
> +The ``baremetal-firmware.conf`` configure a separate :term:`TMPDIR` for holding
> +binaries compiled with the `newlib <https://sourceware.org/newlib/>`__ toolchain
> +(see :term:`TCLIBC`).
> +
> +We then create a recipe ``my-firmware.bb`` that defines how the baremetal
> +firmware is built. The recipe should contain enough information for the
> +:term:`OpenEmbedded build system` to properly compile the firmware with our
> +toolchain. The building tasks may vary depending on the nature of the firmware.
> +However, the recipe should define a :ref:`ref-classes-deploy` task that deploys
> +the output into the :term:`DEPLOYDIR` directory. We will consider in the
> +following that the file is named ``my-firmware.elf``.
> +
> +Building the firmware
> +---------------------
> +
> +The firmware can be built with BitBake with the following command::
> +
> +   $ bitbake mc:baremetal-firmware:my-firmware
> +
> +However, we would prefer for ``my-firmware`` to be automatically built when
> +triggering a normal Linux build.
> +
> +Using an ``mcdepend``, a recipe belonging to the Linux build can trigger the
> +build of ``my-firmware``. For example, let's consider that our Linux build needs
> +to assemble a "special" firmware that uses the output of our ``my-firmware``
> +recipe - let's call it ``my-parent-firmware.bb``. Then, we should specify this
> +dependency in ``my-parent-firmware.bb`` with::
> +
> +   do_compile[mcdepends] = "mc::baremetal-firmware:my-firmware:do_deploy"
> +
> +The above will ensure that when the :ref:`ref-tasks-compile` task of
> +``my-parent-firmware`` is triggered, the :ref:`ref-tasks-deploy` task of
> +``my-firmware`` will already have run successfully.
> +
> +Using the output of ``my-firmware``
> +-----------------------------------
> +
> +After we have deployed ``my-firmware`` by using ``mcdepends``, we need to use
> +the output in some way. We can make a series of assumptions, based on the
> +default Yocto Project variables in order to get the binary for packaging.
> +
> +First, we can set the following in ``my-parent-firmware.bb``::
> +
> +   FIRMWARE_FILE ??= "${TMPDIR}-baremetal-firmware/deploy/images/<machine>/my-firmware.elf"
> +   FIRMWARE_FILE[vardepsexclude] += "TMPDIR"
> +
> +The first assignment stores the value of the path to the firmware built and
> +deployed by the ``my-firmware.bb`` recipe. The second assignment excludes the
> +:term:`TMPDIR` variable from being part of ``FIRMWARE_FILE``'s dependencies -
> +meaning that changing the value of :term:`TMPDIR` (for example, changing the
> +host on which the firmware is built) will not invalidate the :ref:`shared state
> +cache <overview-manual/concepts:shared state cache>`.
> +
> +Additionally, ``<machine>`` should be replaced by the machine for which we are

s/machine/:term:`MACHINE`/ ?

> +building in the Linux context.
> +

In the baremetal-firmware context rather?

> +We can add an :ref:`ref-tasks-install` task to the ``my-parent-firmware``::

We can +then ?

s/an/a/ ?

Coming from the embedded industry, I find an example using "main SoC" vs 
"companion microcontroller" on the same board drawing a better picture 
than "baremetal firmware" vs "Linux build" especially since we don't 
specify here they could be for different architectures (so implied they 
are for the same).

Other use cases I've seen for multiconfig is rootfs within another 
rootfs, or building a recovery image for a system and putting in on the 
same disk image as the normal rootfs, or building an initramfs with 
another init system than the one used for the main rootfs. We don't have 
to list them all, just sharing here for reference :)

Cheers,
Quentin

Re: [docs] [PATCH 6/6] dev-manual/multiconfig: add suggested best practices and baremetal sections

[Antonin Godard]

Hi Quentin,

On Tue Feb 11, 2025 at 1:08 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 2/7/25 5:28 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> After the suggestions from Mark Hatle on the list
>> (https://lists.yoctoproject.org/g/docs/topic/110487932), add two
>> sections to the multiconfig doc:
>> 
>> - Suggested best practices: suggestion for better design of multiconfig
>>    builds.
>> 
>> - Common use case: baremetal build.
>> 
>>    This section applies the guidelines from the first sections and apply
>>    it to a real-life example of how to use multiconfig. This one to build
>>    some baremetal firmware alongside a regular Linux build.
>> 
>> Suggested-by: Mark Hatle <mark.hatle@kernel.crashing.org>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/dev-manual/multiconfig.rst | 106 +++++++++++++++++++++++++++++++
>>   1 file changed, 106 insertions(+)
>> 
>> diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
>> index 27442a042..9560ce5a0 100644
>> --- a/documentation/dev-manual/multiconfig.rst
>> +++ b/documentation/dev-manual/multiconfig.rst
>> @@ -171,3 +171,109 @@ and have separate configuration files, BitBake places the artifacts for
>>   each build in the respective temporary build directories (i.e.
>>   :term:`TMPDIR`).
>>   
>> +Suggested best practices
>> +========================
>> +
>> +-  :term:`TMPDIR` (other then the default set in bitbake.conf) is only set in
>
> s/then/than/
>
> and tick quote bitbake.conf
>
>> +   ``local.conf`` by the user. This means that we should **not** manipulate
>> +   :term:`TMPDIR` in any way within the Machine or Distro :term:`configuration
>> +   file`.
>> +
>> +-  A multiconfig should specify a :term:`TMPDIR`, and should specify it by
>> +   appending the multiconfig name via :term:`BB_CURRENT_MC`.
>> +
>
> Provide the example you gave in the previous patch.
>
>> +-  Recipes that are used to transfer the output from a multiconfig build should
>
> +to another
>
> i.e.
>
> from a multiconfig build to another
>
> ?
>
>> +   use ``task[mcdepends]`` to trigger the build of the component, and then
>
> maybe use do_task[mcdepends] here?
>
>> +   transfer the item to the current configuration in :ref:`ref-tasks-install`
>> +   :ref:`ref-tasks-deploy`, assuming the value of the deployed item based on
>> +   :term:`TMPDIR`.
>> +
>
> Please provide an example with fictitious recipes and tasks?
>
> There's also a missing word between the install and deploy task refs.

Will be part of v2.

>> +-  Firmware recipes can set the :term:`INHIBIT_DEFAULT_DEPS` variable to ``1``
>> +   if they don't rely on default dependencies such as the standard C library.
>> +
>> +Common use case: building baremetal firmware alongside a Linux build
>> +====================================================================
>> +
>> +A common use for multiconfig is to use the default configuration as the regular
>> +Linux build, while one or more multiconfigs can be used to build special
>> +components, such as baremetal firmware. This section details how one can achieve
>> +this scenario.
>> +
>> +Adding a multiconfig configuration file and recipe for a baremetal firmware
>> +---------------------------------------------------------------------------
>> +
>> +As described in :ref:`dev-manual/multiconfig:Setting Up and Running a Multiple
>> +Configuration Build`, each multiconfig will require a separate
>> +:term:`Configuration File`. In our case, we will make a separate temporary
>> +directory for our baremetal firmware build configuration.
>> +
>> +For example, we will define a new ``conf/multiconfig/baremetal-firmware.conf``
>> +as follows::
>> +
>> +   TMPDIR .= "-${BB_CURRENT_MC}"
>> +   TCLIBC = "newlib"
>> +
>> +The ``baremetal-firmware.conf`` configure a separate :term:`TMPDIR` for holding
>> +binaries compiled with the `newlib <https://sourceware.org/newlib/>`__ toolchain
>> +(see :term:`TCLIBC`).
>> +
>> +We then create a recipe ``my-firmware.bb`` that defines how the baremetal
>> +firmware is built. The recipe should contain enough information for the
>> +:term:`OpenEmbedded build system` to properly compile the firmware with our
>> +toolchain. The building tasks may vary depending on the nature of the firmware.
>> +However, the recipe should define a :ref:`ref-classes-deploy` task that deploys
>> +the output into the :term:`DEPLOYDIR` directory. We will consider in the
>> +following that the file is named ``my-firmware.elf``.
>> +
>> +Building the firmware
>> +---------------------
>> +
>> +The firmware can be built with BitBake with the following command::
>> +
>> +   $ bitbake mc:baremetal-firmware:my-firmware
>> +
>> +However, we would prefer for ``my-firmware`` to be automatically built when
>> +triggering a normal Linux build.
>> +
>> +Using an ``mcdepend``, a recipe belonging to the Linux build can trigger the
>> +build of ``my-firmware``. For example, let's consider that our Linux build needs
>> +to assemble a "special" firmware that uses the output of our ``my-firmware``
>> +recipe - let's call it ``my-parent-firmware.bb``. Then, we should specify this
>> +dependency in ``my-parent-firmware.bb`` with::
>> +
>> +   do_compile[mcdepends] = "mc::baremetal-firmware:my-firmware:do_deploy"
>> +
>> +The above will ensure that when the :ref:`ref-tasks-compile` task of
>> +``my-parent-firmware`` is triggered, the :ref:`ref-tasks-deploy` task of
>> +``my-firmware`` will already have run successfully.
>> +
>> +Using the output of ``my-firmware``
>> +-----------------------------------
>> +
>> +After we have deployed ``my-firmware`` by using ``mcdepends``, we need to use
>> +the output in some way. We can make a series of assumptions, based on the
>> +default Yocto Project variables in order to get the binary for packaging.
>> +
>> +First, we can set the following in ``my-parent-firmware.bb``::
>> +
>> +   FIRMWARE_FILE ??= "${TMPDIR}-baremetal-firmware/deploy/images/<machine>/my-firmware.elf"
>> +   FIRMWARE_FILE[vardepsexclude] += "TMPDIR"
>> +
>> +The first assignment stores the value of the path to the firmware built and
>> +deployed by the ``my-firmware.bb`` recipe. The second assignment excludes the
>> +:term:`TMPDIR` variable from being part of ``FIRMWARE_FILE``'s dependencies -
>> +meaning that changing the value of :term:`TMPDIR` (for example, changing the
>> +host on which the firmware is built) will not invalidate the :ref:`shared state
>> +cache <overview-manual/concepts:shared state cache>`.
>> +
>> +Additionally, ``<machine>`` should be replaced by the machine for which we are
>
> s/machine/:term:`MACHINE`/ ?

Here ``<machine>`` refers to the example, where it is written like so. However I
think I'll replace "by the machine" by "by the :term:`MACHINE`".

>> +building in the Linux context.
>> +
>
> In the baremetal-firmware context rather?

Yes, thanks for pointing that out!

>> +We can add an :ref:`ref-tasks-install` task to the ``my-parent-firmware``::
>
> We can +then ?
>
> s/an/a/ ?
>
> Coming from the embedded industry, I find an example using "main SoC" vs 
> "companion microcontroller" on the same board drawing a better picture 
> than "baremetal firmware" vs "Linux build" especially since we don't 
> specify here they could be for different architectures (so implied they 
> are for the same).

I will try mentioning that this section is not limited to the baremetal firmware
running under the same architecture. Specifically, that the MACHINE variable may
be overridden in the multiconfig conf, if one wants to do so.

> Other use cases I've seen for multiconfig is rootfs within another 
> rootfs, or building a recovery image for a system and putting in on the 
> same disk image as the normal rootfs, or building an initramfs with 
> another init system than the one used for the main rootfs. We don't have 
> to list them all, just sharing here for reference :)

Yes, those are really good examples, hopefully this document can be used in the
future to add and document these! I think this was initially the intent of
Mark's original message.

Thanks!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com