From 6003a9615dc4cc8b02912815a3d785299d01fe25 Mon Sep 17 00:00:00 2001 From: "Robert P. J. Day" Date: Wed, 9 Jul 2025 14:16:54 -0400 Subject: [PATCH] bitbake: bitbake: clarify significance of "include_all" directive Rewrite the include and include_all sections to drive home the fact that the include_all directive is relevant in only very specific cases, and not something developers should expect to use in normal operation. (Bitbake rev: 4b3bfe70d02cc1c11972357e2dc595acc75056e5) Signed-off-by: Robert P. J. Day Signed-off-by: Richard Purdie --- .../bitbake-user-manual-metadata.rst | 67 +++++++++++-------- 1 file changed, 38 insertions(+), 29 deletions(-) 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 f60a9d8312..1042c65d89 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst @@ -874,58 +874,67 @@ becomes a no-op. ``include`` Directive --------------------- -BitBake understands the ``include`` directive. This directive causes -BitBake to parse whatever file you specify, and to insert that file at -that location. The directive is much like its equivalent in Make except -that if the path specified on the include line is a relative path, -BitBake locates the first file it can find within :term:`BBPATH`. +The ``include`` directive causes BitBake to parse a given file, +and to include that file's contents at the location of the +``include`` statement. This directive is similar to its equivalent +in Make, except that if the path specified on the BitBake ``include`` +line is a relative path, BitBake will search for it on the path designated +by :term:`BBPATH` and will include *only the first matching file*. -The include directive is a more generic method of including +The ``include`` directive is a more generic method of including functionality as compared to the :ref:`inherit ` directive, which is restricted to class (i.e. ``.bbclass``) files. The -include directive is applicable for any other kind of shared or +``include`` directive is applicable for any other kind of shared or encapsulated functionality or configuration that does not suit a ``.bbclass`` file. -As an example, suppose you needed a recipe to include some self-test -definitions:: +For example, if you needed a recipe to include some self-test definitions, +you might write:: include test_defs.inc +The ``include`` directive does not produce an error if the specified file +cannot be found. If the included file *must* exist, then you should use +use :ref:`require ` instead, which will generate an error +if the file cannot be found. + .. note:: - The include directive does not produce an error when the file cannot be - found. Consequently, it is recommended that if the file you are including is - expected to exist, you should use :ref:`require ` instead - of include . Doing so makes sure that an error is produced if the file cannot - be found. + Note well that the ``include`` directive will include the first matching + file and nothing further (which is almost always the behaviour you want). + If you need to include all matching files, you need to use the + ``include_all`` directive, explained below. ``include_all`` Directive ------------------------- The ``include_all`` directive works like the :ref:`include ` -directive but will include all of the files that match the specified path in +directive but will include *all* of the files that match the specified path in the enabled layers (layers part of :term:`BBLAYERS`). -For example, let's say a ``maintainers.inc`` file is present in different layers -and is conventionally placed in the ``conf/distro/include`` directory of each -layer. In that case the ``include_all`` directive can be used to include -the ``maintainers.inc`` file for all of these layers:: +.. note:: + + This behaviour is rarely what you want in normal operation, and should + be reserved for only those situations when you explicitly want to parse + and include all matching files found across all layers, as the following + example shows. + +As a realistic example of this directive, imagine that all of your active +layers contain a file ``conf/distro/include/maintainers.inc``, containing +maintainer information for the recipes in that layer, and you wanted to +collect all of the content from all of those files across all of those layers. +You could use the statement:: include_all conf/distro/include/maintainers.inc -In other words, the ``maintainers.inc`` file for each layer is included through -the :ref:`include ` -directive. +In this case, BitBake will iterate through all of the directories in +the colon-separated :term:`BBPATH` (from left to right) and collect the +contents of all matching files, so you end up with the maintainer +information of all of your active layers, not just the first one. -BitBake will iterate through the colon-separated :term:`BBPATH` list to look for -matching files to include, from left to right. As a consequence, matching files -are included in that order. - -As the ``include_all`` directive uses the :ref:`include -` -directive in the background, no error is produced if no files are matched. +As the ``include_all`` directive uses the ``include`` directive in the +background, as with ``include``, no error is produced if no files are matched. .. _require-inclusion: