[PATCH 0/8] doc: bitbake-user-manual-metadata: misc improvements on sharing functionality

[PATCH 0/8] doc: bitbake-user-manual-metadata: misc improvements on sharing functionality

[Quentin Schulz]

This expands on the include_all directive by providing an example and
highlighting the difference with the include directive.

It fixes some highlighting and cross-referencing inconsistencies as well
as the wrong path in the examples.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
Quentin Schulz (8):
      doc: bitbake-user-manual-metadata: list (in order) all sharing directives
      doc: bitbake-user-manual-metadata: highlight configuration fragment differently
      doc: bitbake-user-manual-metadata: use a cross-reference for addfragments
      doc: bitbake-user-manual-metadata: specify that current dir won't be searched for include_all
      doc: bitbake-user-manual-metadata: add missing highlight for BBPATH and PATH
      doc: bitbake-user-manual-metadata: fix incorrect path in example for locating files
      doc: bitbake-user-manual-metadata: expand on search paths for include directive
      doc: bitbake-user-manual-metadata: expand locating files example for include_all directive

 .../bitbake-user-manual-metadata.rst               | 65 ++++++++++++++++++----
 1 file changed, 54 insertions(+), 11 deletions(-)
---
base-commit: f23e186a75e71ba885b9b53a1dfda99af29c67b0
change-id: 20260112-doc-directives-6e42bc047525

Best regards,
-- 
Quentin Schulz <quentin.schulz@cherry.de>

[PATCH 1/8] doc: bitbake-user-manual-metadata: list (in order) all sharing directives

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

The Sharing Functionality section has multiple subsections each
representing a way to share code.

Let's list all directives listed in the subsections (we were missing
inherit_defer and include_all) and provide a link for each subsection.

This also fixes the link to INHERIT to point to the subsection where it
is explained instead of to the variable glossary.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index ef401d4ab..0c5466943 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -753,7 +753,12 @@ share the task.
 
 This section presents the mechanisms BitBake provides to allow you to
 share functionality between recipes. Specifically, the mechanisms
-include ``include``, ``inherit``, :term:`INHERIT`, and ``require``
+include :ref:`inherit<ref-bitbake-user-manual-metadata-inherit>`,
+:ref:`inherit_defer<ref-bitbake-user-manual-metadata-inherit-defer>`,
+:ref:`include<ref-include-directive>`,
+:ref:`include_all<ref-include-all-directive>`,
+:ref:`require<require-inclusion>` and
+:ref:`INHERIT<bitbake-user-manual/bitbake-user-manual-metadata:\`\`INHERIT\`\` configuration directive>`
 directives. There is also a higher-level abstraction called
 ``configuration fragments`` that is enabled with ``addfragments``
 directive.

-- 
2.52.0

[PATCH 2/8] doc: bitbake-user-manual-metadata: highlight configuration fragment differently

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

We typically reserve the monospace font (used when highlighting with two
tick quotes) for inline code examples or non-English words, but
"configuration fragments" is neither. Instead, let's assume the intended
style effect was to highlight the term as a two-word term and only use
single tick quotes to make the text look italic.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 0c5466943..3ac2cb755 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -760,7 +760,7 @@ include :ref:`inherit<ref-bitbake-user-manual-metadata-inherit>`,
 :ref:`require<require-inclusion>` and
 :ref:`INHERIT<bitbake-user-manual/bitbake-user-manual-metadata:\`\`INHERIT\`\` configuration directive>`
 directives. There is also a higher-level abstraction called
-``configuration fragments`` that is enabled with ``addfragments``
+`configuration fragments` that is enabled with ``addfragments``
 directive.
 
 .. _ref-bitbake-user-manual-metadata-inherit:

-- 
2.52.0

[PATCH 3/8] doc: bitbake-user-manual-metadata: use a cross-reference for addfragments

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

We use cross-reference links for all but addfragments so let's fix that
inconsistency.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 3ac2cb755..9233c4555 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -760,8 +760,8 @@ include :ref:`inherit<ref-bitbake-user-manual-metadata-inherit>`,
 :ref:`require<require-inclusion>` and
 :ref:`INHERIT<bitbake-user-manual/bitbake-user-manual-metadata:\`\`INHERIT\`\` configuration directive>`
 directives. There is also a higher-level abstraction called
-`configuration fragments` that is enabled with ``addfragments``
-directive.
+`configuration fragments` that is enabled with the
+:ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`addfragments\`\` directive`.
 
 .. _ref-bitbake-user-manual-metadata-inherit:
 

-- 
2.52.0

[PATCH 4/8] doc: bitbake-user-manual-metadata: specify that current dir won't be searched for include_all

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

