bitbake: clarify significance of "include_all" directive

Rewrite the include and include_all sections to drive home the fact
that the include_all directive is relevant in only very specific
cases, and not something developers should expect to use in normal
operation.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

Hi,

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

Thanks,
Antonin

Hi Robert,

On 7/9/25 8:16 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> 
> Rewrite the include and include_all sections to drive home the fact
> that the include_all directive is relevant in only very specific
> cases, and not something developers should expect to use in normal
> operation.
> 
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> 
> ---
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index f60a9d831..1042c65d8 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -874,58 +874,67 @@ becomes a no-op.
>   ``include`` Directive
>   ---------------------
> 
> -BitBake understands the ``include`` directive. This directive causes
> -BitBake to parse whatever file you specify, and to insert that file at
> -that location. The directive is much like its equivalent in Make except
> -that if the path specified on the include line is a relative path,
> -BitBake locates the first file it can find within :term:`BBPATH`.
> -
> -The include directive is a more generic method of including
> +The ``include`` directive causes BitBake to parse a given file,

While at it, always replace ``include`` with the appropriate :ref: 
cross-reference link.

Ditto for ``include_all`` and ``inherit``.

> +and to include that file's contents at the location of the
> +``include`` statement. This directive is similar to its equivalent
> +in Make, except that if the path specified on the BitBake ``include``
> +line is a relative path, BitBake will search for it on the path designated
> +by :term:`BBPATH` and will include *only the first matching file*.
> +
> +The ``include`` directive is a more generic method of including
>   functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>`
>   directive, which is restricted to class (i.e. ``.bbclass``) files. The
> -include directive is applicable for any other kind of shared or
> +``include`` directive is applicable for any other kind of shared or
>   encapsulated functionality or configuration that does not suit a
>   ``.bbclass`` file.
> 
> -As an example, suppose you needed a recipe to include some self-test
> -definitions::
> +For example, if you needed a recipe to include some self-test definitions,
> +you might write::
> 
>      include test_defs.inc
> 
> +The ``include`` directive does not produce an error if the specified file
> +cannot be found. If the included file *must* exist, then you should use
> +use :ref:`require <require-inclusion>` instead, which will generate an error
> +if the file cannot be found.
> +
>   .. note::
> 
> -   The include directive does not produce an error when the file cannot be
> -   found.  Consequently, it is recommended that if the file you are including is
> -   expected to exist, you should use :ref:`require <require-inclusion>` instead
> -   of include . Doing so makes sure that an error is produced if the file cannot
> -   be found.
> +   Note well that the ``include`` directive will include the first matching
> +   file and nothing further (which is almost always the behaviour you want).
> +   If you need to include all matching files, you need to use the
> +   ``include_all`` directive, explained below.
> 
>   ``include_all`` Directive
>   -------------------------
> 
>   The ``include_all`` directive works like the :ref:`include
>   <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`
> -directive but will include all of the files that match the specified path in
> +directive but will include *all* of the files that match the specified path in
>   the enabled layers (layers part of :term:`BBLAYERS`).
> 
> -For example, let's say a ``maintainers.inc`` file is present in different layers
> -and is conventionally placed in the ``conf/distro/include`` directory of each
> -layer. In that case the ``include_all`` directive can be used to include
> -the ``maintainers.inc`` file for all of these layers::
> +.. note::
> 
> -   include_all conf/distro/include/maintainers.inc
> +   This behaviour is rarely what you want in normal operation, and should
> +   be reserved for only those situations when you explicitly want to parse
> +   and include all matching files found across all layers, as the following
> +   example shows.
> 
> -In other words, the ``maintainers.inc`` file for each layer is included through
> -the :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`
> -directive.
> +As a realistic example of this directive, imagine that all of your active
> +layers contain a file ``conf/distro/include/maintainers.inc``, containing
> +maintainer information for the recipes in that layer, and you wanted to
> +collect all of the content from all of those files across all of those layers.
> +You could use the statement::
> +

This may be understood as all active layers must contain a 
conf/distro/include/maintainers.inc file in order for include_all to 
work, but that's not the case. I would reword from "all of your active 
layers" to "some or all of your active layers" or simply "some of your 
active layers".

Maybe avoid "contain" redundancy with

"""
contain a file X with the maintainer information for the recipes in that 
layer
"""

Maybe make the sentence a bit shorter with

"""
you wanted to collect the content of this file from all those layers.
"""

> +   include_all conf/distro/include/maintainers.inc
> 
> -BitBake will iterate through the colon-separated :term:`BBPATH` list to look for
> -matching files to include, from left to right. As a consequence, matching files
> -are included in that order.
> +In this case, BitBake will iterate through all of the directories in
> +the colon-separated :term:`BBPATH` (from left to right) and collect the
> +contents of all matching files, so you end up with the maintainer
> +information of all of your active layers, not just the first one.
> 
> -As the ``include_all`` directive uses the :ref:`include
> -<bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`
> -directive in the background, no error is produced if no files are matched.
> +As the ``include_all`` directive uses the ``include`` directive in the

No need to remove the cross-reference link here.

I don't find the maintainers.inc example particularly useful but I also 
cannot come up with another usecase of this directive so it'll do for now :)

Cheers,
Quentin