diff options
author | 2014-02-07 17:31:43 -0600 | |
---|---|---|
committer | 2014-03-09 18:59:01 -0700 | |
commit | c0239ff8a8dcd9f43d522a7a1c60320bd0e5bb0c (patch) | |
tree | d76d79be503b9406da0635de7a8b167e1697a492 /bitbake | |
parent | 80127f433a90252ec6c376321b3c9b444bc55e74 (diff) | |
download | openembedded-core-contrib-c0239ff8a8dcd9f43d522a7a1c60320bd0e5bb0c.tar.gz |
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 <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake')
-rw-r--r-- | bitbake/doc/user-manual/user-manual-metadata.xml | 260 |
1 files changed, 164 insertions, 96 deletions
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 @@ <title>Parsing Overview</title> <para> - BitBake parses configuration files, classes, and - <filename>.bb</filename> files. + BitBake parses configuration files, classes, recipes, and append + files. </para> <para> The first thing BitBake does is look for the <filename>bitbake.conf</filename> file. - This file resides in the within the <filename>conf/</filename> - directory. - BitBake finds it by examining its <filename>BBPATH</filename> - environment variable and looking for the - <filename>conf/</filename> directory. + This file resides in the <filename>conf</filename> + directory, which must be listed in + <link linkend='var-BBPATH'><filename>BBPATH</filename></link>. </para> <para> The <filename>bitbake.conf</filename> file lists other configuration - files to include from a <filename>conf/</filename> directory below the + files to include from the <filename>conf</filename> directory below the directories listed in <filename>BBPATH</filename>. - In general, the most important configuration file from a user's perspective - is <filename>local.conf</filename>, which contains a user's + In general, the most important of these + configuration files from a user's perspective + is <filename>local.conf</filename>, which contains the user's customized settings for the build environment. + </para> + + <para> Other notable configuration files are the distribution configuration - file (set by the <filename>DISTRO</filename> variable) and the machine - configuration file (set by the <filename>MACHINE</filename> variable). - The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake - environment variables are both usually set in the - <filename>local.conf file</filename>. - Valid distribution configuration files are available - in the <filename>conf/distro/</filename> directory and valid machine - configuration files in the <filename>meta/conf/machine/</filename> - directory. - Within the <filename>conf/machine/include/</filename> directory are - various <filename>tune-*.inc</filename> 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 + <filename>DISTRO</filename> and <filename>MACHINE</filename> + variables, respectively. </para> <para> @@ -1083,8 +1078,9 @@ The <filename>base.bbclass</filename> file is always included. Other classes that are specified in the configuration using the - <filename>INHERIT</filename> variable are also included. - Class files are searched for in a classes subdirectory under + <link linkend='var-INHERIT'><filename>INHERIT</filename></link> + variable are also included. + BitBake searches for class files in a "classes" subdirectory under the paths in <filename>BBPATH</filename> in the same way as configuration files. </para> @@ -1093,29 +1089,28 @@ After classes are included, the variable <filename>BBFILES</filename> is set, usually in <filename>local.conf</filename>, and defines the list of - places to search for <filename>.bb</filename> files. + places to search for recipe and append files. Adding extra content to <filename>BBFILES</filename> is best - achieved through the use of BitBake layers as described in the - Layers section below. + achieved through the use of BitBake layers. </para> <para> - BitBake parses each <filename>.bb</filename> file in + BitBake parses each recipe and append file located with <filename>BBFILES</filename> and stores the values of various - variables. - In summary, for each <filename>.bb</filename> 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 - <filename>.bb</filename> file itself, followed by any inherit commands - that <filename>.bb</filename> file might contain. + recipe file itself, followed by any inherit commands + that the recipe file might contain. </para> <para> - Because parsing <filename>.bb</filename> files is a time consuming - process, a cache is kept to speed up subsequent parsing. - This cache is invalid if the timestamp of the - <filename>.bb</filename> file itself changes, or if the timestamps of - any of the include, configuration files or class files on which - the <filename>.bb</filename> 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. </para> </section> @@ -1126,12 +1121,12 @@ Prior to parsing configuration files, Bitbake looks at certain variables, including: <itemizedlist> - <listitem><para><filename>BB-ENV-WHITELIST</filename></para></listitem> - <listitem><para><filename>BB_PRESERVE-ENV</filename></para></listitem> - <listitem><para><filename>BB_ENV_EXTRAWHITE</filename></para></listitem> - <listitem><para><filename>BB_ORIG_ENV</filename></para></listitem> - <listitem><para><filename>PREFERRED_VERSIONS</filename></para></listitem> - <listitem><para><filename>PREFERRED_PROVIDERS</filename></para></listitem> + <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem> + <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem> + <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem> + <listitem><para><link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link></para></listitem> + <listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem> + <listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem> </itemizedlist> </para> @@ -1144,13 +1139,15 @@ <para> BitBake will first search the current working directory for an optional <filename>conf/bblayers.conf</filename> configuration file. - This file is expected to contain a <filename>BBLAYERS</filename> + This file is expected to contain a + <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> variable that is a space delimited list of 'layer' directories. For each directory in this list, a <filename>conf/layer.conf</filename> file will be searched for and parsed with the - <filename>LAYERDIR</filename> variable being set to the directory where - the layer was found. - The idea is these files will setup <filename>BBPATH</filename> + <link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link> + variable being set to the directory where the layer was found. + The idea is these files will setup + <link linkend='var-BBPATH'><filename>BBPATH</filename></link> and other variables correctly for a given build directory automatically for the user. </para> @@ -1168,22 +1165,54 @@ in <filename>.conf</filename> files. The following variables include: <itemizedlist> - <listitem><para><filename>BITBAKE_UI</filename></para></listitem> - <listitem><para><filename>BBDEBUG</filename></para></listitem> - <listitem><para><filename>MULTI_PROVIDER_WHITELIST</filename></para></listitem> - <listitem><para><filename>BB_NUMBER_PARSE_THREADS</filename></para></listitem> - <listitem><para><filename>BBPKGS</filename></para></listitem> - <listitem><para><filename>BB_DEFAULT_TASK</filename></para></listitem> - <listitem><para><filename>TOPDIR</filename></para></listitem> - <listitem><para><filename>BB_VERBOSE_LOGS</filename></para></listitem> - <listitem><para><filename>BB_NICE_LEVEL</filename></para></listitem> - <listitem><para><filename>BBFILE_COLLECTIONS</filename></para></listitem> - <listitem><para><filename>ASSUME_PROVIDED</filename></para></listitem> - <listitem><para><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></para></listitem> - <listitem><para><filename>BBINCLUDED</filename></para></listitem> - <listitem><para><filename>BBFILE_PRIORITY</filename></para></listitem> - <listitem><para><filename>BUILDNAME</filename></para></listitem> - <listitem><para><filename>BBMASK</filename></para></listitem> + <listitem><para> + <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-MULTI_PROVIDER_WHITELIST'><filename>MULTI_PROVIDER_WHITELIST</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></link> + </para></listitem> + <listitem><para> + <filename>BBPKGS</filename> + </para></listitem> + <listitem><para> + <link linkend='var-BB_DEFAULT_TASK'><filename>BB_DEFAULT_TASK</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BB_VERBOSE_LOGS'><filename>BB_VERBOSE_LOGS</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BB_NICE_LEVEL'><filename>BB_NICE_LEVEL</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BUILDNAME'><filename>BUILDNAME</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BBMASK'><filename>BBMASK</filename></link> + </para></listitem> </itemizedlist> </para> @@ -1193,36 +1222,38 @@ <para> 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. </para> <para> - 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 - (<filename>.bbappend</filename>) file, which is described - later in this section. + (<filename>.bbappend</filename>) file. </para> <para> - There are certain variable specific to layers, including: + There are certain variables specific to layers: <itemizedlist> - <listitem><para><filename>LAYERDEPENDS</filename></para></listitem> - <listitem><para><filename>LAYERVERSION</filename></para></listitem> + <listitem><para> + <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link> + </para></listitem> </itemizedlist> </para> </section> @@ -1231,11 +1262,14 @@ <title>Schedulers</title> <para> - There are variables specific to scheduling functionality - including: + Variables specific to scheduling functionality exist: <itemizedlist> - <listitem><para><filename>BB_SCHEDULER</filename></para></listitem> - <listitem><para><filename>BB_SCHEDULERS</filename></para></listitem> + <listitem><para> + <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link> + </para></listitem> + <listitem><para> + <link linkend='var-BB_SCHEDULERS'><filename>BB_SCHEDULERS</filename></link> + </para></listitem> </itemizedlist> </para> </section> @@ -1245,26 +1279,60 @@ <title>Classes</title> <para> - 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 <filename>classes/</filename> directory - relative to the directories in <filename>BBPATH</filename>. + 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 <filename>classes</filename> directory + relative to the directories in + <link linkend='var-BBPATH'><filename>BBPATH</filename></link>. + </para> + </section> + + <section id='recipe-bb-files'> + <title>Recipe (<filename>.bb</filename>) Files</title> + + <para> + Recipe files, which are files that have the + <filename>.bb</filename> file extension, are logical units of + tasks for execution. + Normally, that logical unit is a package that needs to be + built. + </para> + + <para> + BitBake obeys all inter-recipe dependencies. + </para> + + <para> + Recipe files must reside in locations found in the + <link linkend='var-BBFILES'><filename>BBFILES</filename></link> + variable. </para> </section> - <section id='bb-files'> - <title><filename>.bb</filename> Files</title> + <section id='append-bbappend-files'> + <title>Append (<filename>.bbappend</filename>) Files</title> + + <para> + Append files, which are files that have the + <filename>.bbappend</filename> file extension, add or + extend build information to an existing + <link linkend='recipe-bb-files'>recipe file</link>. + </para> + + <para> + 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. <filename>formfactor_0.0.bb</filename> and + <filename>formfactor_0.0.bbappend</filename>). + </para> <para> - A BitBake (<filename>.bb</filename>) file is a logical unit - of tasks to be executed. - Normally this is a package to be built. - Inter-<filename>.bb</filename> dependencies are obeyed. - The files themselves are located via the - <filename>BBFILES</filename> variable, which - is set to a space separated list of <filename>.bb</filename> - files, and does handle wildcards. + Information in append files overrides the information in the + similarly-named recipe file. </para> </section> </section> |