We've forgotten to make it explicit that include_all differs from the
include directive also by the fact it doesn't look for the file
relatively to the file with the include_all directive, so let's make
that clear.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 9233c4555..d7335f29e 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -910,6 +910,10 @@ The ``include_all`` directive works like the :ref:`include
 directive but will include *all* of the files that match the specified path in
 the enabled layers (layers part of :term:`BBLAYERS`).
 
+Note that only :term:`BBPATH` will be searched, the parent directory of the file
+with the ``include_all`` directive will not be searched (unlike for the
+``include`` directive).
+
 .. note::
 
    This behaviour is rarely what you want in normal operation, and should

-- 
2.52.0

[PATCH 5/8] doc: bitbake-user-manual-metadata: add missing highlight for BBPATH and PATH

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

We typically highlight (via a :term: directive or with double tick
quotes if there's no entry in the glossary or it is inappropriate)
variables, and here it was missed so let's fix that oversight.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index d7335f29e..44a1e519b 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -1070,7 +1070,7 @@ BitBake also uses the :term:`BBPATH` variable.
 
 .. note::
 
-   The BBPATH variable is analogous to the environment variable PATH.
+   The :term:`BBPATH` variable is analogous to the environment variable ``PATH``.
 
 For these two directives, BitBake includes the first file it finds.
 

-- 
2.52.0

[PATCH 6/8] doc: bitbake-user-manual-metadata: fix incorrect path in example for locating files

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

The paths listed in the example are missing an "example" subdirectory to
match the searched paths in the example, let's fix this oversight.

Fixes: 7bd36f6c6d33 ("doc: extend classes and include/require documentation")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 44a1e519b..719689150 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -1080,11 +1080,11 @@ For these two directives, BitBake includes the first file it finds.
    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``::
+``/layers/meta-custom2/recipes-example/example/example_0.1.bb``::
 
    require myfile.inc
 
-Where ``myfile.inc`` is located in ``/layers/meta-custom2/recipes-example/``.
+Where ``myfile.inc`` is located in ``/layers/meta-custom2/recipes-example/example``.
 
 And let's assume that the value of :term:`BBPATH` is
 ``/layers/meta-custom1:/layers/meta-custom2``. Then BitBake will try to find

-- 
2.52.0

[PATCH 7/8] doc: bitbake-user-manual-metadata: expand on search paths for include directive

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

While it is made somewhat explicit in the require and include directive
sections, I believe we should provide an example as to which relative
directory the include/require directives apply to when in a bbappend.

Let's provide some example to make this even clearer as it wasn't what I
thought would happen.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 719689150..cbad4df99 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -1112,6 +1112,18 @@ In this case, the following paths would be searched::
 
 This time, the second item of this list would be matched.
 
+Note that the first path is based on the location of the file with the
+``require`` (or ``include``) directive. Imagine there's a
+``/layers/meta-custom2/recipes-bbappend/example/example_0.1.bbappend`` with::
+
+   require myappend.inc
+
+In this case, the following paths would be searched::
+
+   /layers/meta-custom2/recipes-bbappend/example/myappend.inc
+   /layers/meta-custom1/myappend.inc
+   /layers/meta-custom2/myappend.inc
+
 .. note::
 
    In the above examples, the exact same search order applies for the

-- 
2.52.0

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

[Quentin Schulz]

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

-- 
2.52.0

Re: [bitbake-devel] [PATCH 0/8] doc: bitbake-user-manual-metadata: misc improvements on sharing functionality

[Antonin Godard]

On Mon Jan 12, 2026 at 5:36 PM CET, Quentin Schulz wrote:
> This expands on the include_all directive by providing an example and
> highlighting the difference with the include directive.
>
> It fixes some highlighting and cross-referencing inconsistencies as well
> as the wrong path in the examples.
>
> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
> ---
> Quentin Schulz (8):
>       doc: bitbake-user-manual-metadata: list (in order) all sharing directives
>       doc: bitbake-user-manual-metadata: highlight configuration fragment differently
>       doc: bitbake-user-manual-metadata: use a cross-reference for addfragments
>       doc: bitbake-user-manual-metadata: specify that current dir won't be searched for include_all
>       doc: bitbake-user-manual-metadata: add missing highlight for BBPATH and PATH
>       doc: bitbake-user-manual-metadata: fix incorrect path in example for locating files
>       doc: bitbake-user-manual-metadata: expand on search paths for include directive
>       doc: bitbake-user-manual-metadata: expand locating files example for include_all directive
>
>  .../bitbake-user-manual-metadata.rst               | 65 ++++++++++++++++++----
>  1 file changed, 54 insertions(+), 11 deletions(-)
> ---
> base-commit: f23e186a75e71ba885b9b53a1dfda99af29c67b0
> change-id: 20260112-doc-directives-6e42bc047525
>
> Best regards,

Great improvements over what I wrote a while back! I'm glad we have a detailed
explanation on all of these directives now.

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

Thanks!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com