* [PATCH] [dunfell] dev-manual: update session about multiconfig
@ 2022-12-06 10:47 michael.opdenacker
0 siblings, 0 replies; only message in thread
From: michael.opdenacker @ 2022-12-06 10:47 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker, Paul Barker
From: Michael Opdenacker <michael.opdenacker@bootlin.com>
Aligning with contents from the "master" branch.
[YOCTO #14980]
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Paul Barker <paul@pbarker.dev>
---
.../dev-manual/dev-manual-common-tasks.rst | 68 +++++++++----------
1 file changed, 31 insertions(+), 37 deletions(-)
diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 9dcafb2783..8ee386a678 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -3854,7 +3854,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.
@@ -3862,47 +3862,47 @@ 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 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 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 ``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
- directory is ``tmpmultix86``:
- ::
+ directory is ``tmpmultix86``::
MACHINE = "qemux86"
TMPDIR = "${TOPDIR}/tmpmultix86"
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
+ 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``. 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 ``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
:term:`BBMULTICONFIG`
variable in your ``conf/local.conf`` configuration file to specify
each multiconfig. Continuing with the example from the previous
- figure, the ``BBMULTICONFIG`` variable needs to enable two
- multiconfigs: "x86" and "arm" by specifying each configuration file:
- ::
+ figure, the :term:`BBMULTICONFIG` variable needs to enable two
+ multiconfigs: "x86" and "arm" by specifying each configuration file::
BBMULTICONFIG = "x86 arm"
@@ -3916,13 +3916,11 @@ Follow these steps to set up and execute multiple configuration builds:
with "".
- *Launch BitBake*: Use the following BitBake command form to launch
- the multiple configuration build:
- ::
+ the multiple configuration build::
$ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
- For the example in this section, the following command applies:
- ::
+ 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
@@ -3937,7 +3935,7 @@ Follow these steps to set up and execute multiple configuration builds:
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 ``TMPDIR``
+ 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.
@@ -3958,38 +3956,34 @@ essentially that the
To enable dependencies in a multiple configuration build, you must
declare the dependencies in the recipe using the following statement
-form:
-::
+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:
-::
+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 ``do_image`` task in the recipe depends is the
-``do_rootfs`` task from the ``core-image-minimal`` recipe associated
+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:
-::
+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 ``do_rootfs`` task for 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:
-::
+``core-image-sato`` recipe::
do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image"
--
2.37.2
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2022-12-06 10:48 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-12-06 10:47 [PATCH] [dunfell] dev-manual: update session about multiconfig michael.opdenacker
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.