Re: [docs] [PATCH] doc: extend classes and include/require documentation

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Antonin,

Just had the time to review this, sorry for the delay. I'll send a few 
typo and rewording patches soon. However...

On 9/18/25 2:16 PM, Antonin Godard via lists.yoctoproject.org wrote:
[...]
> +Locating Include Files
> +----------------------
> +
> +BitBake uses the :term:`BBPATH` variable to locate needed include files.
> +Additionally, BitBake searches the current directory for :ref:`include
> +<ref-include-directive>` and :ref:`require <require-inclusion>` directives.
> +
> +.. note::
> +
> +   The BBPATH variable is analogous to the environment variable PATH .
> +
> +For these two directives, BitBake includes the first file it finds.
> +
> +.. note::
> +
> +   It is also possible to include *all* occurences of a file with the same name
> +   with the :ref:`include_all <ref-include-all-directive>` directive.
> +
> +Let's consider the following statement called from a recipe file located in
> +``/layers/meta-custom2/recipes-example/example_0.1.bb``::
> +
> +   require myfile.inc
> +
> +Where ``myfile.inc`` is located in ``/layers/meta-custom2/recipes-example/``.
> +
> +And let's assume that the value of :term:`BBPATH` is
> +``/layers/meta-custom1:/layers/meta-custom2``. Then BitBake will try to find
> +``myfile.inc`` in this order::
> +
> +   /layers/meta-custom2/recipes-example/example/myfile.inc
> +   /layers/meta-custom1/myfile.inc
> +   /layers/meta-custom2/myfile.inc
> +
> +In this case the first path of the list matches and BitBake includes this file
> +in ``example_0.1.bb``.
> +
> +Another common example would be::
> +
> +   require recipes-other/other/otherfile.inc
> +
> +Where ``otherfile.inc`` is located in
> +``/layers/meta-custom1/recipes-other/other/``.
> +
> +In this case, the following paths would be searched::
> +
> +   /layers/meta-custom2/recipes-example/example/recipes-other/other/otherfile.inc
> +   /layers/meta-custom1/recipes-other/other/otherfile.inc
> +   /layers/meta-custom2/recipes-other/other/otherfile.inc
> +

I think we should provide an example for include_all directive as well? 
After reading the code, I believe include_all does NOT search the local 
path first, it only searches paths in BBPATH so I think it's worth 
providing an example and maybe notes on how it differs from the other 
directives.

What do you think?

Cheers,
Quentin