mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-31 12:49:46 +00:00
Code Issues Projects Releases Wiki Activity

bitbake: user-manual-metadata.xml: General cleanup to "Parsing and Execution"

Browse Source 
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>
This commit is contained in:
Scott Rifenbark
2014-02-07 17:31:43 -06:00
committed by Richard Purdie
parent 80127f433a
commit c0239ff8a8
1 changed files with 164 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bitbake/doc/user-manual/user-manual-metadata.xml
+164 -96
View File
@@ -1040,41 +1040,36 @@
<title>Parsing Overview</title> <title>Parsing Overview</title>
<para> <para>
BitBake parses configuration files, classes, and BitBake parses configuration files, classes, recipes, and append
<filename>.bb</filename> files. files.
</para> </para>
<para> <para>
The first thing BitBake does is look for the The first thing BitBake does is look for the
<filename>bitbake.conf</filename> file. <filename>bitbake.conf</filename> file.
This file resides in the within the <filename>conf/</filename> This file resides in the <filename>conf</filename>
directory. directory, which must be listed in
BitBake finds it by examining its <filename>BBPATH</filename> <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
environment variable and looking for the
<filename>conf/</filename> directory.
</para> </para>
<para> <para>
The <filename>bitbake.conf</filename> file lists other configuration 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>. directories listed in <filename>BBPATH</filename>.
In general, the most important configuration file from a user's perspective In general, the most important of these
is <filename>local.conf</filename>, which contains a user's configuration files from a user's perspective
is <filename>local.conf</filename>, which contains the user's
customized settings for the build environment. customized settings for the build environment.
</para>
<para>
Other notable configuration files are the distribution configuration Other notable configuration files are the distribution configuration
file (set by the <filename>DISTRO</filename> variable) and the machine file and the machine configuration file.
configuration file (set by the <filename>MACHINE</filename> variable). These configuration files are normally identified by
The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake variables unique to the build systems using BitBake.
environment variables are both usually set in the For example, the Yocto Project uses the
<filename>local.conf file</filename>. <filename>DISTRO</filename> and <filename>MACHINE</filename>
Valid distribution configuration files are available variables, respectively.
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.
</para> </para>
<para> <para>
@@ -1083,8 +1078,9 @@
The <filename>base.bbclass</filename> file The <filename>base.bbclass</filename> file
is always included. is always included.
Other classes that are specified in the configuration using the Other classes that are specified in the configuration using the
<filename>INHERIT</filename> variable are also included. <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
Class files are searched for in a classes subdirectory under 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 the paths in <filename>BBPATH</filename> in the same way as
configuration files. configuration files.
</para> </para>
@@ -1093,29 +1089,28 @@
After classes are included, the variable After classes are included, the variable
<filename>BBFILES</filename> is set, usually in <filename>BBFILES</filename> is set, usually in
<filename>local.conf</filename>, and defines the list of <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 Adding extra content to <filename>BBFILES</filename> is best
achieved through the use of BitBake layers as described in the achieved through the use of BitBake layers.
Layers section below.
</para> </para>
<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 <filename>BBFILES</filename> and stores the values of various
variables. variables into the datastore.
In summary, for each <filename>.bb</filename> file the configuration 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 plus the base class of variables are set, followed by the data in the
<filename>.bb</filename> file itself, followed by any inherit commands recipe file itself, followed by any inherit commands
that <filename>.bb</filename> file might contain. that the recipe file might contain.
</para> </para>
<para> <para>
Because parsing <filename>.bb</filename> files is a time consuming Because parsing recipe and append files is a time consuming
process, a cache is kept to speed up subsequent parsing. process, a cache, referred to as the "setscene"
This cache is invalid if the timestamp of the is kept to speed up subsequent parsing.
<filename>.bb</filename> file itself changes, or if the timestamps of The setscene is invalid if the timestamps of a recipe changes,
any of the include, configuration files or class files on which any of the include files change, configuration files change,
the <filename>.bb</filename> file depends change. or class files on which the recipe file depends change.
</para> </para>
</section> </section>
@@ -1126,12 +1121,12 @@
Prior to parsing configuration files, Bitbake looks Prior to parsing configuration files, Bitbake looks
at certain variables, including: at certain variables, including:
<itemizedlist> <itemizedlist>
<listitem><para><filename>BB-ENV-WHITELIST</filename></para></listitem> <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
<listitem><para><filename>BB_PRESERVE-ENV</filename></para></listitem> <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
<listitem><para><filename>BB_ENV_EXTRAWHITE</filename></para></listitem> <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
<listitem><para><filename>BB_ORIG_ENV</filename></para></listitem> <listitem><para><link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link></para></listitem>
<listitem><para><filename>PREFERRED_VERSIONS</filename></para></listitem> <listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem>
<listitem><para><filename>PREFERRED_PROVIDERS</filename></para></listitem> <listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@@ -1144,13 +1139,15 @@
<para> <para>
BitBake will first search the current working directory for an BitBake will first search the current working directory for an
optional <filename>conf/bblayers.conf</filename> configuration file. 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. variable that is a space delimited list of 'layer' directories.
For each directory in this list, a <filename>conf/layer.conf</filename> For each directory in this list, a <filename>conf/layer.conf</filename>
file will be searched for and parsed with the file will be searched for and parsed with the
<filename>LAYERDIR</filename> variable being set to the directory where <link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link>
the layer was found. variable being set to the directory where the layer was found.
The idea is these files will setup <filename>BBPATH</filename> 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 and other variables correctly for a given build directory automatically
for the user. for the user.
</para> </para>
@@ -1168,22 +1165,54 @@
in <filename>.conf</filename> files. in <filename>.conf</filename> files.
The following variables include: The following variables include:
<itemizedlist> <itemizedlist>
<listitem><para><filename>BITBAKE_UI</filename></para></listitem> <listitem><para>
<listitem><para><filename>BBDEBUG</filename></para></listitem> <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
<listitem><para><filename>MULTI_PROVIDER_WHITELIST</filename></para></listitem> </para></listitem>
<listitem><para><filename>BB_NUMBER_PARSE_THREADS</filename></para></listitem> <listitem><para>
<listitem><para><filename>BBPKGS</filename></para></listitem> <link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link>
<listitem><para><filename>BB_DEFAULT_TASK</filename></para></listitem> </para></listitem>
<listitem><para><filename>TOPDIR</filename></para></listitem> <listitem><para>
<listitem><para><filename>BB_VERBOSE_LOGS</filename></para></listitem> <link linkend='var-MULTI_PROVIDER_WHITELIST'><filename>MULTI_PROVIDER_WHITELIST</filename></link>
<listitem><para><filename>BB_NICE_LEVEL</filename></para></listitem> </para></listitem>
<listitem><para><filename>BBFILE_COLLECTIONS</filename></para></listitem> <listitem><para>
<listitem><para><filename>ASSUME_PROVIDED</filename></para></listitem> <link linkend='var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></link>
<listitem><para><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></para></listitem> </para></listitem>
<listitem><para><filename>BBINCLUDED</filename></para></listitem> <listitem><para>
<listitem><para><filename>BBFILE_PRIORITY</filename></para></listitem> <filename>BBPKGS</filename>
<listitem><para><filename>BUILDNAME</filename></para></listitem> </para></listitem>
<listitem><para><filename>BBMASK</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> </itemizedlist>
</para> </para>
@@ -1193,36 +1222,38 @@
<para> <para>
Layers allow you to isolate different types of Layers allow you to isolate different types of
customizations from each other. customizations from each other.
You might find it tempting to keep everything in one layer While you might find it tempting to keep everything in one layer
when working on a single project. when working on a single project, the more modular you organize
However, the more modular you organize your Metadata, the your metadata, the easier it is to cope with future changes.
easier it is to cope with future changes.
</para> </para>
<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. consider machine customizations.
These types of customizations typically reside in a special layer, These types of customizations typically reside in a special layer,
rather than a general layer, called a Board Specific Package (BSP) Layer. rather than a general layer, called a Board Specific Package (BSP) Layer.
Furthermore, the machine customizations should be isolated from 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. example.
This situation gives you a couple of layers: one for the machine 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 It is important to understand, however, that the BSP layer can still
make machine-specific additions to recipes within make machine-specific additions to recipes within
the GUI environment layer without polluting the GUI layer itself the GUI environment layer without polluting the GUI layer itself
with those machine-specific changes. with those machine-specific changes.
You can accomplish this through a recipe that is a BitBake append You can accomplish this through a recipe that is a BitBake append
(<filename>.bbappend</filename>) file, which is described (<filename>.bbappend</filename>) file.
later in this section.
</para> </para>
<para> <para>
There are certain variable specific to layers, including: There are certain variables specific to layers:
<itemizedlist> <itemizedlist>
<listitem><para><filename>LAYERDEPENDS</filename></para></listitem> <listitem><para>
<listitem><para><filename>LAYERVERSION</filename></para></listitem> <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
</para></listitem>
<listitem><para>
<link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link>
</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</section> </section>
@@ -1231,11 +1262,14 @@
<title>Schedulers</title> <title>Schedulers</title>
<para> <para>
There are variables specific to scheduling functionality Variables specific to scheduling functionality exist:
including:
<itemizedlist> <itemizedlist>
<listitem><para><filename>BB_SCHEDULER</filename></para></listitem> <listitem><para>
<listitem><para><filename>BB_SCHEDULERS</filename></para></listitem> <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> </itemizedlist>
</para> </para>
</section> </section>
@@ -1245,26 +1279,60 @@
<title>Classes</title> <title>Classes</title>
<para> <para>
BitBake classes are our rudimentary inheritance mechanism. BitBake's rudimentary inheritance mechanism is accomplished using
As briefly mentioned in the metadata introduction, they're classes.
parsed when an inherit directive is encountered, and they As briefly mentioned in the metadata introduction, BitBake
are located in the <filename>classes/</filename> directory parses a class when an inherit directive is encountered, and it
relative to the directories in <filename>BBPATH</filename>. is located in the <filename>classes</filename> directory
relative to the directories in
<link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
</para> </para>
</section> </section>
<section id='bb-files'> <section id='recipe-bb-files'>
<title><filename>.bb</filename> Files</title> <title>Recipe (<filename>.bb</filename>) Files</title>
<para> <para>
A BitBake (<filename>.bb</filename>) file is a logical unit Recipe files, which are files that have the
of tasks to be executed. <filename>.bb</filename> file extension, are logical units of
Normally this is a package to be built. tasks for execution.
Inter-<filename>.bb</filename> dependencies are obeyed. Normally, that logical unit is a package that needs to be
The files themselves are located via the built.
<filename>BBFILES</filename> variable, which </para>
is set to a space separated list of <filename>.bb</filename>
files, and does handle wildcards. <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='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>
Information in append files overrides the information in the
similarly-named recipe file.
</para> </para>
</section> </section>
</section> </section>