[PATCH] doc: bitbake-user-manual-metadata: document the include_all directive

[PATCH] doc: bitbake-user-manual-metadata: document the include_all directive

[Antonin Godard]

From: Antonin Godard <antonin.godard@bootlin.com>

Document the include_all directive, which can be used to include
multiple files present in the same location in different layers.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 .../bitbake-user-manual-metadata.rst          | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 2680c6ac2..415fbf6d6 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -900,6 +900,33 @@ definitions::
    of include . Doing so makes sure that an error is produced if the file cannot
    be found.
 
+``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
+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::
+
+   include_all conf/distro/include/maintainers.inc
+
+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.
+
+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.
+
+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.
+
 .. _require-inclusion:
 
 ``require`` Directive

---
base-commit: d5562e007c7c64e8613a118ab9a6c73ed2063263
change-id: 20250310-include-all-e1626a6db436

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

Re: [docs] [PATCH] doc: bitbake-user-manual-metadata: document the include_all directive

[Quentin Schulz]

Hi Antonin,

On 3/10/25 12:21 PM, Antonin Godard via lists.yoctoproject.org wrote:
> From: Antonin Godard <antonin.godard@bootlin.com>
> 
> Document the include_all directive, which can be used to include
> multiple files present in the same location in different layers.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   .../bitbake-user-manual-metadata.rst          | 27 +++++++++++++++++++
>   1 file changed, 27 insertions(+)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index 2680c6ac2..415fbf6d6 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -900,6 +900,33 @@ definitions::
>      of include . Doing so makes sure that an error is produced if the file cannot
>      be found.
>   
> +``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
> +the enabled layers (layers part of :term:`BBLAYERS`).
> +

s/part of/listed in/ ?

> +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::

s/for/from/

> +
> +   include_all conf/distro/include/maintainers.inc
> +
> +In other words, the ``maintainers.inc`` file for each layer is included through

s/for/from/

or

s/for/found in/

> +the :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`
> +directive.
> +
> +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.
> +

Does this mean if you have multiple files in the same layer in different 
locations in BBPATH they'll be all included?

I think you also wanted to mean that the order in BBPATH/BBLAYERS 
actually can change the outcome since the files are included in order?

Cheers,
Quentin