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 +~~~~~~~~~~~ - 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. +BitBake supports class files installed in three different directories: - 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. +- ``classes-global/``: these classes must be inherited globally through the + :term:`INHERIT` variable in a :ref:`configuration file + `. 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 ` directive. They do + not support being inherited globally. For example, you would use the recipe + class named ``myclass`` like so:: + + inherit myclass + +- ``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. + +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 +` and :ref:`require ` 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 ` 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 ` 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 ` and +:ref:`require ` directives, BitBake stops and inherits the +first class that it finds. + +For classes inherited with the :ref:`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 =========