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

["Antonin Godard" <antonin.godard@bootlin.com>]

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