Re: [docs] [PATCH 1/2] dev-manual/layers.rst: yocto-check-layer: mention the --machines argument

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

Hi,

On Fri Sep 19, 2025 at 12:59 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
>
> On 9/19/25 12:14 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> The yocto-check-layer script should be run with the --machines arguments
>> to test the different machines present in a BSP layer. Mention it in the
>> documentation.
>> 
>> [YOCTO #15974]
>> 
>> Cc: Mark Hatle <mark.hatle@kernel.crashing.org>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/dev-manual/layers.rst | 9 +++++++++
>>   1 file changed, 9 insertions(+)
>> 
>> diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
>> index fbf3f1a33..0bcbceb1e 100644
>> --- a/documentation/dev-manual/layers.rst
>> +++ b/documentation/dev-manual/layers.rst
>> @@ -376,6 +376,15 @@ directory::
>>   Be sure to provide the actual directory for your
>>   layer as part of the command.
>>   
>> +For :term:`BSP <Board Support Package (BSP)>` layers, the ``--machines``
>> +argument should be passed as part of the command::
>> +
>> +   $ source oe-init-build-env
>> +   $ yocto-check-layer your_layer_directory --machines <machine1> <machine2> ...
>> +
>
> Considering the help text of the script, we should probably rather have 
> the machines before the layer directory? I assume you may have tried and 
> discovered that it doesn't work by simply swapping both, likely due to 
> https://github.com/python/cpython/issues/53584?
>
> The answer to that is "--", as in:
>
> yocto-check-layer --machines <machine1> <machine2> ... -- 
> your_layer_directory

I agree, I also prefer separating with --, the command looks cleaner. I'll
send a v2 with that.

> I always wondered what my BSP layer would return to match this and I 
> just tried from within a kas setup.
>
> First thing... it seems it doesn't detect layer dependencies from 
> bblayers.conf, so I have to make them explicit them from the command 
> line via --dependency (which is fine but a bit odd if they already are 
> in bblayers.conf?). Once that is done, BitBake complains because the 
> layer is included twice (?????). So I instead sourced the script from 
> within the kas container to another location, with thus an empty 
> bblayers.conf and then it started.

On master I get:

  INFO: meta-yocto-bsp already in .../build/conf/bblayers.conf. To capture initial signatures, layer under test should not present in BBLAYERS. Please remove meta-yocto-bsp from BBLAYERS.

I had to remove meta-yocto-bsp in the end. There's also a
yocto-check-layer-wrapper script to start from a clean build env FWIW.

So maybe a more recent version of the script would've warned you?

> I ended up calling
>
> yocto-check-layer --machines jaguar puma-haikou ringneck-haikou 
> tiger-haikou --dependency ../meta-openembedded/meta-python/ 
> ../meta-rockchip/ ../meta-arm/meta-arm ../meta-arm/meta-arm-toolchain/ 
> ../meta-openembedded/meta-oe/ -- ../meta-cherry-es/meta-bsp/
>
> which is what's required to setup a BSP build for me.
>
> The issue is that it seems to test more than just my layer?
>
> [...]
> INFO: Setting up for meta-python(LayerType.SOFTWARE), 
> /work/meta-openembedded/meta-python
> INFO: Adding layer meta-oe
> INFO: Getting initial bitbake variables ...
> INFO: Getting initial signatures ...
> INFO: Adding layer meta-python
> INFO: Starting to analyze: meta-python
> INFO: Distro: poky
> [...]
> INFO: Setting up for meta-oe(LayerType.SOFTWARE), 
> /work/meta-openembedded/meta-oe
> INFO: Getting initial bitbake variables ...
> INFO: Getting initial signatures ...
> INFO: Adding layer meta-oe
> INFO: Starting to analyze: meta-oe
> INFO: Distro: poky
> [...]
> INFO: Setting up for meta-rockchip(LayerType.BSP), /work/meta-rockchip
> INFO: Adding layer meta-arm
> INFO: Adding layer meta-arm-toolchain
> INFO: Getting initial bitbake variables ...
> INFO: Getting initial signatures ...
> INFO: Adding layer meta-rockchip
> INFO: Starting to analyze: meta-rockchip
> INFO: Distro: poky
> [...]
> etc....
>
> Which is very surprising to me, why would we want to run the check 
> against those layers? They are dependencies after all and of course 
> since my machine only exists in my BSP layer, the test for my machine 
> won't pass for meta-python without my layer for example.

Maybe it means that a layer can only compatible if its dependencies are also
compatible? I think it's a fair assumption.

> So I'm not sure what is supposed to happen here but I'm not sure what 
> actually matters as output to this script :/
>
> I would recommend to add a few words maybe on the --dependency argument 
> and that it should be run from a clean build directory (at least it 
> seems like to me) to work?

Yes, I think that can be part of the v2 as well, thanks - I was testing on
meta-yocto-bsp which didn't have any dependency.

> What do you think? Can be added in a follow-up patch if wanted, so for 
> the current content:
>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

I'll remove it for the v2, but thanks!

Antonin

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