| Message ID | 20250207-multiconfig-doc-v1-5-f63cdab1fad9@bootlin.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Improve multiconfig documentation | expand |
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
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
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
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::
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(-)