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

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

[Antonin Godard]

The current documentation is lacking details on the different kinds of
directories for putting classes as well as the order in which BitBake
includes files (classes or include files).

This patch does the following changes:

- Mention the missing classes-recipe and classes-global when applicable.
- Add a Class Types section detailed the three different directories for
  putting classes.
- Move the existing section on locating classes/include files below the
  documentation on the different directives (include/require/inherit).
- Extend the documentation on locating files with include/require and
  inherit to give proper examples, hopefully demystifying this
  mechanism a bit.

[YOCTO #15724]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 .../bitbake-user-manual-execution.rst              |  10 +-
 .../bitbake-user-manual-intro.rst                  |  34 ++++--
 .../bitbake-user-manual-metadata.rst               | 116 ++++++++++++++++++---
 3 files changed, 131 insertions(+), 29 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
index d58fbb32ea..d407f59c0d 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
@@ -64,11 +64,11 @@ data itself is of various types:
    together.
 
 The ``layer.conf`` files are used to construct key variables such as
-:term:`BBPATH` and :term:`BBFILES`.
-:term:`BBPATH` is used to search for configuration and class files under the
-``conf`` and ``classes`` directories, respectively. :term:`BBFILES` is used
-to locate both recipe and recipe append files (``.bb`` and
-``.bbappend``). If there is no ``bblayers.conf`` file, it is assumed the
+:term:`BBPATH` and :term:`BBFILES`. :term:`BBPATH` is used to search for
+configuration files under the ``conf`` directory and class files under the
+``classes-global``, ``classes-recipe`` and ``classes`` directories.
+:term:`BBFILES` is used to locate both recipe and recipe append files (``.bb``
+and ``.bbappend``). If there is no ``bblayers.conf`` file, it is assumed the
 user has set the :term:`BBPATH` and :term:`BBFILES` directly in the environment.
 
 Next, the ``bitbake.conf`` file is located using the :term:`BBPATH` variable
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
index d941e212bf..9837b009ea 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
@@ -206,17 +206,33 @@ installing (empty by default) and packaging (empty by default). These
 tasks are often overridden or extended by other classes added during the
 project development process.
 
-.. note::
+Class Types
+~~~~~~~~~~~
+
+BitBake supports class files installed in three different directories:
+
+-  ``classes-global/``: these classes must be inherited globally through the
+   :term:`INHERIT` variable in a :ref:`configuration file
+   <bitbake-user-manual/bitbake-user-manual-intro:Configuration Files>`.  These
+   classes are included for every recipe being built. For example, you would use
+   the global class named ``myclass`` like so::
+
+      INHERIT += "myclass"
+
+-  ``classes-recipe/``: these classes must be inherited from a recipe using the
+   :ref:`inherit <ref-bitbake-user-manual-metadata-inherit>` directive. They do
+   not support being inherited globally. For example, you would use the recipe
+   class named ``myclass`` like so::
+
+      inherit myclass
 
-   While BitBake comes with just the one ``base.bbclass`` file in the
-   ``classes`` directory, it supports class files also being installed
-   in related directories ``classes-global`` and ``classes-recipe`` and
-   will automatically search all three directories for a selected class
-   file.
+-  ``classes/``: this final directory is meant for classes that can be used in
+   the two contexts explain above. In other words, they can be inherit either
+   globally or in a recipe.
 
-   This means that, in this documentation, when you see a reference to
-   class files being in the ``classes`` directory, you can interpret that
-   as meaning in any one of the above three directories.
+For details on how BitBake locates class files, see the
+:ref:`bitbake-user-manual/bitbake-user-manual-metadata:Locating Class Files`
+section of the Bitbake User Manual.
 
 Layers
 ------
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 9d4f426bf7..4dadf0bc7b 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -758,21 +758,6 @@ directives. There is also a higher-level abstraction called
 ``configuration fragments`` that is enabled with ``addfragments``
 directive.
 
-Locating Include and Class Files
---------------------------------
-
-BitBake uses the :term:`BBPATH` variable to locate
-needed include and class files. Additionally, BitBake searches the
-current directory for ``include`` and ``require`` directives.
-
-.. note::
-
-   The BBPATH variable is analogous to the environment variable PATH .
-
-In order for include and class files to be found by BitBake, they need
-to be located in a "classes" subdirectory that can be found in
-:term:`BBPATH`.
-
 .. _ref-bitbake-user-manual-metadata-inherit:
 
 ``inherit`` Directive
@@ -874,6 +859,8 @@ becomes a no-op.
 See also :term:`BB_DEFER_BBCLASSES` for automatically promoting classes
 ``inherit`` calls to ``inherit_defer``.
 
+.. _ref-include-directive:
+
 ``include`` Directive
 ---------------------
 
@@ -908,6 +895,8 @@ if the file cannot be found.
    If you need to include all matching files, you need to use the
    ``include_all`` directive, explained below.
 
+.. _ref-include-all-directive:
+
 ``include_all`` Directive
 -------------------------
 
@@ -1062,6 +1051,103 @@ bitbake will treat that as direct value assignment in its configuration::
 
   SOMEVARIABLE = "somevalue"
 
+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
+
+This time, the second item of this list would be matched.
+
+.. note::
+
+   In the above examples, the exact same search order applies for the
+   :ref:`include <ref-include-directive>` directive.
+
+Locating Class Files
+--------------------
+
+Like include files, class files are located using the :term:`BBPATH` variable.
+The classes can be included in the ``classes-recipe``, ``classes-global`` and
+``classes`` directories, as explained in the
+:ref:`bitbake-user-manual/bitbake-user-manual-intro:Class types` section of the
+Bitbake User Manual. Like for the :ref:`include <ref-include-directive>` and
+:ref:`require <require-inclusion>` directives, BitBake stops and inherits the
+first class that it finds.
+
+For classes inherited with the :ref:`inherit
+<ref-bitbake-user-manual-metadata-inherit>` directive, BitBake will try to
+locate the class under each ``classes-recipe`` directory for each path in
+:term:`BBPATH`, and then do the same for each ``classes`` directory for each
+path in :term:`BBPATH`.
+
+For example, if the value :term:`BBPATH` is
+``/layers/meta-custom1:/layers/meta-custom2`` then the ``hello`` class
+would be searched in this order::
+
+   /layers/meta-custom1/classes-recipe/hello.bbclass
+   /layers/meta-custom2/classes-recipe/hello.bbclass
+   /layers/meta-custom1/classes/hello.bbclass
+   /layers/meta-custom2/classes/hello.bbclass
+
+.. note::
+
+   Note that the order of the list above does not depend on where the class in
+   inherited from.
+
+Likewise, for classes inherited with the :term:`INHERIT` variable, the
+``classes-global`` directory is searched first, and the ``classes`` directory is
+searched second. Taking the above example, this would result in the following
+list::
+
+   /layers/meta-custom1/classes-global/hello.bbclass
+   /layers/meta-custom2/classes-global/hello.bbclass
+   /layers/meta-custom1/classes/hello.bbclass
+   /layers/meta-custom2/classes/hello.bbclass
+
 Functions
 =========
 

---
base-commit: 546b347b4d3d82c01ecc99f45296f66e44638adc
change-id: 20250917-classes-order-d4d9ae602a8f

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

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

[Quentin Schulz]

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

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

[Antonin Godard]

Hi,

On Wed Dec 3, 2025 at 5:55 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
[...]
> 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?

That's a good point I forgot here, yes, we should explain it to be complete.
Can you send a patch of file a bug?

Thanks,
Antonin

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

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

[Quentin Schulz]

Hi Antonin,

On 12/4/25 2:16 PM, Antonin Godard wrote:
> Hi,
> 
> On Wed Dec 3, 2025 at 5:55 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> [...]
>> 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?
> 
> That's a good point I forgot here, yes, we should explain it to be complete.
> Can you send a patch of file a bug?
> 

Finally took the time to write a patch, see

https://lore.kernel.org/yocto-docs/20260112-doc-directives-v1-8-b23923cfce89@cherry.de/

Cheers,
Quentin