diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 9f172d4e65..ab3dcb19e4 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -1040,41 +1040,36 @@
Parsing Overview
- BitBake parses configuration files, classes, and
- .bb files.
+ BitBake parses configuration files, classes, recipes, and append
+ files.
The first thing BitBake does is look for the
bitbake.conf file.
- This file resides in the within the conf/
- directory.
- BitBake finds it by examining its BBPATH
- environment variable and looking for the
- conf/ directory.
+ This file resides in the conf
+ directory, which must be listed in
+ BBPATH.
The bitbake.conf file lists other configuration
- files to include from a conf/ directory below the
+ files to include from the conf directory below the
directories listed in BBPATH.
- In general, the most important configuration file from a user's perspective
- is local.conf, which contains a user's
+ In general, the most important of these
+ configuration files from a user's perspective
+ is local.conf, which contains the user's
customized settings for the build environment.
+
+
+
Other notable configuration files are the distribution configuration
- file (set by the DISTRO variable) and the machine
- configuration file (set by the MACHINE variable).
- The DISTRO and MACHINE BitBake
- environment variables are both usually set in the
- local.conf file.
- Valid distribution configuration files are available
- in the conf/distro/ directory and valid machine
- configuration files in the meta/conf/machine/
- directory.
- Within the conf/machine/include/ directory are
- various tune-*.inc configuration files
- that provide common "tuning" settings specific to and shared between
- particular architectures and machines.
+ file and the machine configuration file.
+ These configuration files are normally identified by
+ variables unique to the build systems using BitBake.
+ For example, the Yocto Project uses the
+ DISTRO and MACHINE
+ variables, respectively.
@@ -1083,8 +1078,9 @@
The base.bbclass file
is always included.
Other classes that are specified in the configuration using the
- INHERIT variable are also included.
- Class files are searched for in a classes subdirectory under
+ INHERIT
+ variable are also included.
+ BitBake searches for class files in a "classes" subdirectory under
the paths in BBPATH in the same way as
configuration files.
@@ -1093,29 +1089,28 @@
After classes are included, the variable
BBFILES is set, usually in
local.conf, and defines the list of
- places to search for .bb files.
+ places to search for recipe and append files.
Adding extra content to BBFILES is best
- achieved through the use of BitBake layers as described in the
- Layers section below.
+ achieved through the use of BitBake layers.
- BitBake parses each .bb file in
+ BitBake parses each recipe and append file located with
BBFILES and stores the values of various
- variables.
- In summary, for each .bb file the configuration
+ variables into the datastore.
+ In summary, for each recipe and append file pairing, the configuration
plus the base class of variables are set, followed by the data in the
- .bb file itself, followed by any inherit commands
- that .bb file might contain.
+ recipe file itself, followed by any inherit commands
+ that the recipe file might contain.
- Because parsing .bb files is a time consuming
- process, a cache is kept to speed up subsequent parsing.
- This cache is invalid if the timestamp of the
- .bb file itself changes, or if the timestamps of
- any of the include, configuration files or class files on which
- the .bb file depends change.
+ Because parsing recipe and append files is a time consuming
+ process, a cache, referred to as the "setscene"
+ is kept to speed up subsequent parsing.
+ The setscene is invalid if the timestamps of a recipe changes,
+ any of the include files change, configuration files change,
+ or class files on which the recipe file depends change.
@@ -1126,12 +1121,12 @@
Prior to parsing configuration files, Bitbake looks
at certain variables, including:
- BB-ENV-WHITELIST
- BB_PRESERVE-ENV
- BB_ENV_EXTRAWHITE
- BB_ORIG_ENV
- PREFERRED_VERSIONS
- PREFERRED_PROVIDERS
+ BB_ENV_WHITELIST
+ BB_PRESERVE_ENV
+ BB_ENV_EXTRAWHITE
+ BB_ORIGENV
+ PREFERRED_VERSION
+ PREFERRED_PROVIDERS
@@ -1144,13 +1139,15 @@
BitBake will first search the current working directory for an
optional conf/bblayers.conf configuration file.
- This file is expected to contain a BBLAYERS
+ This file is expected to contain a
+ BBLAYERS
variable that is a space delimited list of 'layer' directories.
For each directory in this list, a conf/layer.conf
file will be searched for and parsed with the
- LAYERDIR variable being set to the directory where
- the layer was found.
- The idea is these files will setup BBPATH
+ LAYERDIR
+ variable being set to the directory where the layer was found.
+ The idea is these files will setup
+ BBPATH
and other variables correctly for a given build directory automatically
for the user.
@@ -1168,22 +1165,54 @@
in .conf files.
The following variables include:
- BITBAKE_UI
- BBDEBUG
- MULTI_PROVIDER_WHITELIST
- BB_NUMBER_PARSE_THREADS
- BBPKGS
- BB_DEFAULT_TASK
- TOPDIR
- BB_VERBOSE_LOGS
- BB_NICE_LEVEL
- BBFILE_COLLECTIONS
- ASSUME_PROVIDED
- BB_DANGLINGAPPENDS_WARNONLY
- BBINCLUDED
- BBFILE_PRIORITY
- BUILDNAME
- BBMASK
+
+ BITBAKE_UI
+
+
+ BBDEBUG
+
+
+ MULTI_PROVIDER_WHITELIST
+
+
+ BB_NUMBER_PARSE_THREADS
+
+
+ BBPKGS
+
+
+ BB_DEFAULT_TASK
+
+
+ TOPDIR
+
+
+ BB_VERBOSE_LOGS
+
+
+ BB_NICE_LEVEL
+
+
+ BBFILE_COLLECTIONS
+
+
+ ASSUME_PROVIDED
+
+
+ BB_DANGLINGAPPENDS_WARNONLY
+
+
+ BBINCLUDED
+
+
+ BBFILE_PRIORITY
+
+
+ BUILDNAME
+
+
+ BBMASK
+
@@ -1193,36 +1222,38 @@
Layers allow you to isolate different types of
customizations from each other.
- You might find it tempting to keep everything in one layer
- when working on a single project.
- However, the more modular you organize your Metadata, the
- easier it is to cope with future changes.
+ While you might find it tempting to keep everything in one layer
+ when working on a single project, the more modular you organize
+ your metadata, the easier it is to cope with future changes.
- To illustrate how layers are used to keep things modular,
+ To illustrate how you can use layers to keep things modular,
consider machine customizations.
These types of customizations typically reside in a special layer,
rather than a general layer, called a Board Specific Package (BSP) Layer.
Furthermore, the machine customizations should be isolated from
- recipes and Metadata that support a new GUI environment, for
+ recipes and metadata that support a new GUI environment, for
example.
This situation gives you a couple of layers: one for the machine
- configurations, and one for the GUI environment.
+ configurations and one for the GUI environment.
It is important to understand, however, that the BSP layer can still
make machine-specific additions to recipes within
the GUI environment layer without polluting the GUI layer itself
with those machine-specific changes.
You can accomplish this through a recipe that is a BitBake append
- (.bbappend) file, which is described
- later in this section.
+ (.bbappend) file.
- There are certain variable specific to layers, including:
+ There are certain variables specific to layers:
- LAYERDEPENDS
- LAYERVERSION
+
+ LAYERDEPENDS
+
+
+ LAYERVERSION
+
@@ -1231,11 +1262,14 @@
Schedulers
- There are variables specific to scheduling functionality
- including:
+ Variables specific to scheduling functionality exist:
- BB_SCHEDULER
- BB_SCHEDULERS
+
+ BB_SCHEDULER
+
+
+ BB_SCHEDULERS
+
@@ -1245,26 +1279,60 @@
Classes
- BitBake classes are our rudimentary inheritance mechanism.
- As briefly mentioned in the metadata introduction, they're
- parsed when an inherit directive is encountered, and they
- are located in the classes/ directory
- relative to the directories in BBPATH.
+ BitBake's rudimentary inheritance mechanism is accomplished using
+ classes.
+ As briefly mentioned in the metadata introduction, BitBake
+ parses a class when an inherit directive is encountered, and it
+ is located in the classes directory
+ relative to the directories in
+ BBPATH.
-
- <filename>.bb</filename> Files
+
+ Recipe (<filename>.bb</filename>) Files
- A BitBake (.bb) file is a logical unit
- of tasks to be executed.
- Normally this is a package to be built.
- Inter-.bb dependencies are obeyed.
- The files themselves are located via the
- BBFILES variable, which
- is set to a space separated list of .bb
- files, and does handle wildcards.
+ Recipe files, which are files that have the
+ .bb file extension, are logical units of
+ tasks for execution.
+ Normally, that logical unit is a package that needs to be
+ built.
+
+
+
+ BitBake obeys all inter-recipe dependencies.
+
+
+
+ Recipe files must reside in locations found in the
+ BBFILES
+ variable.
+
+
+
+
+ Append (<filename>.bbappend</filename>) Files
+
+
+ Append files, which are files that have the
+ .bbappend file extension, add or
+ extend build information to an existing
+ recipe file.
+
+
+
+ BitBake expects every append file to have a corresponding recipe file.
+ Furthermore, the append file and corresponding recipe file
+ must use the same root filename.
+ The filenames can differ only in the file type suffix used
+ (e.g. formfactor_0.0.bb and
+ formfactor_0.0.bbappend).
+
+
+
+ Information in append files overrides the information in the
+ similarly-named recipe file.