3 files changed, 131 insertions, 29 deletions

diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
index d58fbb32ea..d407f59c0d 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
+++ b/bitbake/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/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
index d941e212bf..9837b009ea 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
+++ b/bitbake/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/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 9d4f426bf7..4dadf0bc7b 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/bitbake/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
 =========