[PATCH 0/2] Update yocto-check-layer documentation

[PATCH 0/2] Update yocto-check-layer documentation

[Antonin Godard]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (2):
      dev-manual/layers.rst: yocto-check-layer: mention the --machines argument
      test-manual/yocto-project-compatible.rst: fix a typo

 documentation/dev-manual/layers.rst                    | 9 +++++++++
 documentation/test-manual/yocto-project-compatible.rst | 2 +-
 2 files changed, 10 insertions(+), 1 deletion(-)
---
base-commit: e77139b5c616e6e5ad436eb91416fd804389425f
change-id: 20250919-update-compatible-doc-651debba8dfa

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

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

[Antonin Godard]

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> ...
+
+These machines are the ones present in your BSP layer, in the ``conf/machine/``
+directory.
+
 Entering the command causes the script to determine the type of layer
 and then to execute a set of specific tests against the layer. The
 following list overviews the test:

-- 
2.51.0

[PATCH 2/2] test-manual/yocto-project-compatible.rst: fix a typo

[Antonin Godard]

Fix a typo in yocto-project-compatible.rst.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/test-manual/yocto-project-compatible.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/test-manual/yocto-project-compatible.rst b/documentation/test-manual/yocto-project-compatible.rst
index 65d924fad9..7a2e00a99e 100644
--- a/documentation/test-manual/yocto-project-compatible.rst
+++ b/documentation/test-manual/yocto-project-compatible.rst
@@ -38,7 +38,7 @@ Benefits
 and flexible: it gives users the ultimate power to change pretty much any
 aspect of the system but as with most things, power comes with responsibility.
 The Yocto Project would like to see people able to mix and match BSPs with
-distro configs or software stacks and be able to merge succesfully.
+distro configs or software stacks and be able to merge successfully.
 Over time, the project identified characteristics in layers that allow them
 to operate well together. "anti-patterns" were also found, preventing layers
 from working well together.

-- 
2.51.0

Re: [docs] [PATCH 2/2] test-manual/yocto-project-compatible.rst: fix a typo

[Quentin Schulz]

Hi Antonin,

On 9/19/25 12:14 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Fix a typo in yocto-project-compatible.rst.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

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

Thanks!
Quentin

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

[Quentin Schulz]

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 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.

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.

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?

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>

Thanks!
Quentin

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

[Antonin Godard]

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