diff mbox series

[8/8] doc: bitbake-user-manual-metadata: expand locating files example for include_all directive

Message ID 20260112-doc-directives-v1-8-b23923cfce89@cherry.de
State New
Headers show
Series doc: bitbake-user-manual-metadata: misc improvements on sharing functionality | expand

Commit Message

Quentin Schulz Jan. 12, 2026, 4:36 p.m. UTC 
From: Quentin Schulz <quentin.schulz@cherry.de>

This adds a separate example for the include_all directive which also
highlights that the current directory isn't searched (unlike when using
the include or require directive).

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 .../bitbake-user-manual-metadata.rst               | 32 ++++++++++++++++++----
 1 file changed, 27 insertions(+), 5 deletions(-)
diff mbox series

Patch

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index cbad4df99..18f293f4b 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -1074,11 +1074,6 @@  BitBake also uses the :term:`BBPATH` variable.
 
 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/example_0.1.bb``::
 
@@ -1129,6 +1124,33 @@  In this case, the following paths would be searched::
    In the above examples, the exact same search order applies for the
    :ref:`include <ref-include-directive>` directive.
 
+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/exampleall_0.1.bb``::
+
+   include_all all.inc
+
+Where multiple ``all.inc`` are in located in ``/layers/meta-custom2`` and
+``/layers/meta-custom1``.
+
+And let's assume that the value of :term:`BBPATH` is
+``/layers/meta-custom1:/layers/meta-custom2``. Then BitBake will try to include
+all ``all.inc`` in this order::
+
+   /layers/meta-custom1/all.inc
+   /layers/meta-custom2/all.inc
+
+In this case the first ``/layers/meta-custom1/all.inc`` would be included, and
+then ``/layers/meta-custom2/all.inc`` if both are found.
+
+.. note::
+
+   The same logic as for the :ref:`ref-include-directive` applies, except that
+   the path relative to the file where the directive is specified is not
+   searched when using the ``include_all`` directive.
+
 Locating Class Files
 --------------------