From c0239ff8a8dcd9f43d522a7a1c60320bd0e5bb0c Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 7 Feb 2014 17:31:43 -0600 Subject: bitbake: user-manual-metadata.xml: General cleanup to "Parsing and Execution" I went through and created links for variables we reference that are in the glossary. I also re-wrote much of the text to just clean it up. (Bitbake rev: dd9a4422d387da45f6de945eb4944c2a06bc98a0) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- bitbake/doc/user-manual/user-manual-metadata.xml | 260 ++++++++++++++--------- 1 file changed, 164 insertions(+), 96 deletions(-) (limited to 'bitbake/doc/user-manual/user-manual-metadata.xml') 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. + + + +
+ Recipe (<filename>.bb</filename>) Files + + + 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.
-
- <filename>.bb</filename> Files +
+ 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). + - 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. + Information in append files overrides the information in the + similarly-named recipe file.
-- cgit v1.2.3-54-g00ecf