Squashed 'yocto-poky/' content from commit ea562de
git-subtree-dir: yocto-poky
git-subtree-split: ea562de57590c966cd5a75fda8defecd397e6436
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-customization.xsl b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-customization.xsl
new file mode 100644
index 0000000..5985ea7
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-customization.xsl
@@ -0,0 +1,29 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+
+ <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
+
+<!--
+
+ <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
+
+ <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
+
+-->
+
+ <xsl:include href="../template/permalinks.xsl"/>
+ <xsl:include href="../template/section.title.xsl"/>
+ <xsl:include href="../template/component.title.xsl"/>
+ <xsl:include href="../template/division.title.xsl"/>
+ <xsl:include href="../template/formal.object.heading.xsl"/>
+ <xsl:include href="../template/gloss-permalinks.xsl"/>
+
+ <xsl:param name="html.stylesheet" select="'user-manual-style.css'" />
+ <xsl:param name="chapter.autolabel" select="1" />
+ <xsl:param name="section.autolabel" select="1" />
+ <xsl:param name="section.label.includes.component.label" select="1" />
+ <xsl:param name="appendix.autolabel">A</xsl:param>
+
+<!-- <xsl:param name="generate.toc" select="'article nop'"></xsl:param> -->
+
+</xsl:stylesheet>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
new file mode 100644
index 0000000..fa52e29
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
@@ -0,0 +1,912 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="bitbake-user-manual-execution">
+ <title>Execution</title>
+
+ <para>
+ The primary purpose for running BitBake is to produce some kind
+ of output such as a single installable package, a kernel, a software
+ development kit, or even a full, board-specific bootable Linux image,
+ complete with bootloader, kernel, and root filesystem.
+ Of course, you can execute the <filename>bitbake</filename>
+ command with options that cause it to execute single tasks,
+ compile single recipe files, capture or clear data, or simply
+ return information about the execution environment.
+ </para>
+
+ <para>
+ This chapter describes BitBake's execution process from start
+ to finish when you use it to create an image.
+ The execution process is launched using the following command
+ form:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>target</replaceable>
+ </literallayout>
+ For information on the BitBake command and its options,
+ see
+ "<link linkend='bitbake-user-manual-command'>The BitBake Command</link>"
+ section.
+ <note>
+ <para>
+ Prior to executing BitBake, you should take advantage of available
+ parallel thread execution on your build host by setting the
+ <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
+ variable in your project's <filename>local.conf</filename>
+ configuration file.
+ </para>
+
+ <para>
+ A common method to determine this value for your build host is to run
+ the following:
+ <literallayout class='monospaced'>
+ $ grep processor /proc/cpuinfo
+ </literallayout>
+ This command returns the number of processors, which takes into
+ account hyper-threading.
+ Thus, a quad-core build host with hyper-threading most likely
+ shows eight processors, which is the value you would then assign to
+ <filename>BB_NUMBER_THREADS</filename>.
+ </para>
+
+ <para>
+ A possibly simpler solution is that some Linux distributions
+ (e.g. Debian and Ubuntu) provide the <filename>ncpus</filename> command.
+ </para>
+ </note>
+ </para>
+
+ <section id='parsing-the-base-configuration-metadata'>
+ <title>Parsing the Base Configuration Metadata</title>
+
+ <para>
+ The first thing BitBake does is parse base configuration
+ metadata.
+ Base configuration metadata consists of your project's
+ <filename>bblayers.conf</filename> file to determine what
+ layers BitBake needs to recognize, all necessary
+ <filename>layer.conf</filename> files (one from each layer),
+ and <filename>bitbake.conf</filename>.
+ The data itself is of various types:
+ <itemizedlist>
+ <listitem><para><emphasis>Recipes:</emphasis>
+ Details about particular pieces of software.
+ </para></listitem>
+ <listitem><para><emphasis>Class Data:</emphasis>
+ An abstraction of common build information
+ (e.g. how to build a Linux kernel).
+ </para></listitem>
+ <listitem><para><emphasis>Configuration Data:</emphasis>
+ Machine-specific settings, policy decisions,
+ and so forth.
+ Configuration data acts as the glue to bind everything
+ together.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The <filename>layer.conf</filename> files are used to
+ construct key variables such as
+ <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+ and
+ <link linkend='var-BBFILES'><filename>BBFILES</filename></link>.
+ <filename>BBPATH</filename> is used to search for
+ configuration and class files under the
+ <filename>conf</filename> and <filename>classes</filename>
+ directories, respectively.
+ <filename>BBFILES</filename> is used to locate both recipe
+ and recipe append files
+ (<filename>.bb</filename> and <filename>.bbappend</filename>).
+ If there is no <filename>bblayers.conf</filename> file,
+ it is assumed the user has set the <filename>BBPATH</filename>
+ and <filename>BBFILES</filename> directly in the environment.
+ </para>
+
+ <para>
+ Next, the <filename>bitbake.conf</filename> file is located
+ using the <filename>BBPATH</filename> variable that was
+ just constructed.
+ The <filename>bitbake.conf</filename> file may also include other
+ configuration files using the
+ <filename>include</filename> or
+ <filename>require</filename> directives.
+ </para>
+
+ <para>
+ Prior to parsing configuration files, Bitbake looks
+ at certain variables, including:
+ <itemizedlist>
+ <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-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
+ </para></listitem>
+ </itemizedlist>
+ You can find information on how to pass environment variables into the BitBake
+ execution environment in the
+ "<link linkend='passing-information-into-the-build-task-environment'>Passing Information Into the Build Task Environment</link>" section.
+ </para>
+
+ <para>
+ The base configuration metadata is global
+ and therefore affects all recipes and tasks that are executed.
+ </para>
+
+ <para>
+ BitBake first searches the current working directory for an
+ optional <filename>conf/bblayers.conf</filename> configuration file.
+ 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.
+ Recall that if BitBake cannot find a <filename>bblayers.conf</filename>
+ file, then it is assumed the user has set the <filename>BBPATH</filename>
+ and <filename>BBFILES</filename> variables directly in the environment.
+ </para>
+
+ <para>
+ For each directory (layer) in this list, a <filename>conf/layer.conf</filename>
+ file is located and parsed with the
+ <link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link>
+ variable being set to the directory where the layer was found.
+ The idea is these files automatically set up
+ <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+ and other variables correctly for a given build directory.
+ </para>
+
+ <para>
+ BitBake then expects to find the <filename>conf/bitbake.conf</filename>
+ file somewhere in the user-specified <filename>BBPATH</filename>.
+ That configuration file generally has include directives to pull
+ in any other metadata such as files specific to the architecture,
+ the machine, the local environment, and so forth.
+ </para>
+
+ <para>
+ Only variable definitions and include directives are allowed
+ in BitBake <filename>.conf</filename> files.
+ Some variables directly influence BitBake's behavior.
+ These variables might have been set from the environment
+ depending on the environment variables previously
+ mentioned or set in the configuration files.
+ The
+ "<link linkend='ref-variables-glos'>Variables Glossary</link>"
+ chapter presents a full list of variables.
+ </para>
+
+ <para>
+ After parsing configuration files, BitBake uses its rudimentary
+ inheritance mechanism, which is through class files, to inherit
+ some standard classes.
+ BitBake parses a class when the inherit directive responsible
+ for getting that class is encountered.
+ </para>
+
+ <para>
+ The <filename>base.bbclass</filename> file is always included.
+ Other classes that are specified in the configuration using the
+ <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
+ variable are also included.
+ BitBake searches for class files in a
+ <filename>classes</filename> subdirectory under
+ the paths in <filename>BBPATH</filename> in the same way as
+ configuration files.
+ </para>
+
+ <para>
+ A good way to get an idea of the configuration files and
+ the class files used in your execution environment is to
+ run the following BitBake command:
+ <literallayout class='monospaced'>
+ $ bitbake -e > mybb.log
+ </literallayout>
+ Examining the top of the <filename>mybb.log</filename>
+ shows you the many configuration files and class files
+ used in your execution environment.
+ </para>
+
+ <note>
+ <para>
+ You need to be aware of how BitBake parses curly braces.
+ If a recipe uses a closing curly brace within the function and
+ the character has no leading spaces, BitBake produces a parsing
+ error.
+ If you use a pair of curly braces in a shell function, the
+ closing curly brace must not be located at the start of the line
+ without leading spaces.
+ </para>
+
+ <para>
+ Here is an example that causes BitBake to produce a parsing
+ error:
+ <literallayout class='monospaced'>
+ fakeroot create_shar() {
+ cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
+ usage()
+ {
+ echo "test"
+ ###### The following "}" at the start of the line causes a parsing error ######
+ }
+ EOF
+ }
+ </literallayout>
+ Writing the recipe this way avoids the error:
+ <literallayout class='monospaced'>
+ fakeroot create_shar() {
+ cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
+ usage()
+ {
+ echo "test"
+ ######The following "}" with a leading space at the start of the line avoids the error ######
+ }
+ EOF
+ }
+ </literallayout>
+ </para>
+ </note>
+ </section>
+
+ <section id='locating-and-parsing-recipes'>
+ <title>Locating and Parsing Recipes</title>
+
+ <para>
+ During the configuration phase, BitBake will have set
+ <link linkend='var-BBFILES'><filename>BBFILES</filename></link>.
+ BitBake now uses it to construct a list of recipes to parse,
+ along with any append files (<filename>.bbappend</filename>)
+ to apply.
+ <filename>BBFILES</filename> is a space-separated list of
+ available files and supports wildcards.
+ An example would be:
+ <literallayout class='monospaced'>
+ BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
+ </literallayout>
+ BitBake parses each recipe and append file located
+ with <filename>BBFILES</filename> and stores the values of
+ various variables into the datastore.
+ <note>
+ Append files are applied in the order they are encountered in
+ <filename>BBFILES</filename>.
+ </note>
+ For each file, a fresh copy of the base configuration is
+ made, then the recipe is parsed line by line.
+ Any inherit statements cause BitBake to find and
+ then parse class files (<filename>.bbclass</filename>)
+ using
+ <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+ as the search path.
+ Finally, BitBake parses in order any append files found in
+ <filename>BBFILES</filename>.
+ </para>
+
+ <para>
+ One common convention is to use the recipe filename to define
+ pieces of metadata.
+ For example, in <filename>bitbake.conf</filename> the recipe
+ name and version are used to set the variables
+ <link linkend='var-PN'><filename>PN</filename></link> and
+ <link linkend='var-PV'><filename>PV</filename></link>:
+ <literallayout class='monospaced'>
+ PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
+ PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
+ </literallayout>
+ In this example, a recipe called "something_1.2.3.bb" would set
+ <filename>PN</filename> to "something" and
+ <filename>PV</filename> to "1.2.3".
+ </para>
+
+ <para>
+ By the time parsing is complete for a recipe, BitBake
+ has a list of tasks that the recipe defines and a set of
+ data consisting of keys and values as well as
+ dependency information about the tasks.
+ </para>
+
+ <para>
+ BitBake does not need all of this information.
+ It only needs a small subset of the information to make
+ decisions about the recipe.
+ Consequently, BitBake caches the values in which it is
+ interested and does not store the rest of the information.
+ Experience has shown it is faster to re-parse the metadata than to
+ try and write it out to the disk and then reload it.
+ </para>
+
+ <para>
+ Where possible, subsequent BitBake commands reuse this cache of
+ recipe information.
+ The validity of this cache is determined by first computing a
+ checksum of the base configuration data (see
+ <link linkend='var-BB_HASHCONFIG_WHITELIST'><filename>BB_HASHCONFIG_WHITELIST</filename></link>)
+ and then checking if the checksum matches.
+ If that checksum matches what is in the cache and the recipe
+ and class files have not changed, Bitbake is able to use
+ the cache.
+ BitBake then reloads the cached information about the recipe
+ instead of reparsing it from scratch.
+ </para>
+
+ <para>
+ Recipe file collections exist to allow the user to
+ have multiple repositories of
+ <filename>.bb</filename> files that contain the same
+ exact package.
+ For example, one could easily use them to make one's
+ own local copy of an upstream repository, but with
+ custom modifications that one does not want upstream.
+ Here is an example:
+ <literallayout class='monospaced'>
+ BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
+ BBFILE_COLLECTIONS = "upstream local"
+ BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
+ BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
+ BBFILE_PRIORITY_upstream = "5"
+ BBFILE_PRIORITY_local = "10"
+ </literallayout>
+ <note>
+ The layers mechanism is now the preferred method of collecting
+ code.
+ While the collections code remains, its main use is to set layer
+ priorities and to deal with overlap (conflicts) between layers.
+ </note>
+ </para>
+ </section>
+
+ <section id='bb-bitbake-providers'>
+ <title>Providers</title>
+
+ <para>
+ Assuming BitBake has been instructed to execute a target
+ and that all the recipe files have been parsed, BitBake
+ starts to figure out how to build the target.
+ BitBake looks through the <filename>PROVIDES</filename> list
+ for each of the recipes.
+ A <filename>PROVIDES</filename> list is the list of names by which
+ the recipe can be known.
+ Each recipe's <filename>PROVIDES</filename> list is created
+ implicitly through the recipe's
+ <link linkend='var-PN'><filename>PN</filename></link> variable
+ and explicitly through the recipe's
+ <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
+ variable, which is optional.
+ </para>
+
+ <para>
+ When a recipe uses <filename>PROVIDES</filename>, that recipe's
+ functionality can be found under an alternative name or names other
+ than the implicit <filename>PN</filename> name.
+ As an example, suppose a recipe named <filename>keyboard_1.0.bb</filename>
+ contained the following:
+ <literallayout class='monospaced'>
+ PROVIDES += "fullkeyboard"
+ </literallayout>
+ The <filename>PROVIDES</filename> list for this recipe becomes
+ "keyboard", which is implicit, and "fullkeyboard", which is explicit.
+ Consequently, the functionality found in
+ <filename>keyboard_1.0.bb</filename> can be found under two
+ different names.
+ </para>
+ </section>
+
+ <section id='bb-bitbake-preferences'>
+ <title>Preferences</title>
+
+ <para>
+ The <filename>PROVIDES</filename> list is only part of the solution
+ for figuring out a target's recipes.
+ Because targets might have multiple providers, BitBake needs
+ to prioritize providers by determining provider preferences.
+ </para>
+
+ <para>
+ A common example in which a target has multiple providers
+ is "virtual/kernel", which is on the
+ <filename>PROVIDES</filename> list for each kernel recipe.
+ Each machine often selects the best kernel provider by using a
+ line similar to the following in the machine configuration file:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
+ </literallayout>
+ The default
+ <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
+ is the provider with the same name as the target.
+ Bitbake iterates through each target it needs to build and
+ resolves them and their dependencies using this process.
+ </para>
+
+ <para>
+ Understanding how providers are chosen is made complicated by the fact
+ that multiple versions might exist for a given provider.
+ BitBake defaults to the highest version of a provider.
+ Version comparisons are made using the same method as Debian.
+ You can use the
+ <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
+ variable to specify a particular version.
+ You can influence the order by using the
+ <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
+ variable.
+ </para>
+
+ <para>
+ By default, files have a preference of "0".
+ Setting <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
+ recipe unlikely to be used unless it is explicitly referenced.
+ Setting <filename>DEFAULT_PREFERENCE</filename> to "1" makes it
+ likely the recipe is used.
+ <filename>PREFERRED_VERSION</filename> overrides any
+ <filename>DEFAULT_PREFERENCE</filename> setting.
+ <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer
+ and more experimental recipe versions until they have undergone
+ sufficient testing to be considered stable.
+ </para>
+
+ <para>
+ When there are multiple “versions” of a given recipe,
+ BitBake defaults to selecting the most recent
+ version, unless otherwise specified.
+ If the recipe in question has a
+ <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
+ set lower than the other recipes (default is 0), then
+ it will not be selected.
+ This allows the person or persons maintaining
+ the repository of recipe files to specify
+ their preference for the default selected version.
+ Additionally, the user can specify their preferred version.
+ </para>
+
+ <para>
+ If the first recipe is named <filename>a_1.1.bb</filename>, then the
+ <link linkend='var-PN'><filename>PN</filename></link> variable
+ will be set to “a”, and the
+ <link linkend='var-PV'><filename>PV</filename></link>
+ variable will be set to 1.1.
+ </para>
+
+ <para>
+ Thus, if a recipe named <filename>a_1.2.bb</filename> exists, BitBake
+ will choose 1.2 by default.
+ However, if you define the following variable in a
+ <filename>.conf</filename> file that BitBake parses, you
+ can change that preference:
+ <literallayout class='monospaced'>
+ PREFERRED_VERSION_a = "1.1"
+ </literallayout>
+ </para>
+
+ <note>
+ <para>
+ It is common for a recipe to provide two versions -- a stable,
+ numbered (and preferred) version, and a version that is
+ automatically checked out from a source code repository that
+ is considered more "bleeding edge" but can be selected only
+ explicitly.
+ </para>
+
+ <para>
+ For example, in the OpenEmbedded codebase, there is a standard,
+ versioned recipe file for BusyBox,
+ <filename>busybox_1.22.1.bb</filename>,
+ but there is also a Git-based version,
+ <filename>busybox_git.bb</filename>, which explicitly contains the line
+ <literallayout class='monospaced'>
+ DEFAULT_PREFERENCE = "-1"
+ </literallayout>
+ to ensure that the numbered, stable version is always preferred
+ unless the developer selects otherwise.
+ </para>
+ </note>
+ </section>
+
+ <section id='bb-bitbake-dependencies'>
+ <title>Dependencies</title>
+
+ <para>
+ Each target BitBake builds consists of multiple tasks such as
+ <filename>fetch</filename>, <filename>unpack</filename>,
+ <filename>patch</filename>, <filename>configure</filename>,
+ and <filename>compile</filename>.
+ For best performance on multi-core systems, BitBake considers each
+ task as an independent
+ entity with its own set of dependencies.
+ </para>
+
+ <para>
+ Dependencies are defined through several variables.
+ You can find information about variables BitBake uses in
+ the <link linkend='ref-variables-glos'>Variables Glossary</link>
+ near the end of this manual.
+ At a basic level, it is sufficient to know that BitBake uses the
+ <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> and
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> variables when
+ calculating dependencies.
+ </para>
+
+ <para>
+ For more information on how BitBake handles dependencies, see the
+ "<link linkend='dependencies'>Dependencies</link>" section.
+ </para>
+ </section>
+
+ <section id='ref-bitbake-tasklist'>
+ <title>The Task List</title>
+
+ <para>
+ Based on the generated list of providers and the dependency information,
+ BitBake can now calculate exactly what tasks it needs to run and in what
+ order it needs to run them.
+ The
+ "<link linkend='executing-tasks'>Executing Tasks</link>" section has more
+ information on how BitBake chooses which task to execute next.
+ </para>
+
+ <para>
+ The build now starts with BitBake forking off threads up to the limit set in the
+ <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
+ variable.
+ BitBake continues to fork threads as long as there are tasks ready to run,
+ those tasks have all their dependencies met, and the thread threshold has not been
+ exceeded.
+ </para>
+
+ <para>
+ It is worth noting that you can greatly speed up the build time by properly setting
+ the <filename>BB_NUMBER_THREADS</filename> variable.
+ </para>
+
+ <para>
+ As each task completes, a timestamp is written to the directory specified by the
+ <link linkend='var-STAMP'><filename>STAMP</filename></link> variable.
+ On subsequent runs, BitBake looks in the build directory within
+ <filename>tmp/stamps</filename> and does not rerun
+ tasks that are already completed unless a timestamp is found to be invalid.
+ Currently, invalid timestamps are only considered on a per
+ recipe file basis.
+ So, for example, if the configure stamp has a timestamp greater than the
+ compile timestamp for a given target, then the compile task would rerun.
+ Running the compile task again, however, has no effect on other providers
+ that depend on that target.
+ </para>
+
+ <para>
+ The exact format of the stamps is partly configurable.
+ In modern versions of BitBake, a hash is appended to the
+ stamp so that if the configuration changes, the stamp becomes
+ invalid and the task is automatically rerun.
+ This hash, or signature used, is governed by the signature policy
+ that is configured (see the
+ "<link linkend='checksums'>Checksums (Signatures)</link>"
+ section for information).
+ It is also possible to append extra metadata to the stamp using
+ the "stamp-extra-info" task flag.
+ For example, OpenEmbedded uses this flag to make some tasks machine-specific.
+ </para>
+
+ <note>
+ Some tasks are marked as "nostamp" tasks.
+ No timestamp file is created when these tasks are run.
+ Consequently, "nostamp" tasks are always rerun.
+ </note>
+
+ <para>
+ For more information on tasks, see the
+ "<link linkend='tasks'>Tasks</link>" section.
+ </para>
+ </section>
+
+ <section id='executing-tasks'>
+ <title>Executing Tasks</title>
+
+ <para>
+ Tasks can be either a shell task or a Python task.
+ For shell tasks, BitBake writes a shell script to
+ <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}/run.do_taskname.pid</filename>
+ and then executes the script.
+ The generated shell script contains all the exported variables,
+ and the shell functions with all variables expanded.
+ Output from the shell script goes to the file
+ <filename>${T}/log.do_taskname.pid</filename>.
+ Looking at the expanded shell functions in the run file and
+ the output in the log files is a useful debugging technique.
+ </para>
+
+ <para>
+ For Python tasks, BitBake executes the task internally and logs
+ information to the controlling terminal.
+ Future versions of BitBake will write the functions to files
+ similar to the way shell tasks are handled.
+ Logging will be handled in a way similar to shell tasks as well.
+ </para>
+
+ <para>
+ The order in which BitBake runs the tasks is controlled by its
+ task scheduler.
+ It is possible to configure the scheduler and define custom
+ implementations for specific use cases.
+ For more information, see these variables that control the
+ behavior:
+ <itemizedlist>
+ <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>
+ It is possible to have functions run before and after a task's main
+ function.
+ This is done using the "prefuncs" and "postfuncs" flags of the task
+ that lists the functions to run.
+ </para>
+ </section>
+
+ <section id='checksums'>
+ <title>Checksums (Signatures)</title>
+
+ <para>
+ A checksum is a unique signature of a task's inputs.
+ The signature of a task can be used to determine if a task
+ needs to be run.
+ Because it is a change in a task's inputs that triggers running
+ the task, BitBake needs to detect all the inputs to a given task.
+ For shell tasks, this turns out to be fairly easy because
+ BitBake generates a "run" shell script for each task and
+ it is possible to create a checksum that gives you a good idea of when
+ the task's data changes.
+ </para>
+
+ <para>
+ To complicate the problem, some things should not be included in
+ the checksum.
+ First, there is the actual specific build path of a given task -
+ the working directory.
+ It does not matter if the working directory changes because it should not
+ affect the output for target packages.
+ The simplistic approach for excluding the working directory is to set
+ it to some fixed value and create the checksum for the "run" script.
+ BitBake goes one step better and uses the
+ <link linkend='var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></link>
+ variable to define a list of variables that should never be included
+ when generating the signatures.
+ </para>
+
+ <para>
+ Another problem results from the "run" scripts containing functions that
+ might or might not get called.
+ The incremental build solution contains code that figures out dependencies
+ between shell functions.
+ This code is used to prune the "run" scripts down to the minimum set,
+ thereby alleviating this problem and making the "run" scripts much more
+ readable as a bonus.
+ </para>
+
+ <para>
+ So far we have solutions for shell scripts.
+ What about Python tasks?
+ The same approach applies even though these tasks are more difficult.
+ The process needs to figure out what variables a Python function accesses
+ and what functions it calls.
+ Again, the incremental build solution contains code that first figures out
+ the variable and function dependencies, and then creates a checksum for the data
+ used as the input to the task.
+ </para>
+
+ <para>
+ Like the working directory case, situations exist where dependencies
+ should be ignored.
+ For these cases, you can instruct the build process to ignore a dependency
+ by using a line like the following:
+ <literallayout class='monospaced'>
+ PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
+ </literallayout>
+ This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not
+ depend on the value of <filename>MACHINE</filename>, even if it does reference it.
+ </para>
+
+ <para>
+ Equally, there are cases where we need to add dependencies BitBake
+ is not able to find.
+ You can accomplish this by using a line like the following:
+ <literallayout class='monospaced'>
+ PACKAGE_ARCHS[vardeps] = "MACHINE"
+ </literallayout>
+ This example explicitly adds the <filename>MACHINE</filename> variable as a
+ dependency for <filename>PACKAGE_ARCHS</filename>.
+ </para>
+
+ <para>
+ Consider a case with in-line Python, for example, where BitBake is not
+ able to figure out dependencies.
+ When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
+ produces output when it discovers something for which it cannot figure out
+ dependencies.
+ </para>
+
+ <para>
+ Thus far, this section has limited discussion to the direct inputs into a task.
+ Information based on direct inputs is referred to as the "basehash" in the
+ code.
+ However, there is still the question of a task's indirect inputs - the
+ things that were already built and present in the build directory.
+ The checksum (or signature) for a particular task needs to add the hashes
+ of all the tasks on which the particular task depends.
+ Choosing which dependencies to add is a policy decision.
+ However, the effect is to generate a master checksum that combines the basehash
+ and the hashes of the task's dependencies.
+ </para>
+
+ <para>
+ At the code level, there are a variety of ways both the basehash and the
+ dependent task hashes can be influenced.
+ Within the BitBake configuration file, we can give BitBake some extra information
+ to help it construct the basehash.
+ The following statement effectively results in a list of global variable
+ dependency excludes - variables never included in any checksum.
+ This example uses variables from OpenEmbedded to help illustrate
+ the concept:
+ <literallayout class='monospaced'>
+ BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
+ SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
+ USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
+ PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
+ CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
+ </literallayout>
+ The previous example excludes the work directory, which is part of
+ <filename>TMPDIR</filename>.
+ </para>
+
+ <para>
+ The rules for deciding which hashes of dependent tasks to include through
+ dependency chains are more complex and are generally accomplished with a
+ Python function.
+ The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
+ of this and also illustrates how you can insert your own policy into the system
+ if so desired.
+ This file defines the two basic signature generators OpenEmbedded Core
+ uses: "OEBasic" and "OEBasicHash".
+ By default, there is a dummy "noop" signature handler enabled in BitBake.
+ This means that behavior is unchanged from previous versions.
+ <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
+ through this setting in the <filename>bitbake.conf</filename> file:
+ <literallayout class='monospaced'>
+ BB_SIGNATURE_HANDLER ?= "OEBasicHash"
+ </literallayout>
+ The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
+ "OEBasic" version but adds the task hash to the stamp files.
+ This results in any metadata change that changes the task hash, automatically
+ causing the task to be run again.
+ This removes the need to bump
+ <link linkend='var-PR'><filename>PR</filename></link>
+ values, and changes to metadata automatically ripple across the build.
+ </para>
+
+ <para>
+ It is also worth noting that the end result of these signature generators is to
+ make some dependency and hash information available to the build.
+ This information includes:
+ <itemizedlist>
+ <listitem><para><filename>BB_BASEHASH_task-</filename><replaceable>taskname</replaceable>:
+ The base hashes for each task in the recipe.
+ </para></listitem>
+ <listitem><para><filename>BB_BASEHASH_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>:
+ The base hashes for each dependent task.
+ </para></listitem>
+ <listitem><para><filename>BBHASHDEPS_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>:
+ The task dependencies for each task.
+ </para></listitem>
+ <listitem><para><filename>BB_TASKHASH</filename>:
+ The hash of the currently running task.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ It is worth noting that BitBake's "-S" option lets you
+ debug Bitbake's processing of signatures.
+ The options passed to -S allow different debugging modes
+ to be used, either using BitBake's own debug functions
+ or possibly those defined in the metadata/signature handler
+ itself.
+ The simplest parameter to pass is "none", which causes a
+ set of signature information to be written out into
+ <filename>STAMP_DIR</filename>
+ corresponding to the targets specified.
+ The other currently available parameter is "printdiff",
+ which causes BitBake to try to establish the closest
+ signature match it can (e.g. in the sstate cache) and then
+ run <filename>bitbake-diffsigs</filename> over the matches
+ to determine the stamps and delta where these two
+ stamp trees diverge.
+ <note>
+ It is likely that future versions of BitBake will
+ provide other signature handlers triggered through
+ additional "-S" parameters.
+ </note>
+ </para>
+
+ <para>
+ You can find more information on checksum metadata in the
+ "<link linkend='task-checksums-and-setscene'>Task Checksums and Setscene</link>"
+ section.
+ </para>
+ </section>
+
+ <section id='setscene'>
+ <title>Setscene</title>
+
+ <para>
+ The setscene process enables BitBake to handle "pre-built" artifacts.
+ The ability to handle and reuse these artifacts allows BitBake
+ the luxury of not having to build something from scratch every time.
+ Instead, BitBake can use, when possible, existing build artifacts.
+ </para>
+
+ <para>
+ BitBake needs to have reliable data indicating whether or not an
+ artifact is compatible.
+ Signatures, described in the previous section, provide an ideal
+ way of representing whether an artifact is compatible.
+ If a signature is the same, an object can be reused.
+ </para>
+
+ <para>
+ If an object can be reused, the problem then becomes how to
+ replace a given task or set of tasks with the pre-built artifact.
+ BitBake solves the problem with the "setscene" process.
+ </para>
+
+ <para>
+ When BitBake is asked to build a given target, before building anything,
+ it first asks whether cached information is available for any of the
+ targets it's building, or any of the intermediate targets.
+ If cached information is available, BitBake uses this information instead of
+ running the main tasks.
+ </para>
+
+ <para>
+ BitBake first calls the function defined by the
+ <link linkend='var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>
+ variable with a list of tasks and corresponding
+ hashes it wants to build.
+ This function is designed to be fast and returns a list
+ of the tasks for which it believes in can obtain artifacts.
+ </para>
+
+ <para>
+ Next, for each of the tasks that were returned as possibilities,
+ BitBake executes a setscene version of the task that the possible
+ artifact covers.
+ Setscene versions of a task have the string "_setscene" appended to the
+ task name.
+ So, for example, the task with the name <filename>xxx</filename> has
+ a setscene task named <filename>xxx_setscene</filename>.
+ The setscene version of the task executes and provides the necessary
+ artifacts returning either success or failure.
+ </para>
+
+ <para>
+ As previously mentioned, an artifact can cover more than one task.
+ For example, it is pointless to obtain a compiler if you
+ already have the compiled binary.
+ To handle this, BitBake calls the
+ <link linkend='var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>
+ function for each successful setscene task to know whether or not it needs
+ to obtain the dependencies of that task.
+ </para>
+
+ <para>
+ Finally, after all the setscene tasks have executed, BitBake calls the
+ function listed in
+ <link linkend='var-BB_SETSCENE_VERIFY_FUNCTION'><filename>BB_SETSCENE_VERIFY_FUNCTION</filename></link>
+ with the list of tasks BitBake thinks has been "covered".
+ The metadata can then ensure that this list is correct and can
+ inform BitBake that it wants specific tasks to be run regardless
+ of the setscene result.
+ </para>
+
+ <para>
+ You can find more information on setscene metadata in the
+ "<link linkend='task-checksums-and-setscene'>Task Checksums and Setscene</link>"
+ section.
+ </para>
+ </section>
+</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
new file mode 100644
index 0000000..f168cfa
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
@@ -0,0 +1,765 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter>
+<title>File Download Support</title>
+
+ <para>
+ BitBake's fetch module is a standalone piece of library code
+ that deals with the intricacies of downloading source code
+ and files from remote systems.
+ Fetching source code is one of the cornerstones of building software.
+ As such, this module forms an important part of BitBake.
+ </para>
+
+ <para>
+ The current fetch module is called "fetch2" and refers to the
+ fact that it is the second major version of the API.
+ The original version is obsolete and has been removed from the codebase.
+ Thus, in all cases, "fetch" refers to "fetch2" in this
+ manual.
+ </para>
+
+ <section id='the-download-fetch'>
+ <title>The Download (Fetch)</title>
+
+ <para>
+ BitBake takes several steps when fetching source code or files.
+ The fetcher codebase deals with two distinct processes in order:
+ obtaining the files from somewhere (cached or otherwise)
+ and then unpacking those files into a specific location and
+ perhaps in a specific way.
+ Getting and unpacking the files is often optionally followed
+ by patching.
+ Patching, however, is not covered by this module.
+ </para>
+
+ <para>
+ The code to execute the first part of this process, a fetch,
+ looks something like the following:
+ <literallayout class='monospaced'>
+ src_uri = (d.getVar('SRC_URI', True) or "").split()
+ fetcher = bb.fetch2.Fetch(src_uri, d)
+ fetcher.download()
+ </literallayout>
+ This code sets up an instance of the fetch class.
+ The instance uses a space-separated list of URLs from the
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+ variable and then calls the <filename>download</filename>
+ method to download the files.
+ </para>
+
+ <para>
+ The instantiation of the fetch class is usually followed by:
+ <literallayout class='monospaced'>
+ rootdir = l.getVar('WORKDIR', True)
+ fetcher.unpack(rootdir)
+ </literallayout>
+ This code unpacks the downloaded files to the
+ specified by <filename>WORKDIR</filename>.
+ <note>
+ For convenience, the naming in these examples matches
+ the variables used by OpenEmbedded.
+ If you want to see the above code in action, examine
+ the OpenEmbedded class file <filename>base.bbclass</filename>.
+ </note>
+ The <filename>SRC_URI</filename> and <filename>WORKDIR</filename>
+ variables are not hardcoded into the fetcher, since those fetcher
+ methods can be (and are) called with different variable names.
+ In OpenEmbedded for example, the shared state (sstate) code uses
+ the fetch module to fetch the sstate files.
+ </para>
+
+ <para>
+ When the <filename>download()</filename> method is called,
+ BitBake tries to resolve the URLs by looking for source files
+ in a specific search order:
+ <itemizedlist>
+ <listitem><para><emphasis>Pre-mirror Sites:</emphasis>
+ BitBake first uses pre-mirrors to try and find source files.
+ These locations are defined using the
+ <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
+ variable.
+ </para></listitem>
+ <listitem><para><emphasis>Source URI:</emphasis>
+ If pre-mirrors fail, BitBake uses the original URL (e.g from
+ <filename>SRC_URI</filename>).
+ </para></listitem>
+ <listitem><para><emphasis>Mirror Sites:</emphasis>
+ If fetch failures occur, BitBake next uses mirror locations as
+ defined by the
+ <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
+ variable.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ For each URL passed to the fetcher, the fetcher
+ calls the submodule that handles that particular URL type.
+ This behavior can be the source of some confusion when you
+ are providing URLs for the <filename>SRC_URI</filename>
+ variable.
+ Consider the following two URLs:
+ <literallayout class='monospaced'>
+ http://git.yoctoproject.org/git/poky;protocol=git
+ git://git.yoctoproject.org/git/poky;protocol=http
+ </literallayout>
+ In the former case, the URL is passed to the
+ <filename>wget</filename> fetcher, which does not
+ understand "git".
+ Therefore, the latter case is the correct form since the
+ Git fetcher does know how to use HTTP as a transport.
+ </para>
+
+ <para>
+ Here are some examples that show commonly used mirror
+ definitions:
+ <literallayout class='monospaced'>
+ PREMIRRORS ?= "\
+ bzr://.*/.* http://somemirror.org/sources/ \n \
+ cvs://.*/.* http://somemirror.org/sources/ \n \
+ git://.*/.* http://somemirror.org/sources/ \n \
+ hg://.*/.* http://somemirror.org/sources/ \n \
+ osc://.*/.* http://somemirror.org/sources/ \n \
+ p4://.*/.* http://somemirror.org/sources/ \n \
+ svn://.*/.* http://somemirror.org/sources/ \n"
+
+ MIRRORS =+ "\
+ ftp://.*/.* http://somemirror.org/sources/ \n \
+ http://.*/.* http://somemirror.org/sources/ \n \
+ https://.*/.* http://somemirror.org/sources/ \n"
+ </literallayout>
+ It is useful to note that BitBake supports
+ cross-URLs.
+ It is possible to mirror a Git repository on an HTTP
+ server as a tarball.
+ This is what the <filename>git://</filename> mapping in
+ the previous example does.
+ </para>
+
+ <para>
+ Since network accesses are slow, Bitbake maintains a
+ cache of files downloaded from the network.
+ Any source files that are not local (i.e.
+ downloaded from the Internet) are placed into the download
+ directory, which is specified by the
+ <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+ variable.
+ </para>
+
+ <para>
+ File integrity is of key importance for reproducing builds.
+ For non-local archive downloads, the fetcher code can verify
+ SHA-256 and MD5 checksums to ensure the archives have been
+ downloaded correctly.
+ You can specify these checksums by using the
+ <filename>SRC_URI</filename> variable with the appropriate
+ varflags as follows:
+ <literallayout class='monospaced'>
+ SRC_URI[md5sum] = "<replaceable>value</replaceable>"
+ SRC_URI[sha256sum] = "<replaceable>value</replaceable>"
+ </literallayout>
+ You can also specify the checksums as parameters on the
+ <filename>SRC_URI</filename> as shown below:
+ <literallayout class='monospaced'>
+ SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
+ </literallayout>
+ If multiple URIs exist, you can specify the checksums either
+ directly as in the previous example, or you can name the URLs.
+ The following syntax shows how you name the URIs:
+ <literallayout class='monospaced'>
+ SRC_URI = "http://example.com/foobar.tar.bz2;name=foo"
+ SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d
+ </literallayout>
+ After a file has been downloaded and has had its checksum checked,
+ a ".done" stamp is placed in <filename>DL_DIR</filename>.
+ BitBake uses this stamp during subsequent builds to avoid
+ downloading or comparing a checksum for the file again.
+ <note>
+ It is assumed that local storage is safe from data corruption.
+ If this were not the case, there would be bigger issues to worry about.
+ </note>
+ </para>
+
+ <para>
+ If
+ <link linkend='var-BB_STRICT_CHECKSUM'><filename>BB_STRICT_CHECKSUM</filename></link>
+ is set, any download without a checksum triggers an
+ error message.
+ The
+ <link linkend='var-BB_NO_NETWORK'><filename>BB_NO_NETWORK</filename></link>
+ variable can be used to make any attempted network access a fatal
+ error, which is useful for checking that mirrors are complete
+ as well as other things.
+ </para>
+ </section>
+
+ <section id='bb-the-unpack'>
+ <title>The Unpack</title>
+
+ <para>
+ The unpack process usually immediately follows the download.
+ For all URLs except Git URLs, BitBake uses the common
+ <filename>unpack</filename> method.
+ </para>
+
+ <para>
+ A number of parameters exist that you can specify within the
+ URL to govern the behavior of the unpack stage:
+ <itemizedlist>
+ <listitem><para><emphasis>unpack:</emphasis>
+ Controls whether the URL components are unpacked.
+ If set to "1", which is the default, the components
+ are unpacked.
+ If set to "0", the unpack stage leaves the file alone.
+ This parameter is useful when you want an archive to be
+ copied in and not be unpacked.
+ </para></listitem>
+ <listitem><para><emphasis>dos:</emphasis>
+ Applies to <filename>.zip</filename> and
+ <filename>.jar</filename> files and specifies whether to
+ use DOS line ending conversion on text files.
+ </para></listitem>
+ <listitem><para><emphasis>basepath:</emphasis>
+ Instructs the unpack stage to strip the specified
+ directories from the source path when unpacking.
+ </para></listitem>
+ <listitem><para><emphasis>subdir:</emphasis>
+ Unpacks the specific URL to the specified subdirectory
+ within the root directory.
+ </para></listitem>
+ </itemizedlist>
+ The unpack call automatically decompresses and extracts files
+ with ".Z", ".z", ".gz", ".xz", ".zip", ".jar", ".ipk", ".rpm".
+ ".srpm", ".deb" and ".bz2" extensions as well as various combinations
+ of tarball extensions.
+ </para>
+
+ <para>
+ As mentioned, the Git fetcher has its own unpack method that
+ is optimized to work with Git trees.
+ Basically, this method works by cloning the tree into the final
+ directory.
+ The process is completed using references so that there is
+ only one central copy of the Git metadata needed.
+ </para>
+ </section>
+
+ <section id='bb-fetchers'>
+ <title>Fetchers</title>
+
+ <para>
+ As mentioned earlier, the URL prefix determines which
+ fetcher submodule BitBake uses.
+ Each submodule can support different URL parameters,
+ which are described in the following sections.
+ </para>
+
+ <section id='local-file-fetcher'>
+ <title>Local file fetcher (<filename>file://</filename>)</title>
+
+ <para>
+ This submodule handles URLs that begin with
+ <filename>file://</filename>.
+ The filename you specify within the URL can be
+ either an absolute or relative path to a file.
+ If the filename is relative, the contents of the
+ <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
+ variable is used in the same way
+ <filename>PATH</filename> is used to find executables.
+ Failing that,
+ <link linkend='var-FILESDIR'><filename>FILESDIR</filename></link>
+ is used to find the appropriate relative file.
+ <note>
+ <filename>FILESDIR</filename> is deprecated and can
+ be replaced with <filename>FILESPATH</filename>.
+ Because <filename>FILESDIR</filename> is likely to be
+ removed, you should not use this variable in any new code.
+ </note>
+ If the file cannot be found, it is assumed that it is available in
+ <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+ by the time the <filename>download()</filename> method is called.
+ </para>
+
+ <para>
+ If you specify a directory, the entire directory is
+ unpacked.
+ </para>
+
+ <para>
+ Here are a couple of example URLs, the first relative and
+ the second absolute:
+ <literallayout class='monospaced'>
+ SRC_URI = "file://relativefile.patch"
+ SRC_URI = "file:///Users/ich/very_important_software"
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='http-ftp-fetcher'>
+ <title>HTTP/FTP wget fetcher (<filename>http://</filename>, <filename>ftp://</filename>, <filename>https://</filename>)</title>
+
+ <para>
+ This fetcher obtains files from web and FTP servers.
+ Internally, the fetcher uses the wget utility.
+ </para>
+
+ <para>
+ The executable and parameters used are specified by the
+ <filename>FETCHCMD_wget</filename> variable, which defaults
+ to sensible values.
+ The fetcher supports a parameter "downloadfilename" that
+ allows the name of the downloaded file to be specified.
+ Specifying the name of the downloaded file is useful
+ for avoiding collisions in
+ <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+ when dealing with multiple files that have the same name.
+ </para>
+
+ <para>
+ Some example URLs are as follows:
+ <literallayout class='monospaced'>
+ SRC_URI = "http://oe.handhelds.org/not_there.aac"
+ SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
+ SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"
+ </literallayout>
+ </para>
+ <note>
+ Because URL parameters are delimited by semi-colons, this can
+ introduce ambiguity when parsing URLs that also contain semi-colons,
+ for example:
+ <literallayout class='monospaced'>
+ SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47"
+ </literallayout>
+ Such URLs should should be modified by replacing semi-colons with '&' characters:
+ <literallayout class='monospaced'>
+ SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47"
+ </literallayout>
+ In most cases this should work. Treating semi-colons and '&' in queries
+ identically is recommended by the World Wide Web Consortium (W3C).
+ Note that due to the nature of the URL, you may have to specify the name
+ of the downloaded file as well:
+ <literallayout class='monospaced'>
+ SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2"
+ </literallayout>
+ </note>
+ </section>
+
+ <section id='cvs-fetcher'>
+ <title>CVS fetcher (<filename>(cvs://</filename>)</title>
+
+ <para>
+ This submodule handles checking out files from the
+ CVS version control system.
+ You can configure it using a number of different variables:
+ <itemizedlist>
+ <listitem><para><emphasis><filename>FETCHCMD_cvs</filename>:</emphasis>
+ The name of the executable to use when running
+ the <filename>cvs</filename> command.
+ This name is usually "cvs".
+ </para></listitem>
+ <listitem><para><emphasis><filename>SRCDATE</filename>:</emphasis>
+ The date to use when fetching the CVS source code.
+ A special value of "now" causes the checkout to
+ be updated on every build.
+ </para></listitem>
+ <listitem><para><emphasis><link linkend='var-CVSDIR'><filename>CVSDIR</filename></link>:</emphasis>
+ Specifies where a temporary checkout is saved.
+ The location is often <filename>DL_DIR/cvs</filename>.
+ </para></listitem>
+ <listitem><para><emphasis><filename>CVS_PROXY_HOST</filename>:</emphasis>
+ The name to use as a "proxy=" parameter to the
+ <filename>cvs</filename> command.
+ </para></listitem>
+ <listitem><para><emphasis><filename>CVS_PROXY_PORT</filename>:</emphasis>
+ The port number to use as a "proxyport=" parameter to
+ the <filename>cvs</filename> command.
+ </para></listitem>
+ </itemizedlist>
+ As well as the standard username and password URL syntax,
+ you can also configure the fetcher with various URL parameters:
+ </para>
+
+ <para>
+ The supported parameters are as follows:
+ <itemizedlist>
+ <listitem><para><emphasis>"method":</emphasis>
+ The protocol over which to communicate with the CVS server.
+ By default, this protocol is "pserver".
+ If "method" is set to "ext", BitBake examines the
+ "rsh" parameter and sets <filename>CVS_RSH</filename>.
+ You can use "dir" for local directories.
+ </para></listitem>
+ <listitem><para><emphasis>"module":</emphasis>
+ Specifies the module to check out.
+ You must supply this parameter.
+ </para></listitem>
+ <listitem><para><emphasis>"tag":</emphasis>
+ Describes which CVS TAG should be used for
+ the checkout.
+ By default, the TAG is empty.
+ </para></listitem>
+ <listitem><para><emphasis>"date":</emphasis>
+ Specifies a date.
+ If no "date" is specified, the
+ <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
+ of the configuration is used to checkout a specific date.
+ The special value of "now" causes the checkout to be
+ updated on every build.
+ </para></listitem>
+ <listitem><para><emphasis>"localdir":</emphasis>
+ Used to rename the module.
+ Effectively, you are renaming the output directory
+ to which the module is unpacked.
+ You are forcing the module into a special
+ directory relative to
+ <link linkend='var-CVSDIR'><filename>CVSDIR</filename></link>.
+ </para></listitem>
+ <listitem><para><emphasis>"rsh"</emphasis>
+ Used in conjunction with the "method" parameter.
+ </para></listitem>
+ <listitem><para><emphasis>"scmdata":</emphasis>
+ Causes the CVS metadata to be maintained in the tarball
+ the fetcher creates when set to "keep".
+ The tarball is expanded into the work directory.
+ By default, the CVS metadata is removed.
+ </para></listitem>
+ <listitem><para><emphasis>"fullpath":</emphasis>
+ Controls whether the resulting checkout is at the
+ module level, which is the default, or is at deeper
+ paths.
+ </para></listitem>
+ <listitem><para><emphasis>"norecurse":</emphasis>
+ Causes the fetcher to only checkout the specified
+ directory with no recurse into any subdirectories.
+ </para></listitem>
+ <listitem><para><emphasis>"port":</emphasis>
+ The port to which the CVS server connects.
+ </para></listitem>
+ </itemizedlist>
+ Some example URLs are as follows:
+ <literallayout class='monospaced'>
+ SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
+ SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='svn-fetcher'>
+ <title>Subversion (SVN) Fetcher (<filename>svn://</filename>)</title>
+
+ <para>
+ This fetcher submodule fetches code from the
+ Subversion source control system.
+ The executable used is specified by
+ <filename>FETCHCMD_svn</filename>, which defaults
+ to "svn".
+ The fetcher's temporary working directory is set by
+ <link linkend='var-SVNDIR'><filename>SVNDIR</filename></link>,
+ which is usually <filename>DL_DIR/svn</filename>.
+ </para>
+
+ <para>
+ The supported parameters are as follows:
+ <itemizedlist>
+ <listitem><para><emphasis>"module":</emphasis>
+ The name of the svn module to checkout.
+ You must provide this parameter.
+ You can think of this parameter as the top-level
+ directory of the repository data you want.
+ </para></listitem>
+ <listitem><para><emphasis>"protocol":</emphasis>
+ The protocol to use, which defaults to "svn".
+ Other options are "svn+ssh" and "rsh".
+ For "rsh", the "rsh" parameter is also used.
+ </para></listitem>
+ <listitem><para><emphasis>"rev":</emphasis>
+ The revision of the source code to checkout.
+ </para></listitem>
+ <listitem><para><emphasis>"date":</emphasis>
+ The date of the source code to checkout.
+ Specific revisions are generally much safer to checkout
+ rather than by date as they do not involve timezones
+ (e.g. they are much more deterministic).
+ </para></listitem>
+ <listitem><para><emphasis>"scmdata":</emphasis>
+ Causes the “.svn” directories to be available during
+ compile-time when set to "keep".
+ By default, these directories are removed.
+ </para></listitem>
+ <listitem><para><emphasis>"transportuser":</emphasis>
+ When required, sets the username for the transport.
+ By default, this parameter is empty.
+ The transport username is different than the username
+ used in the main URL, which is passed to the subversion
+ command.
+ </para></listitem>
+ </itemizedlist>
+ Following are two examples using svn:
+ <literallayout class='monospaced'>
+ SRC_URI = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
+ SRC_URI = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='git-fetcher'>
+ <title>Git Fetcher (<filename>git://</filename>)</title>
+
+ <para>
+ This fetcher submodule fetches code from the Git
+ source control system.
+ The fetcher works by creating a bare clone of the
+ remote into
+ <link linkend='var-GITDIR'><filename>GITDIR</filename></link>,
+ which is usually <filename>DL_DIR/git2</filename>.
+ This bare clone is then cloned into the work directory during the
+ unpack stage when a specific tree is checked out.
+ This is done using alternates and by reference to
+ minimize the amount of duplicate data on the disk and
+ make the unpack process fast.
+ The executable used can be set with
+ <filename>FETCHCMD_git</filename>.
+ </para>
+
+ <para>
+ This fetcher supports the following parameters:
+ <itemizedlist>
+ <listitem><para><emphasis>"protocol":</emphasis>
+ The protocol used to fetch the files.
+ The default is "git" when a hostname is set.
+ If a hostname is not set, the Git protocol is "file".
+ You can also use "http", "https", "ssh" and "rsync".
+ </para></listitem>
+ <listitem><para><emphasis>"nocheckout":</emphasis>
+ Tells the fetcher to not checkout source code when
+ unpacking when set to "1".
+ Set this option for the URL where there is a custom
+ routine to checkout code.
+ The default is "0".
+ </para></listitem>
+ <listitem><para><emphasis>"rebaseable":</emphasis>
+ Indicates that the upstream Git repository can be rebased.
+ You should set this parameter to "1" if
+ revisions can become detached from branches.
+ In this case, the source mirror tarball is done per
+ revision, which has a loss of efficiency.
+ Rebasing the upstream Git repository could cause the
+ current revision to disappear from the upstream repository.
+ This option reminds the fetcher to preserve the local cache
+ carefully for future use.
+ The default value for this parameter is "0".
+ </para></listitem>
+ <listitem><para><emphasis>"nobranch":</emphasis>
+ Tells the fetcher to not check the SHA validation
+ for the branch when set to "1".
+ The default is "0".
+ Set this option for the recipe that refers to
+ the commit that is valid for a tag instead of
+ the branch.
+ </para></listitem>
+ <listitem><para><emphasis>"bareclone":</emphasis>
+ Tells the fetcher to clone a bare clone into the
+ destination directory without checking out a working tree.
+ Only the raw Git metadata is provided.
+ This parameter implies the "nocheckout" parameter as well.
+ </para></listitem>
+ <listitem><para><emphasis>"branch":</emphasis>
+ The branch(es) of the Git tree to clone.
+ If unset, this is assumed to be "master".
+ The number of branch parameters much match the number of
+ name parameters.
+ </para></listitem>
+ <listitem><para><emphasis>"rev":</emphasis>
+ The revision to use for the checkout.
+ The default is "master".
+ </para></listitem>
+ <listitem><para><emphasis>"tag":</emphasis>
+ Specifies a tag to use for the checkout.
+ To correctly resolve tags, BitBake must access the
+ network.
+ For that reason, tags are often not used.
+ As far as Git is concerned, the "tag" parameter behaves
+ effectively the same as the "rev" parameter.
+ </para></listitem>
+ <listitem><para><emphasis>"subpath":</emphasis>
+ Limits the checkout to a specific subpath of the tree.
+ By default, the whole tree is checked out.
+ </para></listitem>
+ <listitem><para><emphasis>"destsuffix":</emphasis>
+ The name of the path in which to place the checkout.
+ By default, the path is <filename>git/</filename>.
+ </para></listitem>
+ </itemizedlist>
+ Here are some example URLs:
+ <literallayout class='monospaced'>
+ SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
+ SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='gitsm-fetcher'>
+ <title>Git Submodule Fetcher (<filename>gitsm://</filename>)</title>
+
+ <para>
+ This fetcher submodule inherits from the
+ <link linkend='git-fetcher'>Git fetcher</link> and extends
+ that fetcher's behavior by fetching a repository's submodules.
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+ is passed to the Git fetcher as described in the
+ "<link linkend='git-fetcher'>Git Fetcher (<filename>git://</filename>)</link>"
+ section.
+ <note>
+ <title>Notes and Warnings</title>
+ <para>
+ You must clean a recipe when switching between
+ '<filename>git://</filename>' and
+ '<filename>gitsm://</filename>' URLs.
+ </para>
+
+ <para>
+ The Git Submodules fetcher is not a complete fetcher
+ implementation.
+ The fetcher has known issues where it does not use the
+ normal source mirroring infrastructure properly.
+ </para>
+ </note>
+ </para>
+ </section>
+
+ <section id='clearcase-fetcher'>
+ <title>ClearCase Fetcher (<filename>ccrc://</filename>)</title>
+
+ <para>
+ This fetcher submodule fetches code from a
+ <ulink url='http://en.wikipedia.org/wiki/Rational_ClearCase'>ClearCase</ulink>
+ repository.
+ </para>
+
+ <para>
+ To use this fetcher, make sure your recipe has proper
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
+ <link linkend='var-SRCREV'><filename>SRCREV</filename></link>, and
+ <link linkend='var-PV'><filename>PV</filename></link> settings.
+ Here is an example:
+ <literallayout class='monospaced'>
+ SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
+ SRCREV = "EXAMPLE_CLEARCASE_TAG"
+ PV = "${@d.getVar("SRCREV", False).replace("/", "+")}"
+ </literallayout>
+ The fetcher uses the <filename>rcleartool</filename> or
+ <filename>cleartool</filename> remote client, depending on
+ which one is available.
+ </para>
+
+ <para>
+ Following are options for the <filename>SRC_URI</filename>
+ statement:
+ <itemizedlist>
+ <listitem><para><emphasis><filename>vob</filename></emphasis>:
+ The name, which must include the
+ prepending "/" character, of the ClearCase VOB.
+ This option is required.
+ </para></listitem>
+ <listitem><para><emphasis><filename>module</filename></emphasis>:
+ The module, which must include the
+ prepending "/" character, in the selected VOB.
+ <note>
+ The <filename>module</filename> and <filename>vob</filename>
+ options are combined to create the <filename>load</filename> rule in
+ the view config spec.
+ As an example, consider the <filename>vob</filename> and
+ <filename>module</filename> values from the
+ <filename>SRC_URI</filename> statement at the start of this section.
+ Combining those values results in the following:
+ <literallayout class='monospaced'>
+ load /example_vob/example_module
+ </literallayout>
+ </note>
+ </para></listitem>
+ <listitem><para><emphasis><filename>proto</filename></emphasis>:
+ The protocol, which can be either <filename>http</filename> or
+ <filename>https</filename>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ By default, the fetcher creates a configuration specification.
+ If you want this specification written to an area other than the default,
+ use the <filename>CCASE_CUSTOM_CONFIG_SPEC</filename> variable
+ in your recipe to define where the specification is written.
+ <note>
+ the <filename>SRCREV</filename> loses its functionality if you
+ specify this variable.
+ However, <filename>SRCREV</filename> is still used to label the
+ archive after a fetch even though it does not define what is
+ fetched.
+ </note>
+ </para>
+
+ <para>
+ Here are a couple of other behaviors worth mentioning:
+ <itemizedlist>
+ <listitem><para>
+ When using <filename>cleartool</filename>, the login of
+ <filename>cleartool</filename> is handled by the system.
+ The login require no special steps.
+ </para></listitem>
+ <listitem><para>
+ In order to use <filename>rcleartool</filename> with authenticated
+ users, an "rcleartool login" is necessary before using the fetcher.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='other-fetchers'>
+ <title>Other Fetchers</title>
+
+ <para>
+ Fetch submodules also exist for the following:
+ <itemizedlist>
+ <listitem><para>
+ Bazaar (<filename>bzr://</filename>)
+ </para></listitem>
+ <listitem><para>
+ Perforce (<filename>p4://</filename>)
+ </para></listitem>
+ <listitem><para>
+ Trees using Git Annex (<filename>gitannex://</filename>)
+ </para></listitem>
+ <listitem><para>
+ Secure FTP (<filename>sftp://</filename>)
+ </para></listitem>
+ <listitem><para>
+ Secure Shell (<filename>ssh://</filename>)
+ </para></listitem>
+ <listitem><para>
+ Repo (<filename>repo://</filename>)
+ </para></listitem>
+ <listitem><para>
+ OSC (<filename>osc://</filename>)
+ </para></listitem>
+ <listitem><para>
+ Mercurial (<filename>hg://</filename>)
+ </para></listitem>
+ </itemizedlist>
+ No documentation currently exists for these lesser used
+ fetcher submodules.
+ However, you might find the code helpful and readable.
+ </para>
+ </section>
+ </section>
+
+ <section id='auto-revisions'>
+ <title>Auto Revisions</title>
+
+ <para>
+ We need to document <filename>AUTOREV</filename> and
+ <filename>SRCREV_FORMAT</filename> here.
+ </para>
+ </section>
+</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml
new file mode 100644
index 0000000..f3628cf
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml
@@ -0,0 +1,506 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<appendix id='hello-world-example'>
+ <title>Hello World Example</title>
+
+ <section id='bitbake-hello-world'>
+ <title>BitBake Hello World</title>
+
+ <para>
+ The simplest example commonly used to demonstrate any new
+ programming language or tool is the
+ "<ulink url="http://en.wikipedia.org/wiki/Hello_world_program">Hello World</ulink>"
+ example.
+ This appendix demonstrates, in tutorial form, Hello
+ World within the context of BitBake.
+ The tutorial describes how to create a new project
+ and the applicable metadata files necessary to allow
+ BitBake to build it.
+ </para>
+ </section>
+
+ <section id='example-obtaining-bitbake'>
+ <title>Obtaining BitBake</title>
+
+ <para>
+ See the
+ "<link linkend='obtaining-bitbake'>Obtaining BitBake</link>"
+ section for information on how to obtain BitBake.
+ Once you have the source code on your machine, the BitBake directory
+ appears as follows:
+ <literallayout class='monospaced'>
+ $ ls -al
+ total 100
+ drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 .
+ drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 ..
+ -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS
+ drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin
+ drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build
+ -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
+ drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes
+ drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf
+ drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib
+ -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
+ drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc
+ -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore
+ -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER
+ drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib
+ -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in
+ -rwxrwxr-x. 1 wmat wmat 3195 Jan 31 11:57 setup.py
+ -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO
+ </literallayout>
+ </para>
+
+ <para>
+ At this point, you should have BitBake cloned to
+ a directory that matches the previous listing except for
+ dates and user names.
+ </para>
+ </section>
+
+ <section id='setting-up-the-bitbake-environment'>
+ <title>Setting Up the BitBake Environment</title>
+
+ <para>
+ First, you need to be sure that you can run BitBake.
+ Set your working directory to where your local BitBake
+ files are and run the following command:
+ <literallayout class='monospaced'>
+ $ ./bin/bitbake --version
+ BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
+ </literallayout>
+ The console output tells you what version you are running.
+ </para>
+
+ <para>
+ The recommended method to run BitBake is from a directory of your
+ choice.
+ To be able to run BitBake from any directory, you need to add the
+ executable binary to your binary to your shell's environment
+ <filename>PATH</filename> variable.
+ First, look at your current <filename>PATH</filename> variable
+ by entering the following:
+ <literallayout class='monospaced'>
+ $ echo $PATH
+ </literallayout>
+ Next, add the directory location for the BitBake binary to the
+ <filename>PATH</filename>.
+ Here is an example that adds the
+ <filename>/home/scott-lenovo/bitbake/bin</filename> directory
+ to the front of the <filename>PATH</filename> variable:
+ <literallayout class='monospaced'>
+ $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
+ </literallayout>
+ You should now be able to enter the <filename>bitbake</filename>
+ command from the command line while working from any directory.
+ </para>
+ </section>
+
+ <section id='the-hello-world-example'>
+ <title>The Hello World Example</title>
+
+ <para>
+ The overall goal of this exercise is to build a
+ complete "Hello World" example utilizing task and layer
+ concepts.
+ Because this is how modern projects such as OpenEmbedded and
+ the Yocto Project utilize BitBake, the example
+ provides an excellent starting point for understanding
+ BitBake.
+ </para>
+
+ <para>
+ To help you understand how to use BitBake to build targets,
+ the example starts with nothing but the <filename>bitbake</filename>
+ command, which causes BitBake to fail and report problems.
+ The example progresses by adding pieces to the build to
+ eventually conclude with a working, minimal "Hello World"
+ example.
+ </para>
+
+ <para>
+ While every attempt is made to explain what is happening during
+ the example, the descriptions cannot cover everything.
+ You can find further information throughout this manual.
+ Also, you can actively participate in the
+ <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'></ulink>
+ discussion mailing list about the BitBake build tool.
+ </para>
+
+ <note>
+ This example was inspired by and drew heavily from these sources:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url="http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html">Mailing List post - The BitBake equivalent of "Hello, World!"</ulink>
+ </para></listitem>
+ <listitem><para>
+ <ulink url="http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/">Hambedded Linux blog post - From Bitbake Hello World to an Image</ulink>
+ </para></listitem>
+ </itemizedlist>
+ </note>
+
+ <para>
+ As stated earlier, the goal of this example
+ is to eventually compile "Hello World".
+ However, it is unknown what BitBake needs and what you have
+ to provide in order to achieve that goal.
+ Recall that BitBake utilizes three types of metadata files:
+ <link linkend='configuration-files'>Configuration Files</link>,
+ <link linkend='classes'>Classes</link>, and
+ <link linkend='recipes'>Recipes</link>.
+ But where do they go?
+ How does BitBake find them?
+ BitBake's error messaging helps you answer these types of questions
+ and helps you better understand exactly what is going on.
+ </para>
+
+ <para>
+ Following is the complete "Hello World" example.
+ </para>
+
+ <orderedlist>
+ <listitem><para><emphasis>Create a Project Directory:</emphasis>
+ First, set up a directory for the "Hello World" project.
+ Here is how you can do so in your home directory:
+ <literallayout class='monospaced'>
+ $ mkdir ~/hello
+ $ cd ~/hello
+ </literallayout>
+ This is the directory that BitBake will use to do all of
+ its work.
+ You can use this directory to keep all the metafiles needed
+ by BitBake.
+ Having a project directory is a good way to isolate your
+ project.
+ </para></listitem>
+ <listitem><para><emphasis>Run Bitbake:</emphasis>
+ At this point, you have nothing but a project directory.
+ Run the <filename>bitbake</filename> command and see what
+ it does:
+ <literallayout class='monospaced'>
+ $ bitbake
+ The BBPATH variable is not set and bitbake did not
+ find a conf/bblayers.conf file in the expected location.
+ Maybe you accidentally invoked bitbake from the wrong directory?
+ DEBUG: Removed the following variables from the environment:
+ GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
+ GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
+ XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
+ MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
+ GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
+ XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
+ _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
+ UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
+ </literallayout>
+ The majority of this output is specific to environment variables
+ that are not directly relevant to BitBake.
+ However, the very first message regarding the
+ <filename>BBPATH</filename> variable and the
+ <filename>conf/bblayers.conf</filename> file
+ is relevant.</para>
+ <para>
+ When you run BitBake, it begins looking for metadata files.
+ The
+ <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+ variable is what tells BitBake where to look for those files.
+ <filename>BBPATH</filename> is not set and you need to set it.
+ Without <filename>BBPATH</filename>, Bitbake cannot
+ find any configuration files (<filename>.conf</filename>)
+ or recipe files (<filename>.bb</filename>) at all.
+ BitBake also cannot find the <filename>bitbake.conf</filename>
+ file.
+ </para></listitem>
+ <listitem><para><emphasis>Setting <filename>BBPATH</filename>:</emphasis>
+ For this example, you can set <filename>BBPATH</filename>
+ in the same manner that you set <filename>PATH</filename>
+ earlier in the appendix.
+ You should realize, though, that it is much more flexible to set the
+ <filename>BBPATH</filename> variable up in a configuration
+ file for each project.</para>
+ <para>From your shell, enter the following commands to set and
+ export the <filename>BBPATH</filename> variable:
+ <literallayout class='monospaced'>
+ $ BBPATH="<replaceable>projectdirectory</replaceable>"
+ $ export BBPATH
+ </literallayout>
+ Use your actual project directory in the command.
+ BitBake uses that directory to find the metadata it needs for
+ your project.
+ <note>
+ When specifying your project directory, do not use the
+ tilde ("~") character as BitBake does not expand that character
+ as the shell would.
+ </note>
+ </para></listitem>
+ <listitem><para><emphasis>Run Bitbake:</emphasis>
+ Now that you have <filename>BBPATH</filename> defined, run
+ the <filename>bitbake</filename> command again:
+ <literallayout class='monospaced'>
+ $ bitbake
+ ERROR: Traceback (most recent call last):
+ File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
+ return func(fn, *args)
+ File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
+ return bb.parse.handle(fn, data, include)
+ File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
+ return h['handle'](fn, data, include)
+ File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
+ abs_fn = resolve_file(fn, data)
+ File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
+ raise IOError("file %s not found in %s" % (fn, bbpath))
+ IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello
+
+ ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello
+ </literallayout>
+ This sample output shows that BitBake could not find the
+ <filename>conf/bitbake.conf</filename> file in the project
+ directory.
+ This file is the first thing BitBake must find in order
+ to build a target.
+ And, since the project directory for this example is
+ empty, you need to provide a <filename>conf/bitbake.conf</filename>
+ file.
+ </para></listitem>
+ <listitem><para><emphasis>Creating <filename>conf/bitbake.conf</filename>:</emphasis>
+ The <filename>conf/bitbake.conf</filename> includes a number of
+ configuration variables BitBake uses for metadata and recipe
+ files.
+ For this example, you need to create the file in your project directory
+ and define some key BitBake variables.
+ For more information on the <filename>bitbake.conf</filename>,
+ see
+ <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#an-overview-of-bitbakeconf'></ulink>
+ </para>
+ <para>Use the following commands to create the <filename>conf</filename>
+ directory in the project directory:
+ <literallayout class='monospaced'>
+ $ mkdir conf
+ </literallayout>
+ From within the <filename>conf</filename> directory, use
+ some editor to create the <filename>bitbake.conf</filename>
+ so that it contains the following:
+ <literallayout class='monospaced'>
+ TMPDIR = "${<link linkend='var-TOPDIR'>TOPDIR</link>}/tmp"
+ <link linkend='var-CACHE'>CACHE</link> = "${TMPDIR}/cache"
+ <link linkend='var-STAMP'>STAMP</link> = "${TMPDIR}/stamps"
+ <link linkend='var-T'>T</link> = "${TMPDIR}/work"
+ <link linkend='var-B'>B</link> = "${TMPDIR}"
+ </literallayout>
+ The <filename>TMPDIR</filename> variable establishes a directory
+ that BitBake uses for build output and intermediate files (other
+ than the cached information used by the
+ <link linkend='setscene'>Setscene</link> process.
+ Here, the <filename>TMPDIR</filename> directory is set to
+ <filename>hello/tmp</filename>.
+ <note><title>Tip</title>
+ You can always safely delete the <filename>tmp</filename>
+ directory in order to rebuild a BitBake target.
+ The build process creates the directory for you
+ when you run BitBake.
+ </note></para>
+ <para>For information about each of the other variables defined in this
+ example, click on the links to take you to the definitions in
+ the glossary.
+ </para></listitem>
+ <listitem><para><emphasis>Run Bitbake:</emphasis>
+ After making sure that the <filename>conf/bitbake.conf</filename>
+ file exists, you can run the <filename>bitbake</filename>
+ command again:
+ <literallayout class='monospaced'>
+$ bitbake
+ERROR: Traceback (most recent call last):
+ File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
+ return func(fn, *args)
+ File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
+ bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
+ File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
+ include(fn, file, lineno, d, "inherit")
+ File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
+ raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
+ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
+
+ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
+ </literallayout>
+ In the sample output, BitBake could not find the
+ <filename>classes/base.bbclass</filename> file.
+ You need to create that file next.
+ </para></listitem>
+ <listitem><para><emphasis>Creating <filename>classes/base.bbclass</filename>:</emphasis>
+ BitBake uses class files to provide common code and functionality.
+ The minimally required class for BitBake is the
+ <filename>classes/base.bbclass</filename> file.
+ The <filename>base</filename> class is implicitly inherited by
+ every recipe.
+ BitBake looks for the class in the <filename>classes</filename>
+ directory of the project (i.e <filename>hello/classes</filename>
+ in this example).
+ </para>
+ <para>Create the <filename>classes</filename> directory as follows:
+ <literallayout class='monospaced'>
+ $ cd $HOME/hello
+ $ mkdir classes
+ </literallayout>
+ Move to the <filename>classes</filename> directory and then
+ create the <filename>base.bbclass</filename> file by inserting
+ this single line:
+ <literallayout class='monospaced'>
+ addtask build
+ </literallayout>
+ The minimal task that BitBake runs is the
+ <filename>do_build</filename> task.
+ This is all the example needs in order to build the project.
+ Of course, the <filename>base.bbclass</filename> can have much
+ more depending on which build environments BitBake is
+ supporting.
+ For more information on the <filename>base.bbclass</filename> file,
+ you can look at
+ <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#tasks'></ulink>.
+ </para></listitem>
+ <listitem><para><emphasis>Run Bitbake:</emphasis>
+ After making sure that the <filename>classes/base.bbclass</filename>
+ file exists, you can run the <filename>bitbake</filename>
+ command again:
+ <literallayout class='monospaced'>
+ $ bitbake
+ Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
+ </literallayout>
+ BitBake is finally reporting no errors.
+ However, you can see that it really does not have anything
+ to do.
+ You need to create a recipe that gives BitBake something to do.
+ </para></listitem>
+ <listitem><para><emphasis>Creating a Layer:</emphasis>
+ While it is not really necessary for such a small example,
+ it is good practice to create a layer in which to keep your
+ code separate from the general metadata used by BitBake.
+ Thus, this example creates and uses a layer called "mylayer".
+ <note>
+ You can find additional information on adding a layer at
+ <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#adding-an-example-layer'></ulink>.
+ </note>
+ </para>
+ <para>Minimally, you need a recipe file and a layer configuration
+ file in your layer.
+ The configuration file needs to be in the <filename>conf</filename>
+ directory inside the layer.
+ Use these commands to set up the layer and the <filename>conf</filename>
+ directory:
+ <literallayout class='monospaced'>
+ $ cd $HOME
+ $ mkdir mylayer
+ $ cd mylayer
+ $ mkdir conf
+ </literallayout>
+ Move to the <filename>conf</filename> directory and create a
+ <filename>layer.conf</filename> file that has the following:
+ <literallayout class='monospaced'>
+ BBPATH .= ":${<link linkend='var-LAYERDIR'>LAYERDIR</link>}"
+
+ <link linkend='var-BBFILES'>BBFILES</link> += "${LAYERDIR}/*.bb"
+
+ <link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link> += "mylayer"
+ <link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN_mylayer</link> := "^${LAYERDIR}/"
+ </literallayout>
+ For information on these variables, click the links
+ to go to the definitions in the glossary.</para>
+ <para>You need to create the recipe file next.
+ Inside your layer at the top-level, use an editor and create
+ a recipe file named <filename>printhello.bb</filename> that
+ has the following:
+ <literallayout class='monospaced'>
+ <link linkend='var-DESCRIPTION'>DESCRIPTION</link> = "Prints Hello World"
+ <link linkend='var-PN'>PN</link> = 'printhello'
+ <link linkend='var-PV'>PV</link> = '1'
+
+ python do_build() {
+ bb.plain("********************");
+ bb.plain("* *");
+ bb.plain("* Hello, World! *");
+ bb.plain("* *");
+ bb.plain("********************");
+ }
+ </literallayout>
+ The recipe file simply provides a description of the
+ recipe, the name, version, and the <filename>do_build</filename>
+ task, which prints out "Hello World" to the console.
+ For more information on these variables, follow the links
+ to the glossary.
+ </para></listitem>
+ <listitem><para><emphasis>Run Bitbake With a Target:</emphasis>
+ Now that a BitBake target exists, run the command and provide
+ that target:
+ <literallayout class='monospaced'>
+ $ cd $HOME/hello
+ $ bitbake printhello
+ ERROR: no recipe files to build, check your BBPATH and BBFILES?
+
+ Summary: There was 1 ERROR message shown, returning a non-zero exit code.
+ </literallayout>
+ We have created the layer with the recipe and the layer
+ configuration file but it still seems that BitBake cannot
+ find the recipe.
+ BitBake needs a <filename>conf/bblayers.conf</filename> that
+ lists the layers for the project.
+ Without this file, BitBake cannot find the recipe.
+ </para></listitem>
+ <listitem><para><emphasis>Creating <filename>conf/bblayers.conf</filename>:</emphasis>
+ BitBake uses the <filename>conf/bblayers.conf</filename> file
+ to locate layers needed for the project.
+ This file must reside in the <filename>conf</filename> directory
+ of the project (i.e. <filename>hello/conf</filename> for this
+ example).</para>
+ <para>Set your working directory to the <filename>hello/conf</filename>
+ directory and then create the <filename>bblayers.conf</filename>
+ file so that it contains the following:
+ <literallayout class='monospaced'>
+ BBLAYERS ?= " \
+ /home/<you>/mylayer \
+ "
+ </literallayout>
+ You need to provide your own information for
+ <filename>you</filename> in the file.
+ </para></listitem>
+ <listitem><para><emphasis>Run Bitbake With a Target:</emphasis>
+ Now that you have supplied the <filename>bblayers.conf</filename>
+ file, run the <filename>bitbake</filename> command and provide
+ the target:
+ <literallayout class='monospaced'>
+ $ bitbake printhello
+ Parsing recipes: 100% |##################################################################################|
+ Time: 00:00:00
+ Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
+ NOTE: Resolving any missing task queue dependencies
+ NOTE: Preparing RunQueue
+ NOTE: Executing RunQueue Tasks
+ ********************
+ * *
+ * Hello, World! *
+ * *
+ ********************
+ NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
+ </literallayout>
+ BitBake finds the <filename>printhello</filename> recipe and
+ successfully runs the task.
+ <note>
+ After the first execution, re-running
+ <filename>bitbake printhello</filename> again will not
+ result in a BitBake run that prints the same console
+ output.
+ The reason for this is that the first time the
+ <filename>printhello.bb</filename> recipe's
+ <filename>do_build</filename> task executes
+ successfully, BitBake writes a stamp file for the task.
+ Thus, the next time you attempt to run the task
+ using that same <filename>bitbake</filename> command,
+ BitBake notices the stamp and therefore determines
+ that the task does not need to be re-run.
+ If you delete the <filename>tmp</filename> directory
+ or run <filename>bitbake -c clean printhello</filename>
+ and then re-run the build, the "Hello, World!" message will
+ be printed again.
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </section>
+</appendix>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml
new file mode 100644
index 0000000..2188655
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml
@@ -0,0 +1,685 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="bitbake-user-manual-intro">
+ <title>Overview</title>
+
+ <para>
+ Welcome to the BitBake User Manual.
+ This manual provides information on the BitBake tool.
+ The information attempts to be as independent as possible regarding
+ systems that use BitBake, such as OpenEmbedded and the
+ Yocto Project.
+ In some cases, scenarios or examples within the context of
+ a build system are used in the manual to help with understanding.
+ For these cases, the manual clearly states the context.
+ </para>
+
+ <section id="intro">
+ <title>Introduction</title>
+
+ <para>
+ Fundamentally, BitBake is a generic task execution
+ engine that allows shell and Python tasks to be run
+ efficiently and in parallel while working within
+ complex inter-task dependency constraints.
+ One of BitBake's main users, OpenEmbedded, takes this core
+ and builds embedded Linux software stacks using
+ a task-oriented approach.
+ </para>
+
+ <para>
+ Conceptually, BitBake is similar to GNU Make in
+ some regards but has significant differences:
+ <itemizedlist>
+ <listitem><para>
+ BitBake executes tasks according to provided
+ metadata that builds up the tasks.
+ Metadata is stored in recipe (<filename>.bb</filename>)
+ and related recipe "append" (<filename>.bbappend</filename>)
+ files, configuration (<filename>.conf</filename>) and
+ underlying include (<filename>.inc</filename>) files, and
+ in class (<filename>.bbclass</filename>) files.
+ The metadata provides
+ BitBake with instructions on what tasks to run and
+ the dependencies between those tasks.
+ </para></listitem>
+ <listitem><para>
+ BitBake includes a fetcher library for obtaining source
+ code from various places such as local files, source control
+ systems, or websites.
+ </para></listitem>
+ <listitem><para>
+ The instructions for each unit to be built (e.g. a piece
+ of software) are known as "recipe" files and
+ contain all the information about the unit
+ (dependencies, source file locations, checksums, description
+ and so on).
+ </para></listitem>
+ <listitem><para>
+ BitBake includes a client/server abstraction and can
+ be used from a command line or used as a service over
+ XML-RPC and has several different user interfaces.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="history-and-goals">
+ <title>History and Goals</title>
+
+ <para>
+ BitBake was originally a part of the OpenEmbedded project.
+ It was inspired by the Portage package management system
+ used by the Gentoo Linux distribution.
+ On December 7, 2004, OpenEmbedded project team member
+ Chris Larson split the project into two distinct pieces:
+ <itemizedlist>
+ <listitem><para>BitBake, a generic task executor</para></listitem>
+ <listitem><para>OpenEmbedded, a metadata set utilized by
+ BitBake</para></listitem>
+ </itemizedlist>
+ Today, BitBake is the primary basis of the
+ <ulink url="http://www.openembedded.org/">OpenEmbedded</ulink>
+ project, which is being used to build and maintain Linux
+ distributions such as the
+ <ulink url='http://www.angstrom-distribution.org/'>Angstrom Distribution</ulink>,
+ and which is also being used as the build tool for Linux projects
+ such as the
+ <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>.
+ </para>
+
+ <para>
+ Prior to BitBake, no other build tool adequately met the needs of
+ an aspiring embedded Linux distribution.
+ All of the build systems used by traditional desktop Linux
+ distributions lacked important functionality, and none of the
+ ad hoc Buildroot-based systems, prevalent in the
+ embedded space, were scalable or maintainable.
+ </para>
+
+ <para>
+ Some important original goals for BitBake were:
+ <itemizedlist>
+ <listitem><para>
+ Handle cross-compilation.
+ </para></listitem>
+ <listitem><para>
+ Handle inter-package dependencies (build time on
+ target architecture, build time on native
+ architecture, and runtime).
+ </para></listitem>
+ <listitem><para>
+ Support running any number of tasks within a given
+ package, including, but not limited to, fetching
+ upstream sources, unpacking them, patching them,
+ configuring them, and so forth.
+ </para></listitem>
+ <listitem><para>
+ Be Linux distribution agnostic for both build and
+ target systems.
+ </para></listitem>
+ <listitem><para>
+ Be architecture agnostic.
+ </para></listitem>
+ <listitem><para>
+ Support multiple build and target operating systems
+ (e.g. Cygwin, the BSDs, and so forth).
+ </para></listitem>
+ <listitem><para>
+ Be self contained, rather than tightly
+ integrated into the build machine's root
+ filesystem.
+ </para></listitem>
+ <listitem><para>
+ Handle conditional metadata on the target architecture,
+ operating system, distribution, and machine.
+ </para></listitem>
+ <listitem><para>
+ Be easy to use the tools to supply local metadata and packages
+ against which to operate.
+ </para></listitem>
+ <listitem><para>
+ Be easy to use BitBake to collaborate between multiple
+ projects for their builds.
+ </para></listitem>
+ <listitem><para>
+ Provide an inheritance mechanism to share
+ common metadata between many packages.
+ </para></listitem>
+ </itemizedlist>
+ Over time it became apparent that some further requirements
+ were necessary:
+ <itemizedlist>
+ <listitem><para>
+ Handle variants of a base recipe (e.g. native, sdk,
+ and multilib).
+ </para></listitem>
+ <listitem><para>
+ Split metadata into layers and allow layers
+ to enhance or override other layers.
+ </para></listitem>
+ <listitem><para>
+ Allow representation of a given set of input variables
+ to a task as a checksum.
+ Based on that checksum, allow acceleration of builds
+ with prebuilt components.
+ </para></listitem>
+ </itemizedlist>
+ BitBake satisfies all the original requirements and many more
+ with extensions being made to the basic functionality to
+ reflect the additional requirements.
+ Flexibility and power have always been the priorities.
+ BitBake is highly extensible and supports embedded Python code and
+ execution of any arbitrary tasks.
+ </para>
+ </section>
+
+ <section id="Concepts">
+ <title>Concepts</title>
+
+ <para>
+ BitBake is a program written in the Python language.
+ At the highest level, BitBake interprets metadata, decides
+ what tasks are required to run, and executes those tasks.
+ Similar to GNU Make, BitBake controls how software is
+ built.
+ GNU Make achieves its control through "makefiles", while
+ BitBake uses "recipes".
+ </para>
+
+ <para>
+ BitBake extends the capabilities of a simple
+ tool like GNU Make by allowing for the definition of much more
+ complex tasks, such as assembling entire embedded Linux
+ distributions.
+ </para>
+
+ <para>
+ The remainder of this section introduces several concepts
+ that should be understood in order to better leverage
+ the power of BitBake.
+ </para>
+
+ <section id='recipes'>
+ <title>Recipes</title>
+
+ <para>
+ BitBake Recipes, which are denoted by the file extension
+ <filename>.bb</filename>, are the most basic metadata files.
+ These recipe files provide BitBake with the following:
+ <itemizedlist>
+ <listitem><para>Descriptive information about the
+ package (author, homepage, license, and so on)</para></listitem>
+ <listitem><para>The version of the recipe</para></listitem>
+ <listitem><para>Existing dependencies (both build
+ and runtime dependencies)</para></listitem>
+ <listitem><para>Where the source code resides and
+ how to fetch it</para></listitem>
+ <listitem><para>Whether the source code requires
+ any patches, where to find them, and how to apply
+ them</para></listitem>
+ <listitem><para>How to configure and compile the
+ source code</para></listitem>
+ <listitem><para>Where on the target machine to install the
+ package or packages created</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Within the context of BitBake, or any project utilizing BitBake
+ as its build system, files with the <filename>.bb</filename>
+ extension are referred to as recipes.
+ <note>
+ The term "package" is also commonly used to describe recipes.
+ However, since the same word is used to describe packaged
+ output from a project, it is best to maintain a single
+ descriptive term - "recipes".
+ Put another way, a single "recipe" file is quite capable
+ of generating a number of related but separately installable
+ "packages".
+ In fact, that ability is fairly common.
+ </note>
+ </para>
+ </section>
+
+ <section id='configuration-files'>
+ <title>Configuration Files</title>
+
+ <para>
+ Configuration files, which are denoted by the
+ <filename>.conf</filename> extension, define
+ various configuration variables that govern the project's build
+ process.
+ These files fall into several areas that define
+ machine configuration options, distribution configuration
+ options, compiler tuning options, general common
+ configuration options, and user configuration options.
+ The main configuration file is the sample
+ <filename>bitbake.conf</filename> file, which is
+ located within the BitBake source tree
+ <filename>conf</filename> directory.
+ </para>
+ </section>
+
+ <section id='classes'>
+ <title>Classes</title>
+
+ <para>
+ Class files, which are denoted by the
+ <filename>.bbclass</filename> extension, contain
+ information that is useful to share between metadata files.
+ The BitBake source tree currently comes with one class metadata file
+ called <filename>base.bbclass</filename>.
+ You can find this file in the
+ <filename>classes</filename> directory.
+ The <filename>base.bbclass</filename> class files is special since it
+ is always included automatically for all recipes
+ and classes.
+ This class contains definitions for standard basic tasks such
+ as fetching, unpacking, configuring (empty by default),
+ compiling (runs any Makefile present), installing (empty by
+ default) and packaging (empty by default).
+ These tasks are often overridden or extended by other classes
+ added during the project development process.
+ </para>
+ </section>
+
+ <section id='layers'>
+ <title>Layers</title>
+
+ <para>
+ Layers allow you to isolate different types of
+ customizations from each other.
+ 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 you can use layers to keep things modular,
+ consider customizations you might make to support a specific target machine.
+ These types of customizations typically reside in a special layer,
+ rather than a general layer, called a Board Support Package (BSP)
+ Layer.
+ Furthermore, the machine customizations should be isolated from
+ 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.
+ 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.
+ </para>
+ </section>
+
+ <section id='append-bbappend-files'>
+ <title>Append Files</title>
+
+ <para>
+ Append files, which are files that have the
+ <filename>.bbappend</filename> file extension, extend or
+ override information in an existing recipe file.
+ </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 extends or
+ overrides the information in the underlying,
+ similarly-named recipe files.
+ </para>
+
+ <para>
+ When you name an append file, you can use the
+ wildcard character (%) to allow for matching recipe names.
+ For example, suppose you have an append file named
+ as follows:
+ <literallayout class='monospaced'>
+ busybox_1.21.%.bbappend
+ </literallayout>
+ That append file would match any <filename>busybox_1.21.x.bb</filename>
+ version of the recipe.
+ So, the append file would match the following recipe names:
+ <literallayout class='monospaced'>
+ busybox_1.21.1.bb
+ busybox_1.21.2.bb
+ busybox_1.21.3.bb
+ </literallayout>
+ If the <filename>busybox</filename> recipe was updated to
+ <filename>busybox_1.3.0.bb</filename>, the append name would not
+ match.
+ However, if you named the append file
+ <filename>busybox_1.%.bbappend</filename>, then you would have a match.
+ </para>
+
+ <para>
+ In the most general case, you could name the append file something as
+ simple as <filename>busybox_%.bbappend</filename> to be entirely
+ version independent.
+ </para>
+ </section>
+ </section>
+
+ <section id='obtaining-bitbake'>
+ <title>Obtaining BitBake</title>
+
+ <para>
+ You can obtain BitBake several different ways:
+ <itemizedlist>
+ <listitem><para><emphasis>Cloning BitBake:</emphasis>
+ Using Git to clone the BitBake source code repository
+ is the recommended method for obtaining BitBake.
+ Cloning the repository makes it easy to get bug fixes
+ and have access to stable branches and the master
+ branch.
+ Once you have cloned BitBake, you should use
+ the latest stable
+ branch for development since the master branch is for
+ BitBake development and might contain less stable changes.
+ </para>
+ <para>You usually need a version of BitBake
+ that matches the metadata you are using.
+ The metadata is generally backwards compatible but
+ not forward compatible.</para>
+ <para>Here is an example that clones the BitBake repository:
+ <literallayout class='monospaced'>
+ $ git clone git://git.openembedded.org/bitbake
+ </literallayout>
+ This command clones the BitBake Git repository into a
+ directory called <filename>bitbake</filename>.
+ Alternatively, you can
+ designate a directory after the
+ <filename>git clone</filename> command
+ if you want to call the new directory something
+ other than <filename>bitbake</filename>.
+ Here is an example that names the directory
+ <filename>bbdev</filename>:
+ <literallayout class='monospaced'>
+ $ git clone git://git.openembedded.org/bitbake bbdev
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Installation using your Distribution
+ Package Management System:</emphasis>
+ This method is not
+ recommended because the BitBake version that is
+ provided by your distribution, in most cases,
+ is several
+ releases behind a snapshot of the BitBake repository.
+ </para></listitem>
+ <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
+ Downloading a snapshot of BitBake from the
+ source code repository gives you access to a known
+ branch or release of BitBake.
+ <note>
+ Cloning the Git repository, as described earlier,
+ is the preferred method for getting BitBake.
+ Cloning the repository makes it easier to update as
+ patches are added to the stable branches.
+ </note></para>
+ <para>The following example downloads a snapshot of
+ BitBake version 1.17.0:
+ <literallayout class='monospaced'>
+ $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
+ $ tar zxpvf bitbake-1.17.0.tar.gz
+ </literallayout>
+ After extraction of the tarball using the tar utility,
+ you have a directory entitled
+ <filename>bitbake-1.17.0</filename>.
+ </para></listitem>
+ <listitem><para><emphasis>Using the BitBake that Comes With Your
+ Build Checkout:</emphasis>
+ A final possibility for getting a copy of BitBake is that it
+ already comes with your checkout of a larger Bitbake-based build
+ system, such as Poky or Yocto Project.
+ Rather than manually checking out individual layers and
+ gluing them together yourself, you can check
+ out an entire build system.
+ The checkout will already include a version of BitBake that
+ has been thoroughly tested for compatibility with the other
+ components.
+ For information on how to check out a particular BitBake-based
+ build system, consult that build system's supporting documentation.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="bitbake-user-manual-command">
+ <title>The BitBake Command</title>
+
+ <para>
+ The <filename>bitbake</filename> command is the primary interface
+ to the BitBake tool.
+ This section presents the BitBake command syntax and provides
+ several execution examples.
+ </para>
+
+ <section id='usage-and-syntax'>
+ <title>Usage and syntax</title>
+
+ <para>
+ Following is the usage and syntax for BitBake:
+ <literallayout class='monospaced'>
+ $ bitbake -h
+ Usage: bitbake [options] [recipename/target ...]
+
+ Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
+ It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
+ will provide the layer, BBFILES and other configuration information.
+
+ Options:
+ --version show program's version number and exit
+ -h, --help show this help message and exit
+ -b BUILDFILE, --buildfile=BUILDFILE
+ Execute tasks from a specific .bb recipe directly.
+ WARNING: Does not handle any dependencies from other
+ recipes.
+ -k, --continue Continue as much as possible after an error. While the
+ target that failed and anything depending on it cannot
+ be built, as much as possible will be built before
+ stopping.
+ -a, --tryaltconfigs Continue with builds by trying to use alternative
+ providers where possible.
+ -f, --force Force the specified targets/task to run (invalidating
+ any existing stamp file).
+ -c CMD, --cmd=CMD Specify the task to execute. The exact options
+ available depend on the metadata. Some examples might
+ be 'compile' or 'populate_sysroot' or 'listtasks' may
+ give a list of the tasks available.
+ -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
+ Invalidate the stamp for the specified task such as
+ 'compile' and then run the default task for the
+ specified target(s).
+ -r PREFILE, --read=PREFILE
+ Read the specified file before bitbake.conf.
+ -R POSTFILE, --postread=POSTFILE
+ Read the specified file after bitbake.conf.
+ -v, --verbose Output more log message data to the terminal.
+ -D, --debug Increase the debug level. You can specify this more
+ than once.
+ -n, --dry-run Don't execute, just go through the motions.
+ -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
+ Dump out the signature construction information, with
+ no task execution. The SIGNATURE_HANDLER parameter is
+ passed to the handler. Two common values are none and
+ printdiff but the handler may define more/less. none
+ means only dump the signature, printdiff means compare
+ the dumped signature with the cached one.
+ -p, --parse-only Quit after parsing the BB recipes.
+ -s, --show-versions Show current and preferred versions of all recipes.
+ -e, --environment Show the global or per-recipe environment complete
+ with information about where variables were
+ set/changed.
+ -g, --graphviz Save dependency tree information for the specified
+ targets in the dot syntax.
+ -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
+ Assume these dependencies don't exist and are already
+ provided (equivalent to ASSUME_PROVIDED). Useful to
+ make dependency graphs more appealing
+ -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
+ Show debug logging for the specified logging domains
+ -P, --profile Profile the command and save reports.
+ -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp).
+ -t SERVERTYPE, --servertype=SERVERTYPE
+ Choose which server to use, process or xmlrpc.
+ --token=XMLRPCTOKEN Specify the connection token to be used when
+ connecting to a remote server.
+ --revisions-changed Set the exit code depending on whether upstream
+ floating revisions have changed or not.
+ --server-only Run bitbake without a UI, only starting a server
+ (cooker) process.
+ -B BIND, --bind=BIND The name/address for the bitbake server to bind to.
+ --no-setscene Do not run any setscene tasks. sstate will be ignored
+ and everything needed, built.
+ --remote-server=REMOTE_SERVER
+ Connect to the specified server.
+ -m, --kill-server Terminate the remote server.
+ --observe-only Connect to a server as an observing-only client.
+ --status-only Check the status of the remote bitbake server.
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='bitbake-examples'>
+ <title>Examples</title>
+
+ <para>
+ This section presents some examples showing how to use BitBake.
+ </para>
+
+ <section id='example-executing-a-task-against-a-single-recipe'>
+ <title>Executing a Task Against a Single Recipe</title>
+
+ <para>
+ Executing tasks for a single recipe file is relatively simple.
+ You specify the file in question, and BitBake parses
+ it and executes the specified task.
+ If you do not specify a task, BitBake executes the default
+ task, which is "build”.
+ BitBake obeys inter-task dependencies when doing
+ so.
+ </para>
+
+ <para>
+ The following command runs the build task, which is
+ the default task, on the <filename>foo_1.0.bb</filename>
+ recipe file:
+ <literallayout class='monospaced'>
+ $ bitbake -b foo_1.0.bb
+ </literallayout>
+ The following command runs the clean task on the
+ <filename>foo.bb</filename> recipe file:
+ <literallayout class='monospaced'>
+ $ bitbake -b foo.bb -c clean
+ </literallayout>
+ <note>
+ The "-b" option explicitly does not handle recipe
+ dependencies.
+ Other than for debugging purposes, it is instead
+ recommended that you use the syntax presented in the
+ next section.
+ </note>
+ </para>
+ </section>
+
+ <section id='executing-tasks-against-a-set-of-recipe-files'>
+ <title>Executing Tasks Against a Set of Recipe Files</title>
+
+ <para>
+ There are a number of additional complexities introduced
+ when one wants to manage multiple <filename>.bb</filename>
+ files.
+ Clearly there needs to be a way to tell BitBake what
+ files are available and, of those, which you
+ want to execute.
+ There also needs to be a way for each recipe
+ to express its dependencies, both for build-time and
+ runtime.
+ There must be a way for you to express recipe preferences
+ when multiple recipes provide the same functionality, or when
+ there are multiple versions of a recipe.
+ </para>
+
+ <para>
+ The <filename>bitbake</filename> command, when not using
+ "--buildfile" or "-b" only accepts a "PROVIDES".
+ You cannot provide anything else.
+ By default, a recipe file generally "PROVIDES" its
+ "packagename" as shown in the following example:
+ <literallayout class='monospaced'>
+ $ bitbake foo
+ </literallayout>
+ This next example "PROVIDES" the package name and also uses
+ the "-c" option to tell BitBake to just execute the
+ <filename>do_clean</filename> task:
+ <literallayout class='monospaced'>
+ $ bitbake -c clean foo
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='generating-dependency-graphs'>
+ <title>Generating Dependency Graphs</title>
+
+ <para>
+ BitBake is able to generate dependency graphs using
+ the <filename>dot</filename> syntax.
+ You can convert these graphs into images using the
+ <filename>dot</filename> tool from
+ <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
+ </para>
+
+ <para>
+ When you generate a dependency graph, BitBake writes four files
+ to the current working directory:
+ <itemizedlist>
+ <listitem><para><emphasis><filename>package-depends.dot</filename>:</emphasis>
+ Shows BitBake's knowledge of dependencies between
+ runtime targets.
+ </para></listitem>
+ <listitem><para><emphasis><filename>pn-depends.dot</filename>:</emphasis>
+ Shows dependencies between build-time targets
+ (i.e. recipes).
+ </para></listitem>
+ <listitem><para><emphasis><filename>task-depends.dot</filename>:</emphasis>
+ Shows dependencies between tasks.
+ </para></listitem>
+ <listitem><para><emphasis><filename>pn-buildlist</filename>:</emphasis>
+ Shows a simple list of targets that are to be built.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ To stop depending on common depends, use the "-I" depend
+ option and BitBake omits them from the graph.
+ Leaving this information out can produce more readable graphs.
+ This way, you can remove from the graph
+ <filename>DEPENDS</filename> from inherited classes
+ such as <filename>base.bbclass</filename>.
+ </para>
+
+ <para>
+ Here are two examples that create dependency graphs.
+ The second example omits depends common in OpenEmbedded from
+ the graph:
+ <literallayout class='monospaced'>
+ $ bitbake -g foo
+
+ $ bitbake -g -I virtual/kernel -I eglibc foo
+ </literallayout>
+ </para>
+ </section>
+ </section>
+ </section>
+</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
new file mode 100644
index 0000000..1b9d800
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -0,0 +1,1830 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="bitbake-user-manual-metadata">
+ <title>Syntax and Operators</title>
+
+ <para>
+ Bitbake files have their own syntax.
+ The syntax has similarities to several
+ other languages but also has some unique features.
+ This section describes the available syntax and operators
+ as well as provides examples.
+ </para>
+
+ <section id='basic-syntax'>
+ <title>Basic Syntax</title>
+
+ <para>
+ This section provides some basic syntax examples.
+ </para>
+
+ <section id='basic-variable-setting'>
+ <title>Basic Variable Setting</title>
+
+ <para>
+ The following example sets <filename>VARIABLE</filename> to
+ "value".
+ This assignment occurs immediately as the statement is parsed.
+ It is a "hard" assignment.
+ <literallayout class='monospaced'>
+ VARIABLE = "value"
+ </literallayout>
+ As expected, if you include leading or trailing spaces as part of
+ an assignment, the spaces are retained:
+ <literallayout class='monospaced'>
+ VARIABLE = " value"
+ VARIABLE = "value "
+ </literallayout>
+ Setting <filename>VARIABLE</filename> to "" sets it to an empty string,
+ while setting the variable to " " sets it to a blank space
+ (i.e. these are not the same values).
+ <literallayout class='monospaced'>
+ VARIABLE = ""
+ VARIABLE = " "
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='variable-expansion'>
+ <title>Variable Expansion</title>
+
+ <para>
+ BitBake supports variables referencing one another's
+ contents using a syntax that is similar to shell scripting.
+ Following is an example that results in <filename>A</filename>
+ containing "aval" and <filename>B</filename> evaluating to
+ "preavalpost" based on that current value of
+ <filename>A</filename>.
+ <literallayout class='monospaced'>
+ A = "aval"
+ B = "pre${A}post"
+ </literallayout>
+ You should realize that whenever <filename>B</filename> is
+ referenced, its evaluation will depend on the state of
+ <filename>A</filename> at that time.
+ Thus, later evaluations of <filename>B</filename> in the
+ previous example could result in different values
+ depending on the value of <filename>A</filename>.
+ </para>
+ </section>
+
+ <section id='setting-a-default-value'>
+ <title>Setting a default value (?=)</title>
+
+ <para>
+ You can use the "?=" operator to achieve a "softer" assignment
+ for a variable.
+ This type of assignment allows you to define a variable if it
+ is undefined when the statement is parsed, but to leave the
+ value alone if the variable has a value.
+ Here is an example:
+ <literallayout class='monospaced'>
+ A ?= "aval"
+ </literallayout>
+ If <filename>A</filename> is set at the time this statement is parsed,
+ the variable retains its value.
+ However, if <filename>A</filename> is not set,
+ the variable is set to "aval".
+ <note>
+ This assignment is immediate.
+ Consequently, if multiple "?=" assignments
+ to a single variable exist, the first of those ends up getting
+ used.
+ </note>
+ </para>
+ </section>
+
+ <section id='setting-a-weak-default-value'>
+ <title>Setting a weak default value (??=)</title>
+
+ <para>
+ It is possible to use a "weaker" assignment than in the
+ previous section by using the "??=" operator.
+ This assignment behaves identical to "?=" except that the
+ assignment is made at the end of the parsing process rather
+ than immediately.
+ Consequently, when multiple "??=" assignments exist, the last
+ one is used.
+ Also, any "=" or "?=" assignment will override the value set with
+ "??=".
+ Here is an example:
+ <literallayout class='monospaced'>
+ A ??= "somevalue"
+ A ??= "someothervalue"
+ </literallayout>
+ If <filename>A</filename> is set before the above statements are parsed,
+ the variable retains its value.
+ If <filename>A</filename> is not set,
+ the variable is set to "someothervalue".
+ </para>
+
+ <para>
+ Again, this assignment is a "lazy" or "weak" assignment
+ because it does not occur until the end
+ of the parsing process.
+ </para>
+ </section>
+
+ <section id='immediate-variable-expansion'>
+ <title>Immediate variable expansion (:=)</title>
+
+ <para>
+ The ":=" operator results in a variable's
+ contents being expanded immediately,
+ rather than when the variable is actually used:
+ <literallayout class='monospaced'>
+ T = "123"
+ A := "${B} ${A} test ${T}"
+ T = "456"
+ B = "${T} bval"
+ C = "cval"
+ C := "${C}append"
+ </literallayout>
+ In this example, <filename>A</filename> contains
+ "test 123" because <filename>${B}</filename> and
+ <filename>${A}</filename> at the time of parsing are undefined,
+ which leaves "test 123".
+ And, the variable <filename>C</filename>
+ contains "cvalappend" since <filename>${C}</filename> immediately
+ expands to "cval".
+ </para>
+ </section>
+
+ <section id='appending-and-prepending'>
+ <title>Appending (+=) and prepending (=+) With Spaces</title>
+
+ <para>
+ Appending and prepending values is common and can be accomplished
+ using the "+=" and "=+" operators.
+ These operators insert a space between the current
+ value and prepended or appended value.
+ </para>
+
+ <para>
+ These operators take immediate effect during parsing.
+ Here are some examples:
+ <literallayout class='monospaced'>
+ B = "bval"
+ B += "additionaldata"
+ C = "cval"
+ C =+ "test"
+ </literallayout>
+ The variable <filename>B</filename> contains
+ "bval additionaldata" and <filename>C</filename>
+ contains "test cval".
+ </para>
+ </section>
+
+ <section id='appending-and-prepending-without-spaces'>
+ <title>Appending (.=) and Prepending (=.) Without Spaces</title>
+
+ <para>
+ If you want to append or prepend values without an
+ inserted space, use the ".=" and "=." operators.
+ </para>
+
+ <para>
+ These operators take immediate effect during parsing.
+ Here are some examples:
+ <literallayout class='monospaced'>
+ B = "bval"
+ B .= "additionaldata"
+ C = "cval"
+ C =. "test"
+ </literallayout>
+ The variable <filename>B</filename> contains
+ "bvaladditionaldata" and
+ <filename>C</filename> contains "testcval".
+ </para>
+ </section>
+
+ <section id='appending-and-prepending-override-style-syntax'>
+ <title>Appending and Prepending (Override Style Syntax)</title>
+
+ <para>
+ You can also append and prepend a variable's value
+ using an override style syntax.
+ When you use this syntax, no spaces are inserted.
+ </para>
+
+ <para>
+ These operators differ from the ":=", ".=", "=.", "+=", and "=+"
+ operators in that their effects are deferred
+ until after parsing completes rather than being immediately
+ applied.
+ Here are some examples:
+ <literallayout class='monospaced'>
+ B = "bval"
+ B_append = " additional data"
+ C = "cval"
+ C_prepend = "additional data "
+ D = "dval"
+ D_append = "additional data"
+ </literallayout>
+ The variable <filename>B</filename> becomes
+ "bval additional data" and <filename>C</filename> becomes
+ "additional data cval".
+ The variable <filename>D</filename> becomes
+ "dvaladditional data".
+ <note>
+ You must control all spacing when you use the
+ override syntax.
+ </note>
+ </para>
+ </section>
+
+ <section id='removing-override-style-syntax'>
+ <title>Removal (Override Style Syntax)</title>
+
+ <para>
+ You can remove values from lists using the removal
+ override style syntax.
+ Specifying a value for removal causes all occurrences of that
+ value to be removed from the variable.
+ </para>
+
+ <para>
+ When you use this syntax, BitBake expects one or more strings.
+ Surrounding spaces are removed as well.
+ Here is an example:
+ <literallayout class='monospaced'>
+ FOO = "123 456 789 123456 123 456 123 456"
+ FOO_remove = "123"
+ FOO_remove = "456"
+ FOO2 = "abc def ghi abcdef abc def abc def"
+ FOO2_remove = "abc def"
+ </literallayout>
+ The variable <filename>FOO</filename> becomes
+ "789 123456" and <filename>FOO2</filename> becomes
+ "ghi abcdef".
+ </para>
+ </section>
+
+ <section id='variable-flag-syntax'>
+ <title>Variable Flag Syntax</title>
+
+ <para>
+ Variable flags are BitBake's implementation of variable properties
+ or attributes.
+ It is a way of tagging extra information onto a variable.
+ You can find more out about variable flags in general in the
+ "<link linkend='variable-flags'>Variable Flags</link>"
+ section.
+ </para>
+
+ <para>
+ You can define, append, and prepend values to variable flags.
+ All the standard syntax operations previously mentioned work
+ for variable flags except for override style syntax
+ (i.e. <filename>_prepend</filename>, <filename>_append</filename>,
+ and <filename>_remove</filename>).
+ </para>
+
+ <para>
+ Here are some examples showing how to set variable flags:
+ <literallayout class='monospaced'>
+ FOO[a] = "abc"
+ FOO[b] = "123"
+ FOO[a] += "456"
+ </literallayout>
+ The variable <filename>FOO</filename> has two flags:
+ <filename>a</filename> and <filename>b</filename>.
+ The flags are immediately set to "abc" and "123", respectively.
+ The <filename>a</filename> flag becomes "abc 456".
+ </para>
+
+ <para>
+ No need exists to pre-define variable flags.
+ You can simply start using them.
+ One extremely common application
+ is to attach some brief documentation to a BitBake variable as
+ follows:
+ <literallayout class='monospaced'>
+ CACHE[doc] = "The directory holding the cache of the metadata."
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='inline-python-variable-expansion'>
+ <title>Inline Python Variable Expansion</title>
+
+ <para>
+ You can use inline Python variable expansion to
+ set variables.
+ Here is an example:
+ <literallayout class='monospaced'>
+ DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
+ </literallayout>
+ This example results in the <filename>DATE</filename>
+ variable being set to the current date.
+ </para>
+
+ <para>
+ Probably the most common use of this feature is to extract
+ the value of variables from BitBake's internal data dictionary,
+ <filename>d</filename>.
+ The following lines select the values of a package name
+ and its version number, respectively:
+ <literallayout class='monospaced'>
+ PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
+ PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='providing-pathnames'>
+ <title>Providing Pathnames</title>
+
+ <para>
+ When specifying pathnames for use with BitBake,
+ do not use the tilde ("~") character as a shortcut
+ for your home directory.
+ Doing so might cause BitBake to not recognize the
+ path since BitBake does not expand this character in
+ the same way a shell would.
+ </para>
+
+ <para>
+ Instead, provide a fuller path as the following
+ example illustrates:
+ <literallayout class='monospaced'>
+ BBLAYERS ?= " \
+ /home/scott-lenovo/LayerA \
+ "
+ </literallayout>
+ </para>
+ </section>
+ </section>
+
+ <section id='conditional-syntax-overrides'>
+ <title>Conditional Syntax (Overrides)</title>
+
+ <para>
+ BitBake uses
+ <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
+ to control what variables are overridden after BitBake
+ parses recipes and configuration files.
+ This section describes how you can use
+ <filename>OVERRIDES</filename> as conditional metadata,
+ talks about key expansion in relationship to
+ <filename>OVERRIDES</filename>, and provides some examples
+ to help with understanding.
+ </para>
+
+ <section id='conditional-metadata'>
+ <title>Conditional Metadata</title>
+
+ <para>
+ You can use <filename>OVERRIDES</filename> to conditionally select
+ a specific version of a variable and to conditionally
+ append or prepend the value of a variable.
+ <itemizedlist>
+ <listitem><para><emphasis>Selecting a Variable:</emphasis>
+ The <filename>OVERRIDES</filename> variable is
+ a colon-character-separated list that contains items
+ for which you want to satisfy conditions.
+ Thus, if you have a variable that is conditional on “arm”, and “arm”
+ is in <filename>OVERRIDES</filename>, then the “arm”-specific
+ version of the variable is used rather than the non-conditional
+ version.
+ Here is an example:
+ <literallayout class='monospaced'>
+ OVERRIDES = "architecture:os:machine"
+ TEST = "default"
+ TEST_os = "osspecific"
+ TEST_nooverride = "othercondvalue"
+ </literallayout>
+ In this example, the <filename>OVERRIDES</filename>
+ variable lists three overrides:
+ "architecture", "os", and "machine".
+ The variable <filename>TEST</filename> by itself has a default
+ value of "default".
+ You select the os-specific version of the <filename>TEST</filename>
+ variable by appending the "os" override to the variable
+ (i.e.<filename>TEST_os</filename>).
+ </para>
+
+ <para>
+ To better understand this, consider a practical example
+ that assumes an OpenEmbedded metadata-based Linux
+ kernel recipe file.
+ The following lines from the recipe file first set
+ the kernel branch variable <filename>KBRANCH</filename>
+ to a default value, then conditionally override that
+ value based on the architecture of the build:
+ <literallayout class='monospaced'>
+ KBRANCH = "standard/base"
+ KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
+ KBRANCH_qemumips = "standard/mti-malta32"
+ KBRANCH_qemuppc = "standard/qemuppc"
+ KBRANCH_qemux86 = "standard/common-pc/base"
+ KBRANCH_qemux86-64 = "standard/common-pc-64/base"
+ KBRANCH_qemumips64 = "standard/mti-malta64"
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Appending and Prepending:</emphasis>
+ BitBake also supports append and prepend operations to
+ variable values based on whether a specific item is
+ listed in <filename>OVERRIDES</filename>.
+ Here is an example:
+ <literallayout class='monospaced'>
+ DEPENDS = "glibc ncurses"
+ OVERRIDES = "machine:local"
+ DEPENDS_append_machine = "libmad"
+ </literallayout>
+ In this example, <filename>DEPENDS</filename> becomes
+ "glibc ncurses libmad".
+ </para>
+
+ <para>
+ Again, using an OpenEmbedded metadata-based
+ kernel recipe file as an example, the
+ following lines will conditionally append to the
+ <filename>KERNEL_FEATURES</filename> variable based
+ on the architecture:
+ <literallayout class='monospaced'>
+ KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
+ KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
+ KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='key-expansion'>
+ <title>Key Expansion</title>
+
+ <para>
+ Key expansion happens when the BitBake datastore is finalized
+ just before BitBake expands overrides.
+ To better understand this, consider the following example:
+ <literallayout class='monospaced'>
+ A${B} = "X"
+ B = "2"
+ A2 = "Y"
+ </literallayout>
+ In this case, after all the parsing is complete, and
+ before any overrides are handled, BitBake expands
+ <filename>${B}</filename> into "2".
+ This expansion causes <filename>A2</filename>, which was
+ set to "Y" before the expansion, to become "X".
+ </para>
+ </section>
+
+ <section id='variable-interaction-worked-examples'>
+ <title>Examples</title>
+
+ <para>
+ Despite the previous explanations that show the different forms of
+ variable definitions, it can be hard to work
+ out exactly what happens when variable operators, conditional
+ overrides, and unconditional overrides are combined.
+ This section presents some common scenarios along
+ with explanations for variable interactions that
+ typically confuse users.
+ </para>
+
+ <para>
+ There is often confusion concerning the order in which
+ overrides and various "append" operators take effect.
+ Recall that an append or prepend operation using "_append"
+ and "_prepend" does not result in an immediate assignment
+ as would "+=", ".=", "=+", or "=.".
+ Consider the following example:
+ <literallayout class='monospaced'>
+ OVERRIDES = "foo"
+ A = "Z"
+ A_foo_append = "X"
+ </literallayout>
+ For this case, <filename>A</filename> is
+ unconditionally set to "Z" and "X" is
+ unconditionally and immediately appended to the variable
+ <filename>A_foo</filename>.
+ Because overrides have not been applied yet,
+ <filename>A_foo</filename> is set to "X" due to the append
+ and <filename>A</filename> simply equals "Z".
+ </para>
+
+ <para>
+ Applying overrides, however, changes things.
+ Since "foo" is listed in <filename>OVERRIDES</filename>,
+ the conditional variable <filename>A</filename> is replaced
+ with the "foo" version, which is equal to "X".
+ So effectively, <filename>A_foo</filename> replaces <filename>A</filename>.
+ </para>
+
+ <para>
+ This next example changes the order of the override and
+ the append:
+ <literallayout class='monospaced'>
+ OVERRIDES = "foo"
+ A = "Z"
+ A_append_foo = "X"
+ </literallayout>
+ For this case, before overrides are handled,
+ <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename>
+ is set to "X".
+ Once the override for "foo" is applied, however,
+ <filename>A</filename> gets appended with "X".
+ Consequently, <filename>A</filename> becomes "ZX".
+ Notice that spaces are not appended.
+ </para>
+
+ <para>
+ This next example has the order of the appends and overrides reversed
+ back as in the first example:
+ <literallayout class='monospaced'>
+ OVERRIDES = "foo"
+ A = "Y"
+ A_foo_append = "Z"
+ A_foo_append += "X"
+ </literallayout>
+ For this case, before any overrides are resolved,
+ <filename>A</filename> is set to "Y" using an immediate assignment.
+ After this immediate assignment, <filename>A_foo</filename> is set
+ to "Z", and then further appended with
+ "X" leaving the variable set to "Z X".
+ Finally, applying the override for "foo" results in the conditional
+ variable <filename>A</filename> becoming "Z X" (i.e.
+ <filename>A</filename> is replaced with <filename>A_foo</filename>).
+ </para>
+
+ <para>
+ This final example mixes in some varying operators:
+ <literallayout class='monospaced'>
+ A = "1"
+ A_append = "2"
+ A_append = "3"
+ A += "4"
+ A .= "5"
+ </literallayout>
+ For this case, the type of append operators are affecting the
+ order of assignments as BitBake passes through the code
+ multiple times.
+ Initially, <filename>A</filename> is set to "1 45" because
+ of the three statements that use immediate operators.
+ After these assignments are made, BitBake applies the
+ <filename>_append</filename> operations.
+ Those operations result in <filename>A</filename> becoming "1 4523".
+ </para>
+ </section>
+ </section>
+
+ <section id='sharing-functionality'>
+ <title>Sharing Functionality</title>
+
+ <para>
+ BitBake allows for metadata sharing through include files
+ (<filename>.inc</filename>) and class files
+ (<filename>.bbclass</filename>).
+ For example, suppose you have a piece of common functionality
+ such as a task definition that you want to share between
+ more than one recipe.
+ In this case, creating a <filename>.bbclass</filename>
+ file that contains the common functionality and then using
+ the <filename>inherit</filename> directive in your recipes to
+ inherit the class would be a common way to share the task.
+ </para>
+
+ <para>
+ This section presents the mechanisms BitBake provides to
+ allow you to share functionality between recipes.
+ Specifically, the mechanisms include <filename>include</filename>,
+ <filename>inherit</filename>, <filename>INHERIT</filename>, and
+ <filename>require</filename> directives.
+ </para>
+
+ <section id='locating-include-and-class-files'>
+ <title>Locating Include and Class Files</title>
+
+ <para>
+ BitBake uses the
+ <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+ variable to locate needed include and class files.
+ The <filename>BBPATH</filename> variable is analogous to
+ the environment variable <filename>PATH</filename>.
+ </para>
+
+ <para>
+ In order for include and class files to be found by BitBake,
+ they need to be located in a "classes" subdirectory that can
+ be found in <filename>BBPATH</filename>.
+ </para>
+ </section>
+
+ <section id='inherit-directive'>
+ <title><filename>inherit</filename> Directive</title>
+
+ <para>
+ When writing a recipe or class file, you can use the
+ <filename>inherit</filename> directive to inherit the
+ functionality of a class (<filename>.bbclass</filename>).
+ BitBake only supports this directive when used within recipe
+ and class files (i.e. <filename>.bb</filename> and
+ <filename>.bbclass</filename>).
+ </para>
+
+ <para>
+ The <filename>inherit</filename> directive is a rudimentary
+ means of specifying what classes of functionality your
+ recipes require.
+ For example, you can easily abstract out the tasks involved in
+ building a package that uses Autoconf and Automake and put
+ those tasks into a class file that can be used by your recipe.
+ </para>
+
+ <para>
+ As an example, your recipes could use the following directive
+ to inherit an <filename>autotools.bbclass</filename> file.
+ The class file would contain common functionality for using
+ Autotools that could be shared across recipes:
+ <literallayout class='monospaced'>
+ inherit autotools
+ </literallayout>
+ In this case, BitBake would search for the directory
+ <filename>classes/autotools.bbclass</filename>
+ in <filename>BBPATH</filename>.
+ <note>
+ You can override any values and functions of the
+ inherited class within your recipe by doing so
+ after the "inherit" statement.
+ </note>
+ </para>
+ </section>
+
+ <section id='include-directive'>
+ <title><filename>include</filename> Directive</title>
+
+ <para>
+ BitBake understands the <filename>include</filename>
+ 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 <filename>BBPATH</filename>.
+ </para>
+
+ <para>
+ As an example, suppose you needed a recipe to include some
+ self-test definitions:
+ <literallayout class='monospaced'>
+ include test_defs.inc
+ </literallayout>
+ <note>
+ The <filename>include</filename> 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
+ <link linkend='require-inclusion'><filename>require</filename></link>
+ instead of <filename>include</filename>.
+ Doing so makes sure that an error is produced if the
+ file cannot be found.
+ </note>
+ </para>
+ </section>
+
+ <section id='require-inclusion'>
+ <title><filename>require</filename> Directive</title>
+
+ <para>
+ BitBake understands the <filename>require</filename>
+ directive.
+ This directive behaves just like the
+ <filename>include</filename> directive with the exception that
+ BitBake raises a parsing error if the file to be included cannot
+ be found.
+ Thus, any file you require is inserted into the file that is
+ being parsed at the location of the directive.
+ </para>
+
+ <para>
+ Similar to how BitBake handles
+ <link linkend='include-directive'><filename>include</filename></link>,
+ if the path specified
+ on the require line is a relative path, BitBake locates
+ the first file it can find within <filename>BBPATH</filename>.
+ </para>
+
+ <para>
+ As an example, suppose you have two versions of a recipe
+ (e.g. <filename>foo_1.2.2.bb</filename> and
+ <filename>foo_2.0.0.bb</filename>) where
+ each version contains some identical functionality that could be
+ shared.
+ You could create an include file named <filename>foo.inc</filename>
+ that contains the common definitions needed to build "foo".
+ You need to be sure <filename>foo.inc</filename> is located in the
+ same directory as your two recipe files as well.
+ Once these conditions are set up, you can share the functionality
+ using a <filename>require</filename> directive from within each
+ recipe:
+ <literallayout class='monospaced'>
+ require foo.inc
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='inherit-configuration-directive'>
+ <title><filename>INHERIT</filename> Configuration Directive</title>
+
+ <para>
+ When creating a configuration file (<filename>.conf</filename>),
+ you can use the <filename>INHERIT</filename> directive to
+ inherit a class.
+ BitBake only supports this directive when used within
+ a configuration file.
+ </para>
+
+ <para>
+ As an example, suppose you needed to inherit a class
+ file called <filename>abc.bbclass</filename> from a
+ configuration file as follows:
+ <literallayout class='monospaced'>
+ INHERIT += "abc"
+ </literallayout>
+ This configuration directive causes the named
+ class to be inherited at the point of the directive
+ during parsing.
+ As with the <filename>inherit</filename> directive, the
+ <filename>.bbclass</filename> file must be located in a
+ "classes" subdirectory in one of the directories specified
+ in <filename>BBPATH</filename>.
+ <note>
+ Because <filename>.conf</filename> files are parsed
+ first during BitBake's execution, using
+ <filename>INHERIT</filename> to inherit a class effectively
+ inherits the class globally (i.e. for all recipes).
+ </note>
+ </para>
+ </section>
+ </section>
+
+ <section id='functions'>
+ <title>Functions</title>
+
+ <para>
+ As with most languages, functions are the building blocks that
+ are used to build up operations into tasks.
+ BitBake supports these types of functions:
+ <itemizedlist>
+ <listitem><para><emphasis>Shell Functions:</emphasis>
+ Functions written in shell script and executed either
+ directly as functions, tasks, or both.
+ They can also be called by other shell functions.
+ </para></listitem>
+ <listitem><para><emphasis>BitBake Style Python Functions:</emphasis>
+ Functions written in Python and executed by BitBake or other
+ Python functions using <filename>bb.build.exec_func()</filename>.
+ </para></listitem>
+ <listitem><para><emphasis>Python Functions:</emphasis>
+ Functions written in Python and executed by Python.
+ </para></listitem>
+ <listitem><para><emphasis>Anonymous Python Functions:</emphasis>
+ Python functions executed automatically during
+ parsing.
+ </para></listitem>
+ </itemizedlist>
+ Regardless of the type of function, you can only
+ define them in class (<filename>.bbclass</filename>)
+ and recipe (<filename>.bb</filename> or <filename>.inc</filename>)
+ files.
+ </para>
+
+ <section id='shell-functions'>
+ <title>Shell Functions</title>
+
+ <para>
+ Functions written in shell script and executed either
+ directly as functions, tasks, or both.
+ They can also be called by other shell functions.
+ Here is an example shell function definition:
+ <literallayout class='monospaced'>
+ some_function () {
+ echo "Hello World"
+ }
+ </literallayout>
+ When you create these types of functions in your recipe
+ or class files, you need to follow the shell programming
+ rules.
+ The scripts are executed by <filename>/bin/sh</filename>,
+ which may not be a bash shell but might be something
+ such as <filename>dash</filename>.
+ You should not use Bash-specific script (bashisms).
+ </para>
+ </section>
+
+ <section id='bitbake-style-python-functions'>
+ <title>BitBake Style Python Functions</title>
+
+ <para>
+ These functions are written in Python and executed by
+ BitBake or other Python functions using
+ <filename>bb.build.exec_func()</filename>.
+ </para>
+
+ <para>
+ An example BitBake function is:
+ <literallayout class='monospaced'>
+ python some_python_function () {
+ d.setVar("TEXT", "Hello World")
+ print d.getVar("TEXT", True)
+ }
+ </literallayout>
+ Because the Python "bb" and "os" modules are already
+ imported, you do not need to import these modules.
+ Also in these types of functions, the datastore ("d")
+ is a global variable and is always automatically
+ available.
+ </para>
+ </section>
+
+ <section id='python-functions'>
+ <title>Python Functions</title>
+
+ <para>
+ These functions are written in Python and are executed by
+ other Python code.
+ Examples of Python functions are utility functions
+ that you intend to call from in-line Python or
+ from within other Python functions.
+ Here is an example:
+ <literallayout class='monospaced'>
+ def get_depends(d):
+ if d.getVar('SOMECONDITION', True):
+ return "dependencywithcond"
+ else:
+ return "dependency"
+ SOMECONDITION = "1"
+ DEPENDS = "${@get_depends(d)}"
+ </literallayout>
+ This would result in <filename>DEPENDS</filename>
+ containing <filename>dependencywithcond</filename>.
+ </para>
+
+ <para>
+ Here are some things to know about Python functions:
+ <itemizedlist>
+ <listitem><para>Python functions can take parameters.
+ </para></listitem>
+ <listitem><para>The BitBake datastore is not
+ automatically available.
+ Consequently, you must pass it in as a
+ parameter to the function.
+ </para></listitem>
+ <listitem><para>The "bb" and "os" Python modules are
+ automatically available.
+ You do not need to import them.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='anonymous-python-functions'>
+ <title>Anonymous Python Functions</title>
+
+ <para>
+ Sometimes it is useful to run some code during
+ parsing to set variables or to perform other operations
+ programmatically.
+ To do this, you can define an anonymous Python function.
+ Here is an example that conditionally sets a
+ variable based on the value of another variable:
+ <literallayout class='monospaced'>
+ python __anonymous () {
+ if d.getVar('SOMEVAR', True) == 'value':
+ d.setVar('ANOTHERVAR', 'value2')
+ }
+ </literallayout>
+ The "__anonymous" function name is optional, so the
+ following example is functionally equivalent to the above:
+ <literallayout class='monospaced'>
+ python () {
+ if d.getVar('SOMEVAR', True) == 'value':
+ d.setVar('ANOTHERVAR', 'value2')
+ }
+ </literallayout>
+ Because unlike other Python functions anonymous
+ Python functions are executed during parsing, the
+ "d" variable within an anonymous Python function represents
+ the datastore for the entire recipe.
+ Consequently, you can set variable values here and
+ those values can be picked up by other functions.
+ </para>
+ </section>
+
+ <section id='flexible-inheritance-for-class-functions'>
+ <title>Flexible Inheritance for Class Functions</title>
+
+ <para>
+ Through coding techniques and the use of
+ <filename>EXPORT_FUNCTIONS</filename>, BitBake supports
+ exporting a function from a class such that the
+ class function appears as the default implementation
+ of the function, but can still be called if a recipe
+ inheriting the class needs to define its own version of
+ the function.
+ </para>
+
+ <para>
+ To understand the benefits of this feature, consider
+ the basic scenario where a class defines a task function
+ and your recipe inherits the class.
+ In this basic scenario, your recipe inherits the task
+ function as defined in the class.
+ If desired, your recipe can add to the start and end of the
+ function by using the "_prepend" or "_append" operations
+ respectively, or it can redefine the function completely.
+ However, if it redefines the function, there is
+ no means for it to call the class version of the function.
+ <filename>EXPORT_FUNCTIONS</filename> provides a mechanism
+ that enables the recipe's version of the function to call
+ the original version of the function.
+ </para>
+
+ <para>
+ To make use of this technique, you need the following
+ things in place:
+ <itemizedlist>
+ <listitem><para>
+ The class needs to define the function as follows:
+ <literallayout class='monospaced'>
+ <replaceable>classname</replaceable><filename>_</filename><replaceable>functionname</replaceable>
+ </literallayout>
+ For example, if you have a class file
+ <filename>bar.bbclass</filename> and a function named
+ <filename>do_foo</filename>, the class must define the function
+ as follows:
+ <literallayout class='monospaced'>
+ bar_do_foo
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ The class needs to contain the <filename>EXPORT_FUNCTIONS</filename>
+ statement as follows:
+ <literallayout class='monospaced'>
+ EXPORT_FUNCTIONS <replaceable>functionname</replaceable>
+ </literallayout>
+ For example, continuing with the same example, the
+ statement in the <filename>bar.bbclass</filename> would be
+ as follows:
+ <literallayout class='monospaced'>
+ EXPORT_FUNCTIONS do_foo
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ You need to call the function appropriately from within your
+ recipe.
+ Continuing with the same example, if your recipe
+ needs to call the class version of the function,
+ it should call <filename>bar_do_foo</filename>.
+ Assuming <filename>do_foo</filename> was a shell function
+ and <filename>EXPORT_FUNCTIONS</filename> was used as above,
+ the recipe's function could conditionally call the
+ class version of the function as follows:
+ <literallayout class='monospaced'>
+ do_foo() {
+ if [ somecondition ] ; then
+ bar_do_foo
+ else
+ # Do something else
+ fi
+ }
+ </literallayout>
+ To call your modified version of the function as defined
+ in your recipe, call it as <filename>do_foo</filename>.
+ </para></listitem>
+ </itemizedlist>
+ With these conditions met, your single recipe
+ can freely choose between the original function
+ as defined in the class file and the modified function in your recipe.
+ If you do not set up these conditions, you are limited to using one function
+ or the other.
+ </para>
+ </section>
+ </section>
+
+ <section id='tasks'>
+ <title>Tasks</title>
+
+ <para>
+ Tasks are BitBake execution units that originate as
+ functions and make up the steps that BitBake needs to run
+ for given recipe.
+ Tasks are only supported in recipe (<filename>.bb</filename>
+ or <filename>.inc</filename>) and class
+ (<filename>.bbclass</filename>) files.
+ By convention, task names begin with the string "do_".
+ </para>
+
+ <para>
+ Here is an example of a task that prints out the date:
+ <literallayout class='monospaced'>
+ python do_printdate () {
+ import time
+ print time.strftime('%Y%m%d', time.gmtime())
+ }
+ addtask printdate after do_fetch before do_build
+ </literallayout>
+ </para>
+
+ <section id='promoting-a-function-to-a-task'>
+ <title>Promoting a Function to a Task</title>
+
+ <para>
+ Any function can be promoted to a task by applying the
+ <filename>addtask</filename> command.
+ The <filename>addtask</filename> command also describes
+ inter-task dependencies.
+ Here is the function from the previous section but with the
+ <filename>addtask</filename> command promoting it to a task
+ and defining some dependencies:
+ <literallayout class='monospaced'>
+ python do_printdate () {
+ import time
+ print time.strftime('%Y%m%d', time.gmtime())
+ }
+ addtask printdate after do_fetch before do_build
+ </literallayout>
+ In the example, the function is defined and then promoted
+ as a task.
+ The <filename>do_printdate</filename> task becomes a dependency of
+ the <filename>do_build</filename> task, which is the default
+ task.
+ And, the <filename>do_printdate</filename> task is dependent upon
+ the <filename>do_fetch</filename> task.
+ Execution of the <filename>do_build</filename> task results
+ in the <filename>do_printdate</filename> task running first.
+ </para>
+ </section>
+
+ <section id='deleting-a-task'>
+ <title>Deleting a Task</title>
+
+ <para>
+ As well as being able to add tasks, you can delete them.
+ Simply use the <filename>deltask</filename> command to
+ delete a task.
+ For example, to delete the example task used in the previous
+ sections, you would use:
+ <literallayout class='monospaced'>
+ deltask printdate
+ </literallayout>
+ If you delete a task using the <filename>deltask</filename>
+ command and the task has dependencies, the dependencies are
+ not reconnected.
+ For example, suppose you have three tasks named
+ <filename>do_a</filename>, <filename>do_b</filename>, and
+ <filename>do_c</filename>.
+ Furthermore, <filename>do_c</filename> is dependent on
+ <filename>do_b</filename>, which in turn is dependent on
+ <filename>do_a</filename>.
+ Given this scenario, if you use <filename>deltask</filename>
+ to delete <filename>do_b</filename>, the implicit dependency
+ relationship between <filename>do_c</filename> and
+ <filename>do_a</filename> through <filename>do_b</filename>
+ no longer exists, and <filename>do_c</filename> dependencies
+ are not updated to include <filename>do_a</filename>.
+ Thus, <filename>do_c</filename> is free to run before
+ <filename>do_a</filename>.
+ </para>
+
+ <para>
+ If you want dependencies such as these to remain intact, use
+ the <filename>noexec</filename> varflag to disable the task
+ instead of using the <filename>deltask</filename> command to
+ delete it:
+ <literallayout class='monospaced'>
+ do_b[noexec] = "1"
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='passing-information-into-the-build-task-environment'>
+ <title>Passing Information Into the Build Task Environment</title>
+
+ <para>
+ When running a task, BitBake tightly controls the execution
+ environment of the build tasks to make
+ sure unwanted contamination from the build machine cannot
+ influence the build.
+ Consequently, if you do want something to get passed into the
+ build task environment, you must take these two steps:
+ <orderedlist>
+ <listitem><para>
+ Tell BitBake to load what you want from the environment
+ into the datastore.
+ You can do so through the
+ <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
+ variable.
+ For example, assume you want to prevent the build system from
+ accessing your <filename>$HOME/.ccache</filename>
+ directory.
+ The following command tells BitBake to load
+ <filename>CCACHE_DIR</filename> from the environment into
+ the datastore:
+ <literallayout class='monospaced'>
+ export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
+ </literallayout></para></listitem>
+ <listitem><para>
+ Tell BitBake to export what you have loaded into the
+ datastore to the task environment of every running task.
+ Loading something from the environment into the datastore
+ (previous step) only makes it available in the datastore.
+ To export it to the task environment of every running task,
+ use a command similar to the following in your local configuration
+ file <filename>local.conf</filename> or your
+ distribution configuration file:
+ <literallayout class='monospaced'>
+ export CCACHE_DIR
+ </literallayout>
+ <note>
+ A side effect of the previous steps is that BitBake
+ records the variable as a dependency of the build process
+ in things like the setscene checksums.
+ If doing so results in unnecessary rebuilds of tasks, you can
+ whitelist the variable so that the setscene code
+ ignores the dependency when it creates checksums.
+ </note></para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ Sometimes, it is useful to be able to obtain information
+ from the original execution environment.
+ Bitbake saves a copy of the original environment into
+ a special variable named
+ <link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>.
+ </para>
+
+ <para>
+ The <filename>BB_ORIGENV</filename> variable returns a datastore
+ object that can be queried using the standard datastore operators
+ such as <filename>getVar(, False)</filename>.
+ The datastore object is useful, for example, to find the original
+ <filename>DISPLAY</filename> variable.
+ Here is an example:
+ <literallayout class='monospaced'>
+ origenv = d.getVar("BB_ORIGENV", False)
+ bar = origenv.getVar("BAR", False)
+ </literallayout>
+ The previous example returns <filename>BAR</filename> from the original
+ execution environment.
+ </para>
+
+ <para>
+ By default, BitBake cleans the environment to include only those
+ things exported or listed in its whitelist to ensure that the build
+ environment is reproducible and consistent.
+ </para>
+ </section>
+ </section>
+
+ <section id='variable-flags'>
+ <title>Variable Flags</title>
+
+ <para>
+ Variable flags (varflags) help control a task's functionality
+ and dependencies.
+ BitBake reads and writes varflags to the datastore using the following
+ command forms:
+ <literallayout class='monospaced'>
+ <replaceable>variable</replaceable> = d.getVarFlags("<replaceable>variable</replaceable>")
+ self.d.setVarFlags("FOO", {"func": True})
+ </literallayout>
+ </para>
+
+ <para>
+ When working with varflags, the same syntax, with the exception of
+ overrides, applies.
+ In other words, you can set, append, and prepend varflags just like
+ variables.
+ See the
+ "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>"
+ section for details.
+ </para>
+
+ <para>
+ BitBake has a defined set of varflags available for recipes and
+ classes.
+ Tasks support a number of these flags which control various
+ functionality of the task:
+ <itemizedlist>
+ <listitem><para><emphasis>cleandirs:</emphasis>
+ Empty directories that should created before the task runs.
+ </para></listitem>
+ <listitem><para><emphasis>depends:</emphasis>
+ Controls inter-task dependencies.
+ See the
+ <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+ variable and the
+ "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
+ section for more information.
+ </para></listitem>
+ <listitem><para><emphasis>deptask:</emphasis>
+ Controls task build-time dependencies.
+ See the
+ <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+ variable and the
+ "<link linkend='build-dependencies'>Build Dependencies</link>"
+ section for more information.
+ </para></listitem>
+ <listitem><para><emphasis>dirs:</emphasis>
+ Directories that should be created before the task runs.
+ </para></listitem>
+ <listitem><para><emphasis>lockfiles:</emphasis>
+ Specifies one or more lockfiles to lock while the task
+ executes.
+ Only one task may hold a lockfile, and any task that
+ attempts to lock an already locked file will block until
+ the lock is released.
+ You can use this variable flag to accomplish mutual
+ exclusion.
+ </para></listitem>
+ <listitem><para><emphasis>noexec:</emphasis>
+ Marks the tasks as being empty and no execution required.
+ The <filename>noexec</filename> flag can be used to set up
+ tasks as dependency placeholders, or to disable tasks defined
+ elsewhere that are not needed in a particular recipe.
+ </para></listitem>
+ <listitem><para><emphasis>nostamp:</emphasis>
+ Tells BitBake to not generate a stamp file for a task,
+ which implies the task should always be executed.
+ </para></listitem>
+ <listitem><para><emphasis>postfuncs:</emphasis>
+ List of functions to call after the completion of the task.
+ </para></listitem>
+ <listitem><para><emphasis>prefuncs:</emphasis>
+ List of functions to call before the task executes.
+ </para></listitem>
+ <listitem><para><emphasis>rdepends:</emphasis>
+ Controls inter-task runtime dependencies.
+ See the
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+ variable, the
+ <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
+ variable, and the
+ "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
+ section for more information.
+ </para></listitem>
+ <listitem><para><emphasis>rdeptask:</emphasis>
+ Controls task runtime dependencies.
+ See the
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+ variable, the
+ <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
+ variable, and the
+ "<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
+ section for more information.
+ </para></listitem>
+ <listitem><para><emphasis>recideptask:</emphasis>
+ When set in conjunction with
+ <filename>recrdeptask</filename>, specifies a task that
+ should be inspected for additional dependencies.
+ </para></listitem>
+ <listitem><para><emphasis>recrdeptask:</emphasis>
+ Controls task recursive runtime dependencies.
+ See the
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+ variable, the
+ <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
+ variable, and the
+ "<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
+ section for more information.
+ </para></listitem>
+ <listitem><para><emphasis>stamp-extra-info:</emphasis>
+ Extra stamp information to append to the task's stamp.
+ As an example, OpenEmbedded uses this flag to allow
+ machine-specific tasks.
+ </para></listitem>
+ <listitem><para><emphasis>umask:</emphasis>
+ The umask to run the task under.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Several varflags are useful for controlling how signatures are
+ calculated for variables.
+ For more information on this process, see the
+ "<link linkend='checksums'>Checksums (Signatures)</link>"
+ section.
+ <itemizedlist>
+ <listitem><para><emphasis>vardeps:</emphasis>
+ Specifies a space-separated list of additional
+ variables to add to a variable's dependencies
+ for the purposes of calculating its signature.
+ Adding variables to this list is useful, for example, when
+ a function refers to a variable in a manner that
+ does not allow BitBake to automatically determine
+ that the variable is referred to.
+ </para></listitem>
+ <listitem><para><emphasis>vardepsexclude:</emphasis>
+ Specifies a space-separated list of variables
+ that should be excluded from a variable's dependencies
+ for the purposes of calculating its signature.
+ </para></listitem>
+ <listitem><para><emphasis>vardepvalue:</emphasis>
+ If set, instructs BitBake to ignore the actual
+ value of the variable and instead use the specified
+ value when calculating the variable's signature.
+ </para></listitem>
+ <listitem><para><emphasis>vardepvalueexclude:</emphasis>
+ Specifies a pipe-separated list of strings to exclude
+ from the variable's value when calculating the
+ variable's signature.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='events'>
+ <title>Events</title>
+
+ <para>
+ BitBake allows installation of event handlers within
+ recipe and class files.
+ Events are triggered at certain points during operation,
+ such as the beginning of an operation against a given recipe
+ (<filename>*.bb</filename> file), the start of a given task,
+ task failure, task success, and so forth.
+ The intent is to make it easy to do things like email
+ notification on build failure.
+ </para>
+
+ <para>
+ Following is an example event handler that
+ prints the name of the event and the content of
+ the <filename>FILE</filename> variable:
+ <literallayout class='monospaced'>
+ addhandler myclass_eventhandler
+ python myclass_eventhandler() {
+ from bb.event import getName
+ from bb import data
+ print("The name of the Event is %s" % getName(e))
+ print("The file we run for is %s" % data.getVar('FILE', e.data, True))
+ }
+ </literallayout>
+ This event handler gets called every time an event is
+ triggered.
+ A global variable "<filename>e</filename>" is defined and
+ "<filename>e.data</filename>" contains an instance of
+ "<filename>bb.data</filename>".
+ With the <filename>getName(e)</filename> method, one can get
+ the name of the triggered event.
+ </para>
+
+ <para>
+ Because you probably are only interested in a subset of events,
+ you would likely use the <filename>[eventmask]</filename> flag
+ for your event handler to be sure that only certain events
+ trigger the handler.
+ Given the previous example, suppose you only wanted the
+ <filename>bb.build.TaskFailed</filename> event to trigger that
+ event handler.
+ Use the flag as follows:
+ <literallayout class='monospaced'>
+ addhandler myclass_eventhandler
+ myclass_eventhandler[eventmask] = "bb.build.TaskFailed"
+ python myclass_eventhandler() {
+ from bb.event import getName
+ from bb import data
+ print("The name of the Event is %s" % getName(e))
+ print("The file we run for is %s" % data.getVar('FILE', e.data, True))
+ }
+ </literallayout>
+ </para>
+
+ <para>
+ During a standard build, the following common events might occur:
+ <itemizedlist>
+ <listitem><para>
+ <filename>bb.event.ConfigParsed()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.ParseStarted()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.ParseProgress()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.ParseCompleted()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.BuildStarted()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.build.TaskStarted()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.build.TaskInvalid()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.build.TaskFailedSilent()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.build.TaskFailed()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.build.TaskSucceeded()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.BuildCompleted()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.cooker.CookerExit()</filename>
+ </para></listitem>
+ </itemizedlist>
+ Here is a list of other events that occur based on specific requests
+ to the server:
+ <itemizedlist>
+ <listitem><para>
+ <filename>bb.event.TreeDataPreparationStarted()</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.TreeDataPreparationProgress</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.TreeDataPreparationCompleted</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.DepTreeGenerated</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.CoreBaseFilesFound</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.ConfigFilePathFound</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.FilesMatchingFound</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.ConfigFilesFound</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.event.TargetsTreeGenerated</filename>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='variants-class-extension-mechanism'>
+ <title>Variants - Class Extension Mechanism</title>
+
+ <para>
+ BitBake supports two features that facilitate creating
+ from a single recipe file multiple incarnations of that
+ recipe file where all incarnations are buildable.
+ These features are enabled through the
+ <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
+ and
+ <link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link>
+ variables.
+ <note>
+ The mechanism for this class extension is extremely
+ specific to the implementation.
+ Usually, the recipe's
+ <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>,
+ <link linkend='var-PN'><filename>PN</filename></link>, and
+ <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+ variables would need to be modified by the extension class.
+ For specific examples, see the OE-Core
+ <filename>native</filename>, <filename>nativesdk</filename>,
+ and <filename>multilib</filename> classes.
+ </note>
+ <itemizedlist>
+ <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis>
+ This variable is a space separated list of classes used to "extend" the
+ recipe for each variant.
+ Here is an example that results in a second incarnation of the current
+ recipe being available.
+ This second incarnation will have the "native" class inherited.
+ <literallayout class='monospaced'>
+ BBCLASSEXTEND = "native"
+ </literallayout></para></listitem>
+ <listitem><para><emphasis><filename>BBVERSIONS</filename>:</emphasis>
+ This variable allows a single recipe to build multiple versions of a
+ project from a single recipe file.
+ You can also specify conditional metadata
+ (using the
+ <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
+ mechanism) for a single version, or an optionally named range of versions.
+ Here is an example:
+ <literallayout class='monospaced'>
+ BBVERSIONS = "1.0 2.0 git"
+ SRC_URI_git = "git://someurl/somepath.git"
+
+ BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
+ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
+ </literallayout>
+ The name of the range defaults to the original version of the
+ recipe.
+ For example, in OpenEmbedded, the recipe file
+ <filename>foo_1.0.0+.bb</filename> creates a default name range
+ of <filename>1.0.0+</filename>.
+ This is useful because the range name is not only placed
+ into overrides, but it is also made available for the metadata to use
+ in the variable that defines the base recipe versions for use in
+ <filename>file://</filename> search paths
+ (<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>).
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='dependencies'>
+ <title>Dependencies</title>
+
+ <para>
+ To allow for efficient operation given multiple processes
+ executing in parallel, BitBake handles dependencies at
+ the task level.
+ BitBake supports a robust method to handle these dependencies.
+ </para>
+
+ <para>
+ This section describes several types of dependency mechanisms.
+ </para>
+
+ <section id='dependencies-internal-to-the-bb-file'>
+ <title>Dependencies Internal to the <filename>.bb</filename> File</title>
+
+ <para>
+ BitBake uses the <filename>addtask</filename> directive
+ to manage dependencies that are internal to a given recipe
+ file.
+ You can use the <filename>addtask</filename> directive to
+ indicate when a task is dependent on other tasks or when
+ other tasks depend on that recipe.
+ Here is an example:
+ <literallayout class='monospaced'>
+ addtask printdate after do_fetch before do_build
+ </literallayout>
+ In this example, the <filename>printdate</filename> task is
+ depends on the completion of the <filename>do_fetch</filename>
+ task.
+ And, the <filename>do_build</filename> depends on the completion
+ of the <filename>printdate</filename> task.
+ </para>
+ </section>
+
+ <section id='build-dependencies'>
+ <title>Build Dependencies</title>
+
+ <para>
+ BitBake uses the
+ <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+ variable to manage build time dependencies.
+ The "deptask" varflag for tasks signifies the task of each
+ item listed in <filename>DEPENDS</filename> that must
+ complete before that task can be executed.
+ Here is an example:
+ <literallayout class='monospaced'>
+ do_configure[deptask] = "do_populate_sysroot"
+ </literallayout>
+ In this example, the <filename>do_populate_sysroot</filename>
+ task of each item in <filename>DEPENDS</filename> must complete before
+ <filename>do_configure</filename> can execute.
+ </para>
+ </section>
+
+ <section id='runtime-dependencies'>
+ <title>Runtime Dependencies</title>
+
+ <para>
+ BitBake uses the
+ <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, and
+ <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
+ variables to manage runtime dependencies.
+ </para>
+
+ <para>
+ The <filename>PACKAGES</filename> variable lists runtime
+ packages.
+ Each of those packages can have <filename>RDEPENDS</filename> and
+ <filename>RRECOMMENDS</filename> runtime dependencies.
+ The "rdeptask" flag for tasks is used to signify the task of each
+ item runtime dependency which must have completed before that
+ task can be executed.
+ <literallayout class='monospaced'>
+ do_package_qa[rdeptask] = "do_packagedata"
+ </literallayout>
+ In the previous example, the <filename>do_packagedata</filename>
+ task of each item in <filename>RDEPENDS</filename> must have
+ completed before <filename>do_package_qa</filename> can execute.
+ </para>
+ </section>
+
+ <section id='recursive-dependencies'>
+ <title>Recursive Dependencies</title>
+
+ <para>
+ BitBake uses the "recrdeptask" flag to manage
+ recursive task dependencies.
+ BitBake looks through the build-time and runtime
+ dependencies of the current recipe, looks through
+ the task's inter-task
+ dependencies, and then adds dependencies for the
+ listed task.
+ Once BitBake has accomplished this, it recursively works through
+ the dependencies of those tasks.
+ Iterative passes continue until all dependencies are discovered
+ and added.
+ </para>
+
+ <para>
+ You might want to not only have BitBake look for
+ dependencies of those tasks, but also have BitBake look
+ for build-time and runtime dependencies of the dependent
+ tasks as well.
+ If that is the case, you need to reference the task name
+ itself in the task list:
+ <literallayout class='monospaced'>
+ do_a[recrdeptask] = "do_a do_b"
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='inter-task-dependencies'>
+ <title>Inter-Task Dependencies</title>
+
+ <para>
+ BitBake uses the "depends" flag in a more generic form
+ to manage inter-task dependencies.
+ This more generic form allows for inter-dependency
+ checks for specific tasks rather than checks for
+ the data in <filename>DEPENDS</filename>.
+ Here is an example:
+ <literallayout class='monospaced'>
+ do_patch[depends] = "quilt-native:do_populate_sysroot"
+ </literallayout>
+ In this example, the <filename>do_populate_sysroot</filename>
+ task of the target <filename>quilt-native</filename>
+ must have completed before the
+ <filename>do_patch</filename> task can execute.
+ </para>
+
+ <para>
+ The "rdepends" flag works in a similar way but takes targets
+ in the runtime namespace instead of the build-time dependency
+ namespace.
+ </para>
+ </section>
+ </section>
+
+ <section id='accessing-datastore-variables-using-python'>
+ <title>Accessing Datastore Variables Using Python</title>
+
+ <para>
+ It is often necessary to access variables in the
+ BitBake datastore using Python functions.
+ The Bitbake datastore has an API that allows you this
+ access.
+ Here is a list of available operations:
+ </para>
+
+ <para>
+ <informaltable frame='none'>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth='1*'/>
+ <colspec colname='c2' colwidth='1*'/>
+ <thead>
+ <row>
+ <entry align="left"><emphasis>Operation</emphasis></entry>
+ <entry align="left"><emphasis>Description</emphasis></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry align="left"><filename>d.getVar("X", expand=False)</filename></entry>
+ <entry align="left">Returns the value of variable "X".
+ Using "expand=True" expands the value.</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.setVar("X", "value")</filename></entry>
+ <entry align="left">Sets the variable "X" to "value".</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.appendVar("X", "value")</filename></entry>
+ <entry align="left">Adds "value" to the end of the variable "X".</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.prependVar("X", "value")</filename></entry>
+ <entry align="left">Adds "value" to the start of the variable "X".</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.delVar("X")</filename></entry>
+ <entry align="left">Deletes the variable "X" from the datastore.</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry>
+ <entry align="left">Renames the variable "X" to "Y".</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
+ <entry align="left">Gets then named flag from the variable "X".
+ Using "expand=True" expands the named flag.</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry>
+ <entry align="left">Sets the named flag for variable "X" to "value".</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry>
+ <entry align="left">Appends "value" to the named flag on the
+ variable "X".</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry>
+ <entry align="left">Prepends "value" to the named flag on
+ the variable "X".</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
+ <entry align="left">Deletes the named flag on the variable
+ "X" from the datastore.</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
+ <entry align="left">Sets the flags specified in
+ the <filename>flagsdict()</filename> parameter.
+ <filename>setVarFlags</filename> does not clear previous flags.
+ Think of this operation as <filename>addVarFlags</filename>.</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
+ <entry align="left">Returns a <filename>flagsdict</filename> of the flags for
+ the variable "X".</entry>
+ </row>
+ <row>
+ <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
+ <entry align="left">Deletes all the flags for the variable "X".</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </section>
+
+ <section id='task-checksums-and-setscene'>
+ <title>Task Checksums and Setscene</title>
+
+ <para>
+ BitBake uses checksums (or signatures) along with the setscene
+ to determine if a task needs to be run.
+ This section describes the process.
+ To help understand how BitBake does this, the section assumes an
+ OpenEmbedded metadata-based example.
+ </para>
+
+ <para>
+ This list is a place holder of content existed from previous work
+ on the manual.
+ Some or all of it probably needs integrated into the subsections
+ that make up this section.
+ For now, I have just provided a short glossary-like description
+ for each variable.
+ Ultimately, this list goes away.
+ <itemizedlist>
+ <listitem><para><filename>STAMP</filename>:
+ The base path to create stamp files.</para></listitem>
+ <listitem><para><filename>STAMPCLEAN</filename>
+ Again, the base path to create stamp files but can use wildcards
+ for matching a range of files for clean operations.
+ </para></listitem>
+ <listitem><para><filename>BB_STAMP_WHITELIST</filename>
+ Lists stamp files that are looked at when the stamp policy
+ is "whitelist".
+ </para></listitem>
+ <listitem><para><filename>BB_STAMP_POLICY</filename>
+ Defines the mode for comparing timestamps of stamp files.
+ </para></listitem>
+ <listitem><para><filename>BB_HASHCHECK_FUNCTION</filename>
+ Specifies the name of the function to call during
+ the "setscene" part of the task's execution in order
+ to validate the list of task hashes.
+ </para></listitem>
+ <listitem><para><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
+ Specifies a function to call that verifies the list of
+ planned task execution before the main task execution
+ happens.
+ </para></listitem>
+ <listitem><para><filename>BB_SETSCENE_DEPVALID</filename>
+ Specifies a function BitBake calls that determines
+ whether BitBake requires a setscene dependency to
+ be met.
+ </para></listitem>
+ <listitem><para><filename>BB_TASKHASH</filename>
+ Within an executing task, this variable holds the hash
+ of the task as returned by the currently enabled
+ signature generator.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</chapter>
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
new file mode 100644
index 0000000..05e1b95
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml
@@ -0,0 +1,2262 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<!-- Dummy chapter -->
+<chapter id='ref-variables-glos'>
+
+<title>Variables Glossary</title>
+
+<para>
+ This chapter lists common variables used by BitBake and gives an overview
+ of their function and contents.
+</para>
+
+<note>
+ Following are some points regarding the variables listed in this glossary:
+ <itemizedlist>
+ <listitem><para>The variables listed in this glossary
+ are specific to BitBake.
+ Consequently, the descriptions are limited to that context.
+ </para></listitem>
+ <listitem><para>Also, variables exist in other systems that use BitBake
+ (e.g. The Yocto Project and OpenEmbedded) that have names identical
+ to those found in this glossary.
+ For such cases, the variables in those systems extend the
+ functionality of the variable as it is described here in
+ this glossary.
+ </para></listitem>
+ <listitem><para>Finally, there are variables mentioned in this
+ glossary that do not appear in the BitBake glossary.
+ These other variables are variables used in systems that use
+ BitBake.
+ </para></listitem>
+ </itemizedlist>
+</note>
+
+<glossary id='ref-variables-glossary'>
+
+ <para>
+ <link linkend='var-ASSUME_PROVIDED'>A</link>
+ <link linkend='var-B'>B</link>
+ <link linkend='var-CACHE'>C</link>
+ <link linkend='var-DEFAULT_PREFERENCE'>D</link>
+ <link linkend='var-EXCLUDE_FROM_WORLD'>E</link>
+ <link linkend='var-FAKEROOT'>F</link>
+ <link linkend='var-GITDIR'>G</link>
+ <link linkend='var-HGDIR'>H</link>
+<!-- <link linkend='var-ICECC_DISABLED'>I</link> -->
+<!-- <link linkend='var-glossary-j'>J</link> -->
+<!-- <link linkend='var-KARCH'>K</link> -->
+ <link linkend='var-LAYERDEPENDS'>L</link>
+ <link linkend='var-MIRRORS'>M</link>
+<!-- <link linkend='var-glossary-n'>N</link> -->
+ <link linkend='var-OVERRIDES'>O</link>
+ <link linkend='var-PACKAGES'>P</link>
+<!-- <link linkend='var-QMAKE_PROFILES'>Q</link> -->
+ <link linkend='var-RDEPENDS'>R</link>
+ <link linkend='var-SECTION'>S</link>
+ <link linkend='var-T'>T</link>
+<!-- <link linkend='var-UBOOT_CONFIG'>U</link> -->
+<!-- <link linkend='var-glossary-v'>V</link> -->
+<!-- <link linkend='var-WARN_QA'>W</link> -->
+<!-- <link linkend='var-glossary-x'>X</link> -->
+<!-- <link linkend='var-glossary-y'>Y</link> -->
+<!-- <link linkend='var-glossary-z'>Z</link>-->
+ </para>
+
+ <glossdiv id='var-glossary-a'><title>A</title>
+
+ <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
+ <glossdef>
+ <para>
+ Lists recipe names
+ (<link linkend='var-PN'><filename>PN</filename></link>
+ values) BitBake does not attempt to build.
+ Instead, BitBake assumes these recipes have already been
+ built.
+ </para>
+
+ <para>
+ In OpenEmbedded Core, <filename>ASSUME_PROVIDED</filename>
+ mostly specifies native tools that should not be built.
+ An example is <filename>git-native</filename>, which
+ when specified allows for the Git binary from the host to
+ be used rather than building
+ <filename>git-native</filename>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+
+ <glossdiv id='var-glossary-b'><title>B</title>
+
+ <glossentry id='var-B'><glossterm>B</glossterm>
+ <glossdef>
+ <para>
+ The directory in which BitBake executes functions
+ during a recipe's build process.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>
+ <glossdef>
+ <para>
+ Specifies a space-delimited list of hosts that the fetcher
+ is allowed to use to obtain the required source code.
+ Following are considerations surrounding this variable:
+ <itemizedlist>
+ <listitem><para>
+ This host list is only used if
+ <link linkend='var-BB_NO_NETWORK'><filename>BB_NO_NETWORK</filename></link>
+ is either not set or set to "0".
+ </para></listitem>
+ <listitem><para>
+ Limited support for wildcard matching against the
+ beginning of host names exists.
+ For example, the following setting matches
+ <filename>git.gnu.org</filename>,
+ <filename>ftp.gnu.org</filename>, and
+ <filename>foo.git.gnu.org</filename>.
+ <literallayout class='monospaced'>
+ BB_ALLOWED_NETWORKS = "*.gnu.org"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Mirrors not in the host list are skipped and
+ logged in debug.
+ </para></listitem>
+ <listitem><para>
+ Attempts to access networks not in the host list
+ cause a failure.
+ </para></listitem>
+ </itemizedlist>
+ Using <filename>BB_ALLOWED_NETWORKS</filename> in
+ conjunction with
+ <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
+ is very useful.
+ Adding the host you want to use to
+ <filename>PREMIRRORS</filename> results in the source code
+ being fetched from an allowed location and avoids raising
+ an error when a host that is not allowed is in a
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+ statement.
+ This is because the fetcher does not attempt to use the
+ host listed in <filename>SRC_URI</filename> after a
+ successful fetch from the
+ <filename>PREMIRRORS</filename> occurs.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_CONSOLELOG'><glossterm>BB_CONSOLELOG</glossterm>
+ <glossdef>
+ <para>
+ Specifies the path to a log file into which BitBake's user
+ interface writes output during the build.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_CURRENTTASK'><glossterm>BB_CURRENTTASK</glossterm>
+ <glossdef>
+ <para>
+ Contains the name of the currently running task.
+ The name does not include the
+ <filename>do_</filename> prefix.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
+ <glossdef>
+ <para>
+ Defines how BitBake handles situations where an append
+ file (<filename>.bbappend</filename>) has no
+ corresponding recipe file (<filename>.bb</filename>).
+ This condition often occurs when layers get out of sync
+ (e.g. <filename>oe-core</filename> bumps a
+ recipe version and the old recipe no longer exists and the
+ other layer has not been updated to the new version
+ of the recipe yet).
+ </para>
+
+ <para>
+ The default fatal behavior is safest because it is
+ the sane reaction given something is out of sync.
+ It is important to realize when your changes are no longer
+ being applied.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_DEFAULT_TASK'><glossterm>BB_DEFAULT_TASK</glossterm>
+ <glossdef>
+ <para>
+ The default task to use when none is specified (e.g.
+ with the <filename>-c</filename> command line option).
+ The task name specified should not include the
+ <filename>do_</filename> prefix.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
+ <glossdef>
+ <para>
+ Monitors disk space and available inodes during the build
+ and allows you to control the build based on these
+ parameters.
+ </para>
+
+ <para>
+ Disk space monitoring is disabled by default.
+ When setting this variable, use the following form:
+ <literallayout class='monospaced'>
+ BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]"
+
+ where:
+
+ <action> is:
+ ABORT: Immediately abort the build when
+ a threshold is broken.
+ STOPTASKS: Stop the build after the currently
+ executing tasks have finished when
+ a threshold is broken.
+ WARN: Issue a warning but continue the
+ build when a threshold is broken.
+ Subsequent warnings are issued as
+ defined by the
+ <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
+ which must be defined.
+
+ <dir> is:
+ Any directory you choose. You can specify one or
+ more directories to monitor by separating the
+ groupings with a space. If two directories are
+ on the same device, only the first directory
+ is monitored.
+
+ <threshold> is:
+ Either the minimum available disk space,
+ the minimum number of free inodes, or
+ both. You must specify at least one. To
+ omit one or the other, simply omit the value.
+ Specify the threshold using G, M, K for Gbytes,
+ Mbytes, and Kbytes, respectively. If you do
+ not specify G, M, or K, Kbytes is assumed by
+ default. Do not use GB, MB, or KB.
+ </literallayout>
+ </para>
+
+ <para>
+ Here are some examples:
+ <literallayout class='monospaced'>
+ BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
+ BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
+ BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
+ </literallayout>
+ The first example works only if you also set
+ the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable.
+ This example causes the build system to immediately
+ abort when either the disk space in <filename>${TMPDIR}</filename> drops
+ below 1 Gbyte or the available free inodes drops below
+ 100 Kbytes.
+ Because two directories are provided with the variable, the
+ build system also issues a
+ warning when the disk space in the
+ <filename>${SSTATE_DIR}</filename> directory drops
+ below 1 Gbyte or the number of free inodes drops
+ below 100 Kbytes.
+ Subsequent warnings are issued during intervals as
+ defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
+ variable.
+ </para>
+
+ <para>
+ The second example stops the build after all currently
+ executing tasks complete when the minimum disk space
+ in the <filename>${TMPDIR}</filename>
+ directory drops below 1 Gbyte.
+ No disk monitoring occurs for the free inodes in this case.
+ </para>
+
+ <para>
+ The final example immediately aborts the build when the
+ number of free inodes in the <filename>${TMPDIR}</filename> directory
+ drops below 100 Kbytes.
+ No disk space monitoring for the directory itself occurs
+ in this case.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
+ <glossdef>
+ <para>
+ Defines the disk space and free inode warning intervals.
+ </para>
+
+ <para>
+ If you are going to use the
+ <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
+ also use the
+ <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
+ and define its action as "WARN".
+ During the build, subsequent warnings are issued each time
+ disk space or number of free inodes further reduces by
+ the respective interval.
+ </para>
+
+ <para>
+ If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
+ variable and you do use <filename>BB_DISKMON_DIRS</filename> with
+ the "WARN" action, the disk monitoring interval defaults to
+ the following:
+ <literallayout class='monospaced'>
+ BB_DISKMON_WARNINTERVAL = "50M,5K"
+ </literallayout>
+ </para>
+
+ <para>
+ When specifying the variable in your configuration file,
+ use the following form:
+ <literallayout class='monospaced'>
+ BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>"
+
+ where:
+
+ <disk_space_interval> is:
+ An interval of memory expressed in either
+ G, M, or K for Gbytes, Mbytes, or Kbytes,
+ respectively. You cannot use GB, MB, or KB.
+
+ <disk_inode_interval> is:
+ An interval of free inodes expressed in either
+ G, M, or K for Gbytes, Mbytes, or Kbytes,
+ respectively. You cannot use GB, MB, or KB.
+ </literallayout>
+ </para>
+
+ <para>
+ Here is an example:
+ <literallayout class='monospaced'>
+ BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
+ BB_DISKMON_WARNINTERVAL = "50M,5K"
+ </literallayout>
+ These variables cause BitBake to
+ issue subsequent warnings each time the available
+ disk space further reduces by 50 Mbytes or the number
+ of free inodes further reduces by 5 Kbytes in the
+ <filename>${SSTATE_DIR}</filename> directory.
+ Subsequent warnings based on the interval occur each time
+ a respective interval is reached beyond the initial warning
+ (i.e. 1 Gbytes and 100 Kbytes).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_ENV_WHITELIST'><glossterm>BB_ENV_WHITELIST</glossterm>
+ <glossdef>
+ <para>
+ Specifies the internal whitelist of variables to allow
+ through from the external environment into BitBake's
+ datastore.
+ If the value of this variable is not specified
+ (which is the default), the following list is used:
+ <link linkend='var-BBPATH'><filename>BBPATH</filename></link>,
+ <link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>,
+ <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>,
+ and
+ <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>.
+ <note>
+ You must set this variable in the external environment
+ in order for it to work.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_ENV_EXTRAWHITE'><glossterm>BB_ENV_EXTRAWHITE</glossterm>
+ <glossdef>
+ <para>
+ Specifies an additional set of variables to allow through
+ (whitelist) from the external environment into BitBake's
+ datastore.
+ This list of variables are on top of the internal list
+ set in
+ <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>.
+ <note>
+ You must set this variable in the external
+ environment in order for it to work.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_FETCH_PREMIRRORONLY'><glossterm>BB_FETCH_PREMIRRORONLY</glossterm>
+ <glossdef>
+ <para>
+ When set to "1", causes BitBake's fetcher module to only
+ search
+ <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
+ for files.
+ BitBake will not search the main
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+ or
+ <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_FILENAME'><glossterm>BB_FILENAME</glossterm>
+ <glossdef>
+ <para>
+ Contains the filename of the recipe that owns the currently
+ running task.
+ For example, if the <filename>do_fetch</filename> task that
+ resides in the <filename>my-recipe.bb</filename> is
+ executing, the <filename>BB_FILENAME</filename> variable
+ contains "/foo/path/my-recipe.bb".
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
+ <glossdef>
+ <para>
+ Causes tarballs of the Git repositories, including the
+ Git metadata, to be placed in the
+ <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+ directory.
+ Anyone wishing to create a source mirror would want to
+ enable this variable.
+ </para>
+
+ <para>
+ For performance reasons, creating and placing tarballs of
+ the Git repositories is not the default action by BitBake.
+ <literallayout class='monospaced'>
+ BB_GENERATE_MIRROR_TARBALLS = "1"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm>
+ <glossdef>
+ <para>
+ Lists variables that are excluded from base configuration
+ checksum, which is used to determine if the cache can
+ be reused.
+ </para>
+
+ <para>
+ One of the ways BitBake determines whether to re-parse the
+ main metadata is through checksums of the variables in the
+ datastore of the base configuration data.
+ There are variables that you typically want to exclude when
+ checking whether or not to re-parse and thus rebuild the
+ cache.
+ As an example, you would usually exclude
+ <filename>TIME</filename> and <filename>DATE</filename>
+ because these variables are always changing.
+ If you did not exclude them, BitBake would never reuse the
+ cache.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_HASHBASE_WHITELIST'><glossterm>BB_HASHBASE_WHITELIST</glossterm>
+ <glossdef>
+ <para>
+ Lists variables that are excluded from checksum and
+ dependency data.
+ Variables that are excluded can therefore change without
+ affecting the checksum mechanism.
+ A common example would be the variable for the path of
+ the build.
+ BitBake's output should not (and usually does not) depend
+ on the directory in which it was built.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_HASHCHECK_FUNCTION'><glossterm>BB_HASHCHECK_FUNCTION</glossterm>
+ <glossdef>
+ <para>
+ Specifies the name of the function to call during the
+ "setscene" part of the task's execution in order to
+ validate the list of task hashes.
+ The function returns the list of setscene tasks that should
+ be executed.
+ </para>
+
+ <para>
+ At this point in the execution of the code, the objective
+ is to quickly verify if a given setscene function is likely
+ to work or not.
+ It's easier to check the list of setscene functions in
+ one pass than to call many individual tasks.
+ The returned list need not be completely accurate.
+ A given setscene task can still later fail.
+ However, the more accurate the data returned, the more
+ efficient the build will be.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_INVALIDCONF'><glossterm>BB_INVALIDCONF</glossterm>
+ <glossdef>
+ <para>
+ Used in combination with the
+ <filename>ConfigParsed</filename> event to trigger
+ re-parsing the base metadata (i.e. all the
+ recipes).
+ The <filename>ConfigParsed</filename> event can set the
+ variable to trigger the re-parse.
+ You must be careful to avoid recursive loops with this
+ functionality.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm>
+ <glossdef>
+ <para>
+ Specifies the name of the log files saved into
+ <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
+ By default, the <filename>BB_LOGFMT</filename> variable
+ is undefined and the log file names get created using the
+ following form:
+ <literallayout class='monospaced'>
+ log.{task}.{pid}
+ </literallayout>
+ If you want to force log files to take a specific name,
+ you can set this variable in a configuration file.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm>
+ <glossdef>
+ <para>
+ Allows BitBake to run at a specific priority
+ (i.e. nice level).
+ System permissions usually mean that BitBake can reduce its
+ priority but not raise it again.
+ See
+ <link linkend='var-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link>
+ for additional information.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_NO_NETWORK'><glossterm>BB_NO_NETWORK</glossterm>
+ <glossdef>
+ <para>
+ Disables network access in the BitBake fetcher modules.
+ With this access disabled, any command that attempts to
+ access the network becomes an error.
+ </para>
+
+ <para>
+ Disabling network access is useful for testing source
+ mirrors, running builds when not connected to the Internet,
+ and when operating in certain kinds of firewall
+ environments.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
+ <glossdef>
+ <para>
+ The maximum number of tasks BitBake should run in parallel
+ at any one time.
+ If your host development system supports multiple cores,
+ a good rule of thumb is to set this variable to twice the
+ number of cores.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_NUMBER_PARSE_THREADS'><glossterm>BB_NUMBER_PARSE_THREADS</glossterm>
+ <glossdef>
+ <para>
+ Sets the number of threads BitBake uses when parsing.
+ By default, the number of threads is equal to the number
+ of cores on the system.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_ORIGENV'><glossterm>BB_ORIGENV</glossterm>
+ <glossdef>
+ <para>
+ Contains a copy of the original external environment in
+ which BitBake was run.
+ The copy is taken before any whitelisted variable values
+ are filtered into BitBake's datastore.
+ <note>
+ The contents of this variable is a datastore object
+ that can be queried using the normal datastore
+ operations.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_PRESERVE_ENV'><glossterm>BB_PRESERVE_ENV</glossterm>
+ <glossdef>
+ <para>
+ Disables whitelisting and instead allows all variables
+ through from the external environment into BitBake's
+ datastore.
+ <note>
+ You must set this variable in the external
+ environment in order for it to work.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_RUNFMT'><glossterm>BB_RUNFMT</glossterm>
+ <glossdef>
+ <para>
+ Specifies the name of the executable script files
+ (i.e. run files) saved into
+ <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
+ By default, the <filename>BB_RUNFMT</filename> variable
+ is undefined and the run file names get created using the
+ following form:
+ <literallayout class='monospaced'>
+ run.{task}.{pid}
+ </literallayout>
+ If you want to force run files to take a specific name,
+ you can set this variable in a configuration file.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_RUNTASK'><glossterm>BB_RUNTASK</glossterm>
+ <glossdef>
+ <para>
+ Contains the name of the currently executing task.
+ The value does not include the "do_" prefix.
+ For example, if the currently executing task is
+ <filename>do_config</filename>, the value is
+ "config".
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_SCHEDULER'><glossterm>BB_SCHEDULER</glossterm>
+ <glossdef>
+ <para>
+ Selects the name of the scheduler to use for the
+ scheduling of BitBake tasks.
+ Three options exist:
+ <itemizedlist>
+ <listitem><para><emphasis>basic</emphasis> -
+ The basic framework from which everything derives.
+ Using this option causes tasks to be ordered
+ numerically as they are parsed.
+ </para></listitem>
+ <listitem><para><emphasis>speed</emphasis> -
+ Executes tasks first that have more tasks
+ depending on them.
+ The "speed" option is the default.
+ </para></listitem>
+ <listitem><para><emphasis>completion</emphasis> -
+ Causes the scheduler to try to complete a given
+ recipe once its build has started.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_SCHEDULERS'><glossterm>BB_SCHEDULERS</glossterm>
+ <glossdef>
+ <para>
+ Defines custom schedulers to import.
+ Custom schedulers need to be derived from the
+ <filename>RunQueueScheduler</filename> class.
+ </para>
+
+ <para>
+ For information how to select a scheduler, see the
+ <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
+ variable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_SETSCENE_DEPVALID'><glossterm>BB_SETSCENE_DEPVALID</glossterm>
+ <glossdef>
+ <para>
+ Specifies a function BitBake calls that determines
+ whether BitBake requires a setscene dependency to be met.
+ </para>
+
+ <para>
+ When running a setscene task, BitBake needs to
+ know which dependencies of that setscene task also need
+ to be run.
+ Whether dependencies also need to be run is highly
+ dependent on the metadata.
+ The function specified by this variable returns a
+ "True" or "False" depending on whether the dependency needs
+ to be met.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_SETSCENE_VERIFY_FUNCTION'><glossterm>BB_SETSCENE_VERIFY_FUNCTION</glossterm>
+ <glossdef>
+ <para>
+ Specifies a function to call that verifies the list of
+ planned task execution before the main task execution
+ happens.
+ The function is called once BitBake has a list of setscene
+ tasks that have run and either succeeded or failed.
+ </para>
+
+ <para>
+ The function allows for a task list check to see if they
+ make sense.
+ Even if BitBake was planning to skip a task, the
+ returned value of the function can force BitBake to run
+ the task, which is necessary under certain metadata
+ defined circumstances.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm>
+ <glossdef>
+ <para>
+ Lists variable flags (varflags)
+ that can be safely excluded from checksum
+ and dependency data for keys in the datastore.
+ When generating checksum or dependency data for keys in the
+ datastore, the flags set against that key are normally
+ included in the checksum.
+ </para>
+
+ <para>
+ For more information on varflags, see the
+ "<link linkend='variable-flags'>Variable Flags</link>"
+ section.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_SIGNATURE_HANDLER'><glossterm>BB_SIGNATURE_HANDLER</glossterm>
+ <glossdef>
+ <para>
+ Defines the name of the signature handler BitBake uses.
+ The signature handler defines the way stamp files are
+ created and handled, if and how the signature is
+ incorporated into the stamps, and how the signature
+ itself is generated.
+ </para>
+
+ <para>
+ A new signature handler can be added by injecting a class
+ derived from the
+ <filename>SignatureGenerator</filename> class into the
+ global namespace.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_SRCREV_POLICY'><glossterm>BB_SRCREV_POLICY</glossterm>
+ <glossdef>
+ <para>
+ Defines the behavior of the fetcher when it interacts with
+ source control systems and dynamic source revisions.
+ The <filename>BB_SRCREV_POLICY</filename> variable is
+ useful when working without a network.
+ </para>
+
+ <para>
+ The variable can be set using one of two policies:
+ <itemizedlist>
+ <listitem><para><emphasis>cache</emphasis> -
+ Retains the value the system obtained previously
+ rather than querying the source control system
+ each time.
+ </para></listitem>
+ <listitem><para><emphasis>clear</emphasis> -
+ Queries the source controls system every time.
+ With this policy, there is no cache.
+ The "clear" policy is the default.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_STAMP_POLICY'><glossterm>BB_STAMP_POLICY</glossterm>
+ <glossdef>
+ <para>
+ Defines the mode used for how timestamps of stamp files
+ are compared.
+ You can set the variable to one of the following modes:
+ <itemizedlist>
+ <listitem><para><emphasis>perfile</emphasis> -
+ Timestamp comparisons are only made
+ between timestamps of a specific recipe.
+ This is the default mode.
+ </para></listitem>
+ <listitem><para><emphasis>full</emphasis> -
+ Timestamp comparisons are made for all
+ dependencies.
+ </para></listitem>
+ <listitem><para><emphasis>whitelist</emphasis> -
+ Identical to "full" mode except timestamp
+ comparisons are made for recipes listed in the
+ <link linkend='var-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>
+ variable.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ Stamp policies are largely obsolete with the
+ introduction of setscene tasks.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_STAMP_WHITELIST'><glossterm>BB_STAMP_WHITELIST</glossterm>
+ <glossdef>
+ <para>
+ Lists files whose stamp file timestamps are compared when
+ the stamp policy mode is set to "whitelist".
+ For information on stamp policies, see the
+ <link linkend='var-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>
+ variable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_STRICT_CHECKSUM'><glossterm>BB_STRICT_CHECKSUM</glossterm>
+ <glossdef>
+ <para>
+ Sets a more strict checksum mechanism for non-local URLs.
+ Setting this variable to a value causes BitBake
+ to report an error if it encounters a non-local URL
+ that does not have at least one checksum specified.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm>
+ <glossdef>
+ <para>
+ Allows specific tasks to change their priority
+ (i.e. nice level).
+ </para>
+
+ <para>
+ You can use this variable in combination with task
+ overrides to raise or lower priorities of specific tasks.
+ For example, on the
+ <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>
+ autobuilder, QEMU emulation in images is given a higher
+ priority as compared to build tasks to ensure that images
+ do not suffer timeouts on loaded systems.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_TASKHASH'><glossterm>BB_TASKHASH</glossterm>
+ <glossdef>
+ <para>
+ Within an executing task, this variable holds the hash
+ of the task as returned by the currently enabled
+ signature generator.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_VERBOSE_LOGS'><glossterm>BB_VERBOSE_LOGS</glossterm>
+ <glossdef>
+ <para>
+ Controls how verbose BitBake is during builds.
+ If set, shell scripts echo commands and shell script output
+ appears on standard out (stdout).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_WORKERCONTEXT'><glossterm>BB_WORKERCONTEXT</glossterm>
+ <glossdef>
+ <para>
+ Specifies if the current context is executing a task.
+ BitBake sets this variable to "1" when a task is
+ being executed.
+ The value is not set when the task is in server context
+ during parsing or event handling.
+ </para>
+ </glossdef>
+ </glossentry>
+
+
+ <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
+ <glossdef>
+ <para>
+ Allows you to extend a recipe so that it builds variants
+ of the software.
+ Some examples of these variants for recipes from the
+ OpenEmbedded Core metadata are "natives" such as
+ <filename>quilt-native</filename>, which is a copy of
+ Quilt built to run on the build system; "crosses" such
+ as <filename>gcc-cross</filename>, which is a compiler
+ built to run on the build machine but produces binaries
+ that run on the target <filename>MACHINE</filename>;
+ "nativesdk", which targets the SDK machine instead of
+ <filename>MACHINE</filename>; and "mulitlibs" in the form
+ "<filename>multilib:</filename><replaceable>multilib_name</replaceable>".
+ </para>
+
+ <para>
+ To build a different variant of the recipe with a minimal
+ amount of code, it usually is as simple as adding the
+ variable to your recipe.
+ Here are two examples.
+ The "native" variants are from the OpenEmbedded Core
+ metadata:
+ <literallayout class='monospaced'>
+ BBCLASSEXTEND =+ "native nativesdk"
+ BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBDEBUG'><glossterm>BBDEBUG</glossterm>
+ <glossdef>
+ <para>
+ Sets the BitBake debug output level to a specific value
+ as incremented by the <filename>-d</filename> command line
+ option.
+ <note>
+ You must set this variable in the external environment
+ in order for it to work.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
+ <glossdef>
+ <para>Lists the names of configured layers.
+ These names are used to find the other <filename>BBFILE_*</filename>
+ variables.
+ Typically, each layer appends its name to this variable in its
+ <filename>conf/layer.conf</filename> file.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
+ <glossdef>
+ <para>Variable that expands to match files from
+ <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
+ in a particular layer.
+ This variable is used in the <filename>conf/layer.conf</filename> file and must
+ be suffixed with the name of the specific layer (e.g.
+ <filename>BBFILE_PATTERN_emenlow</filename>).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
+ <glossdef>
+ <para>Assigns the priority for recipe files in each layer.</para>
+ <para>This variable is useful in situations where the same recipe appears in
+ more than one layer.
+ Setting this variable allows you to prioritize a
+ layer against other layers that contain the same recipe - effectively
+ letting you control the precedence for the multiple layers.
+ The precedence established through this variable stands regardless of a
+ recipe's version
+ (<link linkend='var-PV'><filename>PV</filename></link> variable).
+ For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
+ which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
+ lower precedence.</para>
+ <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
+ precedence.
+ For example, the value 6 has a higher precedence than the value 5.
+ If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
+ dependencies (see the
+ <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
+ more information.
+ The default priority, if unspecified
+ for a layer with no dependencies, is the lowest defined priority + 1
+ (or 1 if no priorities are defined).</para>
+ <tip>
+ You can use the command <filename>bitbake-layers show-layers</filename> to list
+ all configured layers along with their priorities.
+ </tip>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
+ <glossdef>
+ <para>List of recipe files BitBake uses to build software.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBINCLUDED'><glossterm>BBINCLUDED</glossterm>
+ <glossdef>
+ <para>
+ Contains a space-separated list of all of all files that
+ BitBake's parser included during parsing of the current
+ file.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
+ <glossdef>
+ <para>
+ If set to a value, enables printing the task log when
+ reporting a failed task.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
+ <glossdef>
+ <para>
+ If
+ <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
+ is set, specifies the maximum number of lines from the
+ task log file to print when reporting a failed task.
+ If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
+ the entire log is printed.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
+ <glossdef>
+ <para>Lists the layers to enable during the build.
+ This variable is defined in the <filename>bblayers.conf</filename> configuration
+ file in the build directory.
+ Here is an example:
+ <literallayout class='monospaced'>
+ BBLAYERS = " \
+ /home/scottrif/poky/meta \
+ /home/scottrif/poky/meta-yocto \
+ /home/scottrif/poky/meta-yocto-bsp \
+ /home/scottrif/poky/meta-mykernel \
+ "
+
+ </literallayout>
+ This example enables four layers, one of which is a custom, user-defined layer
+ named <filename>meta-mykernel</filename>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBLAYERS_FETCH_DIR'><glossterm>BBLAYERS_FETCH_DIR</glossterm>
+ <glossdef>
+ <para>
+ Sets the base location where layers are stored.
+ By default, this location is set to
+ <filename>${COREBASE}</filename>.
+ This setting is used in conjunction with
+ <filename>bitbake-layers layerindex-fetch</filename> and
+ tells <filename>bitbake-layers</filename> where to place
+ the fetched layers.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
+ <glossdef>
+ <para>
+ Prevents BitBake from processing recipes and recipe
+ append files.
+ </para>
+
+ <para>
+ You can use the <filename>BBMASK</filename> variable
+ to "hide" these <filename>.bb</filename> and
+ <filename>.bbappend</filename> files.
+ BitBake ignores any recipe or recipe append files that
+ match the expression.
+ It is as if BitBake does not see them at all.
+ Consequently, matching files are not parsed or otherwise
+ used by BitBake.</para>
+ <para>
+ The value you provide is passed to Python's regular
+ expression compiler.
+ The expression is compared against the full paths to
+ the files.
+ For complete syntax information, see Python's
+ documentation at
+ <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
+ </para>
+
+ <para>
+ The following example uses a complete regular expression
+ to tell BitBake to ignore all recipe and recipe append
+ files in the <filename>meta-ti/recipes-misc/</filename>
+ directory:
+ <literallayout class='monospaced'>
+ BBMASK = "meta-ti/recipes-misc/"
+ </literallayout>
+ If you want to mask out multiple directories or recipes,
+ use the vertical bar to separate the regular expression
+ fragments.
+ This next example masks out multiple directories and
+ individual recipes:
+ <literallayout class='monospaced'>
+ BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
+ BBMASK .= "|.*meta-oe/recipes-support/"
+ BBMASK .= "|.*openldap"
+ BBMASK .= "|.*opencv"
+ BBMASK .= "|.*lzma"
+ </literallayout>
+ Notice how the vertical bar is used to append the fragments.
+ <note>
+ When specifying a directory name, use the trailing
+ slash character to ensure you match just that directory
+ name.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
+ <glossdef>
+ <para>
+ Used by BitBake to locate class
+ (<filename>.bbclass</filename>) and configuration
+ (<filename>.conf</filename>) files.
+ This variable is analogous to the
+ <filename>PATH</filename> variable.
+ </para>
+
+ <para>
+ If you run BitBake from a directory outside of the
+ build directory,
+ you must be sure to set
+ <filename>BBPATH</filename> to point to the
+ build directory.
+ Set the variable as you would any environment variable
+ and then run BitBake:
+ <literallayout class='monospaced'>
+ $ BBPATH="<replaceable>build_directory</replaceable>"
+ $ export BBPATH
+ $ bitbake <replaceable>target</replaceable>
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
+ <glossdef>
+ <para>
+ Points to the server that runs memory-resident BitBake.
+ The variable is only used when you employ memory-resident
+ BitBake.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BBVERSIONS'><glossterm>BBVERSIONS</glossterm>
+ <glossdef>
+ <para>
+ Allows a single recipe to build multiple versions of a
+ project from a single recipe file.
+ You also able to specify conditional metadata
+ using the
+ <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
+ mechanism for a single version or for an optionally named
+ range of versions.
+ </para>
+
+ <para>
+ For more information on <filename>BBVERSIONS</filename>,
+ see the
+ "<link linkend='variants-class-extension-mechanism'>Variants - Class Extension Mechanism</link>"
+ section.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BITBAKE_UI'><glossterm>BITBAKE_UI</glossterm>
+ <glossdef>
+ <para>
+ Used to specify the UI module to use when running BitBake.
+ Using this variable is equivalent to using the
+ <filename>-u</filename> command-line option.
+ <note>
+ You must set this variable in the external environment
+ in order for it to work.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BUILDNAME'><glossterm>BUILDNAME</glossterm>
+ <glossdef>
+ <para>
+ A name assigned to the build.
+ The name defaults to a datetime stamp of when the build was
+ started but can be defined by the metadata.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BZRDIR'><glossterm>BZRDIR</glossterm>
+ <glossdef>
+ <para>
+ The directory in which files checked out of a Bazaar
+ system are stored.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id='var-glossary-c'><title>C</title>
+
+ <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
+ <glossdef>
+ <para>
+ Specifies the directory BitBake uses to store a cache
+ of the metadata so it does not need to be parsed every
+ time BitBake is started.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>
+ <glossdef>
+ <para>
+ The directory in which files checked out under the
+ CVS system are stored.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id='var-glossary-d'><title>D</title>
+
+ <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
+ <glossdef>
+ <para>
+ Specifies a weak bias for recipe selection priority.
+ </para>
+ <para>
+ The most common usage of this is variable is to set
+ it to "-1" within a recipe for a development version of a
+ piece of software.
+ Using the variable in this way causes the stable version
+ of the recipe to build by default in the absence of
+ <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
+ being used to build the development version.
+ </para>
+ <note>
+ The bias provided by <filename>DEFAULT_PREFERENCE</filename>
+ is weak and is overridden by
+ <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
+ if that variable is different between two layers
+ that contain different versions of the same recipe.
+ </note>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
+ <glossdef>
+ <para>
+ Lists a recipe's build-time dependencies
+ (i.e. other recipe files).
+ </para>
+
+ <para>
+ Consider this simple example for two recipes named "a" and
+ "b" that produce similarly named packages.
+ In this example, the <filename>DEPENDS</filename>
+ statement appears in the "a" recipe:
+ <literallayout class='monospaced'>
+ DEPENDS = "b"
+ </literallayout>
+ Here, the dependency is such that the
+ <filename>do_configure</filename> task for recipe "a"
+ depends on the <filename>do_populate_sysroot</filename>
+ task of recipe "b".
+ This means anything that recipe "b" puts into sysroot
+ is available when recipe "a" is configuring itself.
+ </para>
+
+ <para>
+ For information on runtime dependencies, see the
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+ variable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
+ <glossdef>
+ <para>
+ A long description for the recipe.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
+ <glossdef>
+ <para>
+ The central download directory used by the build process to
+ store downloads.
+ By default, <filename>DL_DIR</filename> gets files
+ suitable for mirroring for everything except Git
+ repositories.
+ If you want tarballs of Git repositories, use the
+ <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
+ variable.
+ </para>
+ </glossdef>
+
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id='var-glossary-e'><title>E</title>
+
+ <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
+ <glossdef>
+ <para>
+ Directs BitBake to exclude a recipe from world builds (i.e.
+ <filename>bitbake world</filename>).
+ During world builds, BitBake locates, parses and builds all
+ recipes found in every layer exposed in the
+ <filename>bblayers.conf</filename> configuration file.
+ </para>
+
+ <para>
+ To exclude a recipe from a world build using this variable,
+ set the variable to "1" in the recipe.
+ </para>
+
+ <note>
+ Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
+ may still be built during a world build in order to satisfy
+ dependencies of other recipes.
+ Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
+ only ensures that the recipe is not explicitly added
+ to the list of build targets in a world build.
+ </note>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id='var-glossary-f'><title>F</title>
+
+ <glossentry id='var-FAKEROOT'><glossterm>FAKEROOT</glossterm>
+ <glossdef>
+ <para>
+ Contains the command to use when running a shell script
+ in a fakeroot environment.
+ The <filename>FAKEROOT</filename> variable is obsolete
+ and has been replaced by the other
+ <filename>FAKEROOT*</filename> variables.
+ See these entries in the glossary for more information.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FAKEROOTBASEENV'><glossterm>FAKEROOTBASEENV</glossterm>
+ <glossdef>
+ <para>
+ Lists environment variables to set when executing
+ the command defined by
+ <link linkend='var-FAKEROOTCMD'><filename>FAKEROOTCMD</filename></link>
+ that starts the bitbake-worker process
+ in the fakeroot environment.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FAKEROOTCMD'><glossterm>FAKEROOTCMD</glossterm>
+ <glossdef>
+ <para>
+ Contains the command that starts the bitbake-worker
+ process in the fakeroot environment.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FAKEROOTDIRS'><glossterm>FAKEROOTDIRS</glossterm>
+ <glossdef>
+ <para>
+ Lists directories to create before running a task in
+ the fakeroot environment.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FAKEROOTENV'><glossterm>FAKEROOTENV</glossterm>
+ <glossdef>
+ <para>
+ Lists environment variables to set when running a task
+ in the fakeroot environment.
+ For additional information on environment variables and
+ the fakeroot environment, see the
+ <link linkend='var-FAKEROOTBASEENV'><filename>FAKEROOTBASEENV</filename></link>
+ variable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FAKEROOTNOENV'><glossterm>FAKEROOTNOENV</glossterm>
+ <glossdef>
+ <para>
+ Lists environment variables to set when running a task
+ that is not in the fakeroot environment.
+ For additional information on environment variables and
+ the fakeroot environment, see the
+ <link linkend='var-FAKEROOTENV'><filename>FAKEROOTENV</filename></link>
+ variable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FETCHCMD'><glossterm>FETCHCMD</glossterm>
+ <glossdef>
+ <para>
+ Defines the command the BitBake fetcher module
+ executes when running fetch operations.
+ You need to use an override suffix when you use the
+ variable (e.g. <filename>FETCHCMD_git</filename>
+ or <filename>FETCHCMD_svn</filename>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FILE'><glossterm>FILE</glossterm>
+ <glossdef>
+ <para>
+ Points at the current file.
+ BitBake sets this variable during the parsing process
+ to identify the file being parsed.
+ BitBake also sets this variable when a recipe is being
+ executed to identify the recipe file.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FILESDIR'><glossterm>FILESDIR</glossterm>
+ <glossdef>
+ <para>
+ Specifies directories BitBake uses when searching for
+ patches and files.
+ The "local" fetcher module uses these directories when
+ handling <filename>file://</filename> URLs if the file
+ was not found using
+ <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
+ <note>
+ The <filename>FILESDIR</filename> variable is
+ deprecated and you should use
+ <filename>FILESPATH</filename> in all new code.
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
+ <glossdef>
+ <para>
+ Specifies directories BitBake uses when searching for
+ patches and files.
+ The "local" fetcher module uses these directories when
+ handling <filename>file://</filename> URLs.
+ The variable behaves like a shell <filename>PATH</filename>
+ environment variable.
+ The value is a colon-separated list of directories that
+ are searched left-to-right in order.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+
+ <glossdiv id='var-glossary-g'><title>G</title>
+
+ <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>
+ <glossdef>
+ <para>
+ The directory in which a local copy of a Git repository
+ is stored when it is cloned.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+
+ <glossdiv id='var-glossary-h'><title>H</title>
+
+ <glossentry id='var-HGDIR'><glossterm>HGDIR</glossterm>
+ <glossdef>
+ <para>
+ The directory in which files checked out of a Mercurial
+ system are stored.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
+ <glossdef>
+ <para>Website where more information about the software the recipe is building
+ can be found.</para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id='var-glossary-i'><title>I</title>
+
+ <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
+ <glossdef>
+ <para>
+ Causes the named class to be inherited at
+ this point during parsing.
+ The variable is only valid in configuration files.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+<!--
+ <glossdiv id='var-glossary-j'><title>J</title>
+ </glossdiv>
+
+ <glossdiv id='var-glossary-k'><title>K</title>
+ </glossdiv>
+-->
+
+ <glossdiv id='var-glossary-l'><title>L</title>
+
+ <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
+ <glossdef>
+ <para>Lists the layers, separated by spaces, upon which this recipe depends.
+ Optionally, you can specify a specific layer version for a dependency
+ by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
+ to be compared against
+ <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
+ in this case).
+ BitBake produces an error if any dependency is missing or
+ the version numbers do not match exactly (if specified).</para>
+ <para>
+ You use this variable in the <filename>conf/layer.conf</filename> file.
+ You must also use the specific layer name as a suffix
+ to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
+ <glossdef>
+ <para>When used inside the <filename>layer.conf</filename> configuration
+ file, this variable provides the path of the current layer.
+ This variable is not available outside of <filename>layer.conf</filename>
+ and references are expanded immediately when parsing of the file completes.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
+ <glossdef>
+ <para>Optionally specifies the version of a layer as a single number.
+ You can use this variable within
+ <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
+ for another layer in order to depend on a specific version
+ of the layer.</para>
+ <para>
+ You use this variable in the <filename>conf/layer.conf</filename> file.
+ You must also use the specific layer name as a suffix
+ to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
+ <glossdef>
+ <para>
+ The list of source licenses for the recipe.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id='var-glossary-m'><title>M</title>
+
+ <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
+ <glossdef>
+ <para>
+ Specifies additional paths from which BitBake gets source code.
+ When the build system searches for source code, it first
+ tries the local download directory.
+ If that location fails, the build system tries locations
+ defined by
+ <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
+ the upstream source, and then locations specified by
+ <filename>MIRRORS</filename> in that order.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-MULTI_PROVIDER_WHITELIST'><glossterm>MULTI_PROVIDER_WHITELIST</glossterm>
+ <glossdef>
+ <para>
+ Allows you to suppress BitBake warnings caused when
+ building two separate recipes that provide the same
+ output.
+ </para>
+
+ <para>
+ Bitbake normally issues a warning when building two
+ different recipes where each provides the same output.
+ This scenario is usually something the user does not
+ want.
+ However, cases do exist where it makes sense, particularly
+ in the <filename>virtual/*</filename> namespace.
+ You can use this variable to suppress BitBake's warnings.
+ </para>
+
+ <para>
+ To use the variable, list provider names (e.g.
+ recipe names, <filename>virtual/kernel</filename>,
+ and so forth).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+<!--
+ <glossdiv id='var-glossary-n'><title>N</title>
+ </glossdiv>
+-->
+
+ <glossdiv id='var-glossary-o'><title>O</title>
+
+ <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
+ <glossdef>
+ <para>
+ BitBake uses <filename>OVERRIDES</filename> to control
+ what variables are overridden after BitBake parses
+ recipes and configuration files.
+ </para>
+
+ <para>
+ Following is a simple example that uses an overrides
+ list based on machine architectures:
+ <literallayout class='monospaced'>
+ OVERRIDES = "arm:x86:mips:powerpc"
+ </literallayout>
+ You can find information on how to use
+ <filename>OVERRIDES</filename> in the
+ "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>"
+ section.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id='var-glossary-p'><title>P</title>
+
+ <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
+ <glossdef>
+ <para>The list of packages the recipe creates.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
+ <glossdef>
+ <para>
+ A promise that your recipe satisfies runtime dependencies
+ for optional modules that are found in other recipes.
+ <filename>PACKAGES_DYNAMIC</filename>
+ does not actually satisfy the dependencies, it only states that
+ they should be satisfied.
+ For example, if a hard, runtime dependency
+ (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
+ of another package is satisfied during the build
+ through the <filename>PACKAGES_DYNAMIC</filename>
+ variable, but a package with the module name is never actually
+ produced, then the other package will be broken.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PE'><glossterm>PE</glossterm>
+ <glossdef>
+ <para>
+ The epoch of the recipe.
+ By default, this variable is unset.
+ The variable is used to make upgrades possible when the
+ versioning scheme changes in some backwards incompatible
+ way.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PERSISTENT_DIR'><glossterm>PERSISTENT_DIR</glossterm>
+ <glossdef>
+ <para>
+ Specifies the directory BitBake uses to store data that
+ should be preserved between builds.
+ In particular, the data stored is the data that uses
+ BitBake's persistent data API and the data used by the
+ PR Server and PR Service.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PF'><glossterm>PF</glossterm>
+ <glossdef>
+ <para>
+ Specifies the recipe or package name and includes all version and revision
+ numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
+ <filename>bash-4.2-r1/</filename>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PN'><glossterm>PN</glossterm>
+ <glossdef>
+ <para>The recipe name.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PR'><glossterm>PR</glossterm>
+ <glossdef>
+ <para>The revision of the recipe.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
+ <glossdef>
+ <para>
+ Determines which recipe should be given preference when
+ multiple recipes provide the same item.
+ You should always suffix the variable with the name of the
+ provided item, and you should set it to the
+ <link linkend='var-PN'><filename>PN</filename></link>
+ of the recipe to which you want to give precedence.
+ Some examples:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+ PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
+ PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PREFERRED_PROVIDERS'><glossterm>PREFERRED_PROVIDERS</glossterm>
+ <glossdef>
+ <para>
+ Determines which recipe should be given preference for
+ cases where multiple recipes provide the same item.
+ Functionally,
+ <filename>PREFERRED_PROVIDERS</filename> is identical to
+ <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>.
+ However, the <filename>PREFERRED_PROVIDERS</filename>
+ variable lets you define preferences for multiple
+ situations using the following form:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
+ </literallayout>
+ This form is a convenient replacement for the following:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_xxx = "yyy"
+ PREFERRED_PROVIDER_aaa = "bbb"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
+ <glossdef>
+ <para>
+ If there are multiple versions of recipes available, this
+ variable determines which recipe should be given preference.
+ You must always suffix the variable with the
+ <link linkend='var-PN'><filename>PN</filename></link>
+ you want to select, and you should set
+ <link linkend='var-PV'><filename>PV</filename></link>
+ accordingly for precedence.
+ You can use the "<filename>%</filename>" character as a
+ wildcard to match any number of characters, which can be
+ useful when specifying versions that contain long revision
+ numbers that could potentially change.
+ Here are two examples:
+ <literallayout class='monospaced'>
+ PREFERRED_VERSION_python = "2.7.3"
+ PREFERRED_VERSION_linux-yocto = "3.10%"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
+ <glossdef>
+ <para>
+ Specifies additional paths from which BitBake gets source code.
+ When the build system searches for source code, it first
+ tries the local download directory.
+ If that location fails, the build system tries locations
+ defined by <filename>PREMIRRORS</filename>, the upstream
+ source, and then locations specified by
+ <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
+ in that order.
+ </para>
+
+ <para>
+ Typically, you would add a specific server for the
+ build system to attempt before any others by adding
+ something like the following to your configuration:
+ <literallayout class='monospaced'>
+ PREMIRRORS_prepend = "\
+ git://.*/.* http://www.yoctoproject.org/sources/ \n \
+ ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
+ http://.*/.* http://www.yoctoproject.org/sources/ \n \
+ https://.*/.* http://www.yoctoproject.org/sources/ \n"
+ </literallayout>
+ These changes cause the build system to intercept
+ Git, FTP, HTTP, and HTTPS requests and direct them to
+ the <filename>http://</filename> sources mirror.
+ You can use <filename>file://</filename> URLs to point
+ to local directories or network shares as well.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
+ <glossdef>
+ <para>
+ A list of aliases by which a particular recipe can be
+ known.
+ By default, a recipe's own
+ <filename><link linkend='var-PN'>PN</link></filename>
+ is implicitly already in its <filename>PROVIDES</filename>
+ list.
+ If a recipe uses <filename>PROVIDES</filename>, the
+ additional aliases are synonyms for the recipe and can
+ be useful satisfying dependencies of other recipes during
+ the build as specified by
+ <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
+ </para>
+
+ <para>
+ Consider the following example
+ <filename>PROVIDES</filename> statement from a recipe
+ file <filename>libav_0.8.11.bb</filename>:
+ <literallayout class='monospaced'>
+ PROVIDES += "libpostproc"
+ </literallayout>
+ The <filename>PROVIDES</filename> statement results in
+ the "libav" recipe also being known as "libpostproc".
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
+ <glossdef>
+ <para>
+ The network based
+ <link linkend='var-PR'><filename>PR</filename></link>
+ service host and port.
+ </para>
+
+ <para>
+ Following is an example of how the <filename>PRSERV_HOST</filename> variable is
+ set:
+ <literallayout class='monospaced'>
+ PRSERV_HOST = "localhost:0"
+ </literallayout>
+ You must set the variable if you want to automatically
+ start a local PR service.
+ You can set <filename>PRSERV_HOST</filename> to other
+ values to use a remote PR service.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-PV'><glossterm>PV</glossterm>
+ <glossdef>
+ <para>The version of the recipe.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+<!--
+ <glossdiv id='var-glossary-q'><title>Q</title>
+ </glossdiv>
+-->
+
+ <glossdiv id='var-glossary-r'><title>R</title>
+
+ <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
+ <glossdef>
+ <para>
+ Lists a package's runtime dependencies (i.e. other packages)
+ that must be installed in order for the built package to run
+ correctly.
+ If a package in this list cannot be found during the build,
+ you will get a build error.
+ </para>
+
+ <para>
+ Because the <filename>RDEPENDS</filename> variable applies
+ to packages being built, you should always use the variable
+ in a form with an attached package name.
+ For example, suppose you are building a development package
+ that depends on the <filename>perl</filename> package.
+ In this case, you would use the following
+ <filename>RDEPENDS</filename> statement:
+ <literallayout class='monospaced'>
+ RDEPENDS_${PN}-dev += "perl"
+ </literallayout>
+ In the example, the development package depends on
+ the <filename>perl</filename> package.
+ Thus, the <filename>RDEPENDS</filename> variable has the
+ <filename>${PN}-dev</filename> package name as part of the
+ variable.
+ </para>
+
+ <para>
+ BitBake supports specifying versioned dependencies.
+ Although the syntax varies depending on the packaging
+ format, BitBake hides these differences from you.
+ Here is the general syntax to specify versions with
+ the <filename>RDEPENDS</filename> variable:
+ <literallayout class='monospaced'>
+ RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
+ </literallayout>
+ For <filename>operator</filename>, you can specify the
+ following:
+ <literallayout class='monospaced'>
+ =
+ <
+ >
+ <=
+ >=
+ </literallayout>
+ For example, the following sets up a dependency on version
+ 1.2 or greater of the package <filename>foo</filename>:
+ <literallayout class='monospaced'>
+ RDEPENDS_${PN} = "foo (>= 1.2)"
+ </literallayout>
+ </para>
+
+ <para>
+ For information on build-time dependencies, see the
+ <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+ variable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
+ <glossdef>
+ <para>
+ A list of package name aliases that a package also provides.
+ These aliases are useful for satisfying runtime dependencies
+ of other packages both during the build and on the target
+ (as specified by
+ <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
+ </para>
+ <para>
+ As with all package-controlling variables, you must always
+ use the variable in conjunction with a package name override.
+ Here is an example:
+ <literallayout class='monospaced'>
+ RPROVIDES_${PN} = "widget-abi-2"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
+ <glossdef>
+ <para>
+ A list of packages that extends the usability of a package
+ being built.
+ The package being built does not depend on this list of
+ packages in order to successfully build, but needs them for
+ the extended usability.
+ To specify runtime dependencies for packages, see the
+ <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
+ variable.
+ </para>
+
+ <para>
+ BitBake supports specifying versioned recommends.
+ Although the syntax varies depending on the packaging
+ format, BitBake hides these differences from you.
+ Here is the general syntax to specify versions with
+ the <filename>RRECOMMENDS</filename> variable:
+ <literallayout class='monospaced'>
+ RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
+ </literallayout>
+ For <filename>operator</filename>, you can specify the
+ following:
+ <literallayout class='monospaced'>
+ =
+ <
+ >
+ <=
+ >=
+ </literallayout>
+ For example, the following sets up a recommend on version
+ 1.2 or greater of the package <filename>foo</filename>:
+ <literallayout class='monospaced'>
+ RRECOMMENDS_${PN} = "foo (>= 1.2)"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id='var-glossary-s'><title>S</title>
+
+ <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
+ <glossdef>
+ <para>The section in which packages should be categorized.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
+ <glossdef>
+ <para>
+ The list of source files - local or remote.
+ This variable tells BitBake which bits
+ to pull for the build and how to pull them.
+ For example, if the recipe or append file needs to
+ fetch a single tarball from the Internet, the recipe or
+ append file uses a <filename>SRC_URI</filename>
+ entry that specifies that tarball.
+ On the other hand, if the recipe or append file needs to
+ fetch a tarball and include a custom file, the recipe or
+ append file needs an <filename>SRC_URI</filename> variable
+ that specifies all those sources.</para>
+ <para>The following list explains the available URI protocols:
+ <itemizedlist>
+ <listitem><para><emphasis><filename>file://</filename> -</emphasis>
+ Fetches files, which are usually files shipped with
+ the metadata,
+ from the local machine.
+ The path is relative to the
+ <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
+ variable.</para></listitem>
+ <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
+ Bazaar revision control repository.</para></listitem>
+ <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
+ Git revision control repository.</para></listitem>
+ <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
+ an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
+ <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
+ a repo (Git) repository.</para></listitem>
+ <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
+ the Internet using HTTP.</para></listitem>
+ <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
+ from the Internet using HTTPS.</para></listitem>
+ <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
+ from the Internet using FTP.</para></listitem>
+ <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
+ a CVS revision control repository.</para></listitem>
+ <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
+ a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
+ <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
+ a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
+ <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
+ a secure shell.</para></listitem>
+ <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
+ a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
+ </itemizedlist>
+ </para>
+ <para>Here are some additional options worth mentioning:
+ <itemizedlist>
+ <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
+ whether or not to unpack the file if it is an archive.
+ The default action is to unpack the file.</para></listitem>
+ <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
+ (or extracts its contents) into the specified
+ subdirectory.
+ This option is useful for unusual tarballs or other archives that
+ do not have their files already in a subdirectory within the archive.
+ </para></listitem>
+ <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
+ name to be used for association with <filename>SRC_URI</filename> checksums
+ when you have more than one file specified in <filename>SRC_URI</filename>.
+ </para></listitem>
+ <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
+ the filename used when storing the downloaded file.</para></listitem>
+ </itemizedlist>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
+ <glossdef>
+ <para>
+ The date of the source code used to build the package.
+ This variable applies only if the source was fetched from a Source Code Manager (SCM).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
+ <glossdef>
+ <para>
+ The revision of the source code used to build the package.
+ This variable applies only when using Subversion, Git, Mercurial and Bazaar.
+ If you want to build a fixed revision and you want
+ to avoid performing a query on the remote repository every time
+ BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
+ full revision identifier and not just a tag.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-SRCREV_FORMAT'><glossterm>SRCREV_FORMAT</glossterm>
+ <glossdef>
+ <para>
+ Helps construct valid
+ <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
+ values when multiple source controlled URLs are used in
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
+ </para>
+
+ <para>
+ The system needs help constructing these values under these
+ circumstances.
+ Each component in the <filename>SRC_URI</filename>
+ is assigned a name and these are referenced
+ in the <filename>SRCREV_FORMAT</filename> variable.
+ Consider an example with URLs named "machine" and "meta".
+ In this case, <filename>SRCREV_FORMAT</filename> could look
+ like "machine_meta" and those names would have the SCM
+ versions substituted into each position.
+ Only one <filename>AUTOINC</filename> placeholder is added
+ and if needed.
+ And, this placeholder is placed at the start of the
+ returned string.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
+ <glossdef>
+ <para>
+ Specifies the base path used to create recipe stamp files.
+ The path to an actual stamp file is constructed by evaluating this
+ string and then appending additional information.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-STAMPCLEAN'><glossterm>STAMPCLEAN</glossterm>
+ <glossdef>
+ <para>
+ Specifies the base path used to create recipe stamp files.
+ Unlike the
+ <link linkend='var-STAMP'><filename>STAMP</filename></link>
+ variable, <filename>STAMPCLEAN</filename> can contain
+ wildcards to match the range of files a clean operation
+ should remove.
+ BitBake uses a clean operation to remove any other stamps
+ it should be removing when creating a new stamp.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
+ <glossdef>
+ <para>
+ A short summary for the recipe, which is 72 characters or less.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
+ <glossdef>
+ <para>
+ The directory in which files checked out of a Subversion
+ system are stored.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id='var-glossary-t'><title>T</title>
+
+ <glossentry id='var-T'><glossterm>T</glossterm>
+ <glossdef>
+ <para>Points to a directory were BitBake places
+ temporary files, which consist mostly of task logs and
+ scripts, when building a particular recipe.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
+ <glossdef>
+ <para>
+ Points to the build directory.
+ BitBake automatically sets this variable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+<!--
+ <glossdiv id='var-glossary-u'><title>U</title>
+ </glossdiv>
+
+ <glossdiv id='var-glossary-v'><title>V</title>
+ </glossdiv>
+
+ <glossdiv id='var-glossary-w'><title>W</title>
+ </glossdiv>
+
+ <glossdiv id='var-glossary-x'><title>X</title>
+ </glossdiv>
+
+ <glossdiv id='var-glossary-y'><title>Y</title>
+ </glossdiv>
+
+ <glossdiv id='var-glossary-z'><title>Z</title>
+ </glossdiv>
+-->
+
+
+</glossary>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-style.css b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-style.css
new file mode 100644
index 0000000..65da2a4
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-style.css
@@ -0,0 +1,984 @@
+/*
+ Generic XHTML / DocBook XHTML CSS Stylesheet.
+
+ Browser wrangling and typographic design by
+ Oyvind Kolas / pippin@gimp.org
+
+ Customised for Poky by
+ Matthew Allum / mallum@o-hand.com
+
+ Thanks to:
+ Liam R. E. Quin
+ William Skaggs
+ Jakub Steiner
+
+ Structure
+ ---------
+
+ The stylesheet is divided into the following sections:
+
+ Positioning
+ Margins, paddings, width, font-size, clearing.
+ Decorations
+ Borders, style
+ Colors
+ Colors
+ Graphics
+ Graphical backgrounds
+ Nasty IE tweaks
+ Workarounds needed to make it work in internet explorer,
+ currently makes the stylesheet non validating, but up until
+ this point it is validating.
+ Mozilla extensions
+ Transparency for footer
+ Rounded corners on boxes
+
+*/
+
+
+ /*************** /
+ / Positioning /
+/ ***************/
+
+body {
+ font-family: Verdana, Sans, sans-serif;
+
+ min-width: 640px;
+ width: 80%;
+ margin: 0em auto;
+ padding: 2em 5em 5em 5em;
+ color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+ font-family: Arial, Sans;
+ color: #00557D;
+ clear: both;
+}
+
+h1 {
+ font-size: 2em;
+ text-align: left;
+ padding: 0em 0em 0em 0em;
+ margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+ margin: 0.10em 0em 3.0em 0em;
+ padding: 0em 0em 0em 0em;
+ font-size: 1.8em;
+ padding-left: 20%;
+ font-weight: normal;
+ font-style: italic;
+}
+
+h2 {
+ margin: 2em 0em 0.66em 0em;
+ padding: 0.5em 0em 0em 0em;
+ font-size: 1.5em;
+ font-weight: bold;
+}
+
+h3.subtitle {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+ font-size: 142.14%;
+ text-align: right;
+}
+
+h3 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 140%;
+ font-weight: bold;
+}
+
+h4 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 120%;
+ font-weight: bold;
+}
+
+h5 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 110%;
+ font-weight: bold;
+}
+
+h6 {
+ margin: 1em 0em 0em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 110%;
+ font-weight: bold;
+}
+
+.authorgroup {
+ background-color: transparent;
+ background-repeat: no-repeat;
+ padding-top: 256px;
+ background-image: url("figures/bitbake-title.png");
+ background-position: left top;
+ margin-top: -256px;
+ padding-right: 50px;
+ margin-left: 0px;
+ text-align: right;
+ width: 740px;
+}
+
+h3.author {
+ margin: 0em 0me 0em 0em;
+ padding: 0em 0em 0em 0em;
+ font-weight: normal;
+ font-size: 100%;
+ color: #333;
+ clear: both;
+}
+
+.author tt.email {
+ font-size: 66%;
+}
+
+.titlepage hr {
+ width: 0em;
+ clear: both;
+}
+
+.revhistory {
+ padding-top: 2em;
+ clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+ padding: 1.33em 0em 2.5em 0em;
+ color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+ padding: 0em 0em 0em 0em;
+ padding: 0em 0em 0.3em;
+ margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+ font-size: 100.0%;
+ font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+ margin: 0em 0em 0.5em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+ margin: 0em 0em 0em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+ margin: 0em 0em 0em 2.6em;
+ padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+ font-weight: normal;
+ width: 20em;
+ text-align: right;
+}
+
+.variablelist dl dt {
+ margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+ margin-top: -1em;
+ margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+ margin-top: 0em;
+ margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+ padding: 0em 0em 0em 0em;
+ margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+ margin-top: 0em;
+ margin-bottom: 1em;
+}
+
+div p.copyright {
+ text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+ margin-bottom: 0em;
+}
+
+p {
+ line-height: 1.5em;
+ margin-top: 0em;
+
+}
+
+dl {
+ padding-top: 0em;
+}
+
+hr {
+ border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+ text-align: center;
+}
+
+img {
+ border: none;
+}
+
+ul {
+ padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+ padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+ text-align: left;
+}
+
+table {
+ width :100%;
+}
+
+th {
+ padding: 0.25em;
+ text-align: left;
+ font-weight: normal;
+ vertical-align: top;
+}
+
+td {
+ padding: 0.25em;
+ vertical-align: top;
+}
+
+p a[id] {
+ margin: 0px;
+ padding: 0px;
+ display: inline;
+ background-image: none;
+}
+
+a {
+ text-decoration: underline;
+ color: #444;
+}
+
+pre {
+ overflow: auto;
+}
+
+a:hover {
+ text-decoration: underline;
+ /*font-weight: bold;*/
+}
+
+/* This style defines how the permalink character
+ appears by itself and when hovered over with
+ the mouse. */
+
+[alt='Permalink'] { color: #eee; }
+[alt='Permalink']:hover { color: black; }
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+ margin: 1em 0em;
+ padding: 1em;
+ page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+ padding-top: 0em;
+ margin-top: 0em;
+ font-size: 100%;
+ font-weight: normal;
+}
+
+.mediaobject .caption,
+.mediaobject .caption p {
+ text-align: center;
+ font-size: 80%;
+ padding-top: 0.5em;
+ padding-bottom: 0.5em;
+}
+
+.epigraph {
+ padding-left: 55%;
+ margin-bottom: 1em;
+}
+
+.epigraph p {
+ text-align: left;
+}
+
+.epigraph .quote {
+ font-style: italic;
+}
+.epigraph .attribution {
+ font-style: normal;
+ text-align: right;
+}
+
+span.application {
+ font-style: italic;
+}
+
+.programlisting {
+ font-family: monospace;
+ font-size: 80%;
+ white-space: pre;
+ margin: 1.33em 0em;
+ padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+ margin-top: 1em;
+ margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+ border: none;
+ width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ padding: 0.8em 0.0em 0.0em 0.0em;
+ margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+ padding-right: 1em;
+ text-align: left;
+}
+
+.acronym {
+ text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+ padding: 0.09em 0.3em;
+ margin: 0em;
+}
+
+.itemizedlist li {
+ clear: none;
+}
+
+.filename {
+ font-size: medium;
+ font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+ position: absolute;
+ left: 0em;
+ top: 0em;
+ width: 100%;
+ background-color: #cdf;
+ width: 100%;
+}
+
+div.navfooter, div.footing{
+ position: fixed;
+ left: 0em;
+ bottom: 0em;
+ background-color: #eee;
+ width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+ font-size: 66%;
+}
+
+div.navheader table th {
+ /*font-family: Georgia, Times, serif;*/
+ /*font-size: x-large;*/
+ font-size: 80%;
+}
+
+div.navheader table {
+ border-left: 0em;
+ border-right: 0em;
+ border-top: 0em;
+ width: 100%;
+}
+
+div.navfooter table {
+ border-left: 0em;
+ border-right: 0em;
+ border-bottom: 0em;
+ width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+ color: #777;
+ text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+ color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+ color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+ text-decoration: underline;
+ background-color: transparent;
+ color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+ display: none;
+}
+
+
+.qandaset tr.question td p {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+}
+.answer td {
+ padding-bottom: 1.5em;
+}
+
+.emphasis {
+ font-weight: bold;
+}
+
+
+ /************* /
+ / decorations /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+ border: none;
+}
+
+/*
+h1 {
+ border: none;
+}
+
+h2 {
+ border-top: solid 0.2em;
+ border-bottom: solid 0.06em;
+}
+
+h3 {
+ border-top: 0em;
+ border-bottom: solid 0.06em;
+}
+
+h4 {
+ border: 0em;
+ border-bottom: solid 0.06em;
+}
+
+h5 {
+ border: 0em;
+}
+*/
+
+.programlisting {
+ border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+ border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+ border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ border-bottom: 1px solid;
+}
+
+.question td {
+ border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+ border: 1px solid;
+}
+
+
+div.navheader, div.heading{
+ border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+ border-top: 1px solid;
+}
+
+ /********* /
+ / colors /
+/ *********/
+
+body {
+ color: #333;
+ background: white;
+}
+
+a {
+ background: transparent;
+}
+
+a:hover {
+ background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+ background-color: transparent;
+}
+
+hr {
+ border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+ border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ border-bottom-color: #fff;
+}
+
+
+.warning {
+ background-color: #f0f0f2;
+}
+
+.caution {
+ background-color: #f0f0f2;
+}
+
+.tip {
+ background-color: #f0f0f2;
+}
+
+.note {
+ background-color: #f0f0f2;
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+ color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+ border-color: #aaa;
+}
+
+pre.programlisting {
+ color: black;
+ background-color: #fff;
+ border-color: #aaa;
+ border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+ background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+ background-color: #eee;
+ border-color: #999;
+}
+
+
+div.navheader {
+ border-color: black;
+}
+
+
+div.navfooter {
+ border-color: black;
+}
+
+
+ /*********** /
+ / graphics /
+/ ***********/
+
+/*
+body {
+ background-image: url("images/body_bg.jpg");
+ background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+ background-image: url("images/note_bg.jpg");
+ background-attachment: fixed;
+}
+
+.warning,
+.caution {
+ background-image: url("images/warning_bg.jpg");
+ background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+ background-image: url("images/figure_bg.jpg");
+ background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+ background-image: url("figures/white-on-black.png");
+ background-position: center;
+ background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title,
+div.colophon .title,
+div.chapter .titlepage .title,
+div.article .titlepage .title
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+ background: none;
+}
+
+
+h1.title {
+ background-color: transparent;
+ background-repeat: no-repeat;
+ height: 256px;
+ text-indent: -9000px;
+ overflow:hidden;
+}
+
+h2.subtitle {
+ background-color: transparent;
+ text-indent: -9000px;
+ overflow:hidden;
+ width: 0px;
+ display: none;
+}
+
+ /*************************************** /
+ / pippin.gimp.org specific alterations /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+ color: #777;
+ font-size: 80%;
+ padding: 0;
+ margin: 0;
+ text-align: left;
+ position: absolute;
+ top: 0px;
+ left: 0px;
+ width: 100%;
+ height: 50px;
+ background: url('/gfx/heading_bg.png') transparent;
+ background-repeat: repeat-x;
+ background-attachment: fixed;
+ border: none;
+}
+
+div.heading a {
+ color: #444;
+}
+
+div.footing, div.navfooter {
+ border: none;
+ color: #ddd;
+ font-size: 80%;
+ text-align:right;
+
+ width: 100%;
+ padding-top: 10px;
+ position: absolute;
+ bottom: 0px;
+ left: 0px;
+
+ background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+ /****************** /
+ / nasty ie tweaks /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+ width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+ width:expression(document.body.clientWidth + "px");
+ margin-left:expression("-5em");
+}
+body {
+ padding:expression("4em 5em 0em 5em");
+}
+*/
+
+ /**************************************** /
+ / mozilla vendor specific css extensions /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+ -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+ -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+ -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+ display: none;
+}
+
+
+hr {
+ display: none;
+}
+
+table {
+ border: 0em;
+}
+
+ .photo {
+ float: right;
+ margin-left: 1.5em;
+ margin-bottom: 1.5em;
+ margin-top: 0em;
+ max-width: 17em;
+ border: 1px solid gray;
+ padding: 3px;
+ background: white;
+}
+ .seperator {
+ padding-top: 2em;
+ clear: both;
+ }
+
+ #validators {
+ margin-top: 5em;
+ text-align: right;
+ color: #777;
+ }
+ @media print {
+ body {
+ font-size: 8pt;
+ }
+ .noprint {
+ display: none;
+ }
+ }
+
+
+.tip,
+.note {
+ background: #f0f0f2;
+ color: #333;
+ padding: 20px;
+ margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+ padding: 0em;
+ margin: 0em;
+ font-size: 2em;
+ font-weight: bold;
+ color: #333;
+}
+
+.tip a,
+.note a {
+ color: #333;
+ text-decoration: underline;
+}
+
+.footnote {
+ font-size: small;
+ color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+ font-size:large;
+ color: #00557D;
+}
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml
new file mode 100644
index 0000000..7fff933
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml
@@ -0,0 +1,88 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<book id='bitbake-user-manual' lang='en'
+ xmlns:xi="http://www.w3.org/2003/XInclude"
+ xmlns="http://docbook.org/ns/docbook"
+ >
+ <bookinfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref='figures/bitbake-title.png'
+ format='SVG'
+ align='left' scalefit='1' width='100%'/>
+ </imageobject>
+ </mediaobject>
+
+ <title>
+ BitBake User Manual
+ </title>
+
+ <authorgroup>
+ <author>
+ <firstname>Richard Purdie, Chris Larson, and </firstname> <surname>Phil Blundell</surname>
+ <affiliation>
+ <orgname>BitBake Community</orgname>
+ </affiliation>
+ <email>bitbake-devel@lists.openembedded.org</email>
+ </author>
+ </authorgroup>
+
+<!--
+# Add in some revision history if we want it here.
+ <revhistory>
+ <revision>
+ <revnumber>x.x</revnumber>
+ <date>dd month year</date>
+ <revremark>Some relevent comment</revremark>
+ </revision>
+ <revision>
+ <revnumber>x.x</revnumber>
+ <date>dd month year</date>
+ <revremark>Some relevent comment</revremark>
+ </revision>
+ <revision>
+ <revnumber>x.x</revnumber>
+ <date>dd month year</date>
+ <revremark>Some relevent comment</revremark>
+ </revision>
+ <revision>
+ <revnumber>x.x</revnumber>
+ <date>dd month year</date>
+ <revremark>Some relevent comment</revremark>
+ </revision>
+ </revhistory>
+-->
+
+ <copyright>
+ <year>2004-2015</year>
+ <holder>Richard Purdie</holder>
+ <holder>Chris Larson</holder>
+ <holder>and Phil Blundell</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>
+ This work is licensed under the Creative Commons Attribution License.
+ To view a copy of this license, visit
+ <ulink url="http://creativecommons.org/licenses/by/2.5/">http://creativecommons.org/licenses/by/2.5/</ulink>
+ or send a letter to Creative Commons, 444 Castro Street,
+ Suite 900, Mountain View, California 94041, USA.
+ </para>
+ </legalnotice>
+ </bookinfo>
+
+ <xi:include href="bitbake-user-manual-intro.xml"/>
+
+ <xi:include href="bitbake-user-manual-execution.xml"/>
+
+ <xi:include href="bitbake-user-manual-metadata.xml"/>
+
+ <xi:include href="bitbake-user-manual-fetching.xml"/>
+
+ <xi:include href="bitbake-user-manual-ref-variables.xml"/>
+
+ <xi:include href="bitbake-user-manual-hello.xml"/>
+
+</book>
diff --git a/bitbake/doc/bitbake-user-manual/figures/bitbake-title.png b/bitbake/doc/bitbake-user-manual/figures/bitbake-title.png
new file mode 100644
index 0000000..cb29015
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/figures/bitbake-title.png
Binary files differ
diff --git a/bitbake/doc/bitbake-user-manual/html.css b/bitbake/doc/bitbake-user-manual/html.css
new file mode 100644
index 0000000..6eedfd3
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/html.css
@@ -0,0 +1,281 @@
+/* Feuille de style DocBook du projet Traduc.org */
+/* DocBook CSS stylesheet of the Traduc.org project */
+
+/* (c) Jean-Philippe Guérard - 14 août 2004 */
+/* (c) Jean-Philippe Guérard - 14 August 2004 */
+
+/* Cette feuille de style est libre, vous pouvez la */
+/* redistribuer et la modifier selon les termes de la Licence */
+/* Art Libre. Vous trouverez un exemplaire de cette Licence sur */
+/* http://tigreraye.org/Petit-guide-du-traducteur.html#licence-art-libre */
+
+/* This work of art is free, you can redistribute it and/or */
+/* modify it according to terms of the Free Art license. You */
+/* will find a specimen of this license on the Copyleft */
+/* Attitude web site: http://artlibre.org as well as on other */
+/* sites. */
+/* Please note that the French version of this licence as shown */
+/* on http://tigreraye.org/Petit-guide-du-traducteur.html#licence-art-libre */
+/* is only official licence of this document. The English */
+/* is only provided to help you understand this licence. */
+
+/* La dernière version de cette feuille de style est toujours */
+/* disponible sur : http://tigreraye.org/style.css */
+/* Elle est également disponible sur : */
+/* http://www.traduc.org/docs/HOWTO/lecture/style.css */
+
+/* The latest version of this stylesheet is available from: */
+/* http://tigreraye.org/style.css */
+/* It is also available on: */
+/* http://www.traduc.org/docs/HOWTO/lecture/style.css */
+
+/* N'hésitez pas à envoyer vos commentaires et corrections à */
+/* Jean-Philippe Guérard <jean-philippe.guerard@tigreraye.org> */
+
+/* Please send feedback and bug reports to */
+/* Jean-Philippe Guérard <jean-philippe.guerard@tigreraye.org> */
+
+/* $Id: style.css,v 1.14 2004/09/10 20:12:09 fevrier Exp fevrier $ */
+
+/* Présentation générale du document */
+/* Overall document presentation */
+
+body {
+ /*
+ font-family: Apolline, "URW Palladio L", Garamond, jGaramond,
+ "Bitstream Cyberbit", "Palatino Linotype", serif;
+ */
+ margin: 7%;
+ background-color: white;
+}
+
+/* Taille du texte */
+/* Text size */
+
+* { font-size: 100%; }
+
+/* Gestion des textes mis en relief imbriqués */
+/* Embedded emphasis */
+
+em { font-style: italic; }
+em em { font-style: normal; }
+em em em { font-style: italic; }
+
+/* Titres */
+/* Titles */
+
+h1 { font-size: 200%; font-weight: 900; }
+h2 { font-size: 160%; font-weight: 900; }
+h3 { font-size: 130%; font-weight: bold; }
+h4 { font-size: 115%; font-weight: bold; }
+h5 { font-size: 108%; font-weight: bold; }
+h6 { font-weight: bold; }
+
+/* Nom de famille en petites majuscules (uniquement en français) */
+/* Last names in small caps (for French only) */
+
+*[class~="surname"]:lang(fr) { font-variant: small-caps; }
+
+/* Blocs de citation */
+/* Quotation blocs */
+
+div[class~="blockquote"] {
+ border: solid 2px #AAA;
+ padding: 5px;
+ margin: 5px;
+}
+
+div[class~="blockquote"] > table {
+ border: none;
+}
+
+/* Blocs litéraux : fond gris clair */
+/* Literal blocs: light gray background */
+
+*[class~="literallayout"] {
+ background: #f0f0f0;
+ padding: 5px;
+ margin: 5px;
+}
+
+/* Programmes et captures texte : fond bleu clair */
+/* Listing and text screen snapshots: light blue background */
+
+*[class~="programlisting"], *[class~="screen"] {
+ background: #f0f0ff;
+ padding: 5px;
+ margin: 5px;
+}
+
+/* Les textes à remplacer sont surlignés en vert pâle */
+/* Replaceable text in highlighted in pale green */
+
+*[class~="replaceable"] {
+ background-color: #98fb98;
+ font-style: normal; }
+
+/* Tables : fonds gris clair & bords simples */
+/* Tables: light gray background and solid borders */
+
+*[class~="table"] *[class~="title"] { width:100%; border: 0px; }
+
+table {
+ border: 1px solid #aaa;
+ border-collapse: collapse;
+ padding: 2px;
+ margin: 5px;
+}
+
+/* Listes simples en style table */
+/* Simples lists in table presentation */
+
+table[class~="simplelist"] {
+ background-color: #F0F0F0;
+ margin: 5px;
+ border: solid 1px #AAA;
+}
+
+table[class~="simplelist"] td {
+ border: solid 1px #AAA;
+}
+
+/* Les tables */
+/* Tables */
+
+*[class~="table"] table {
+ background-color: #F0F0F0;
+ border: solid 1px #AAA;
+}
+*[class~="informaltable"] table { background-color: #F0F0F0; }
+
+th,td {
+ vertical-align: baseline;
+ text-align: left;
+ padding: 0.1em 0.3em;
+ empty-cells: show;
+}
+
+/* Alignement des colonnes */
+/* Colunms alignment */
+
+td[align=center] , th[align=center] { text-align: center; }
+td[align=right] , th[align=right] { text-align: right; }
+td[align=left] , th[align=left] { text-align: left; }
+td[align=justify] , th[align=justify] { text-align: justify; }
+
+/* Pas de marge autour des images */
+/* No inside margins for images */
+
+img { border: 0; }
+
+/* Les liens ne sont pas soulignés */
+/* No underlines for links */
+
+:link , :visited , :active { text-decoration: none; }
+
+/* Prudence : cadre jaune et fond jaune clair */
+/* Caution: yellow border and light yellow background */
+
+*[class~="caution"] {
+ border: solid 2px yellow;
+ background-color: #ffffe0;
+ padding: 1em 6px 1em ;
+ margin: 5px;
+}
+
+*[class~="caution"] th {
+ vertical-align: middle
+}
+
+*[class~="caution"] table {
+ background-color: #ffffe0;
+ border: none;
+}
+
+/* Note importante : cadre jaune et fond jaune clair */
+/* Important: yellow border and light yellow background */
+
+*[class~="important"] {
+ border: solid 2px yellow;
+ background-color: #ffffe0;
+ padding: 1em 6px 1em;
+ margin: 5px;
+}
+
+*[class~="important"] th {
+ vertical-align: middle
+}
+
+*[class~="important"] table {
+ background-color: #ffffe0;
+ border: none;
+}
+
+/* Mise en évidence : texte légèrement plus grand */
+/* Highlights: slightly larger texts */
+
+*[class~="highlights"] {
+ font-size: 110%;
+}
+
+/* Note : cadre bleu et fond bleu clair */
+/* Notes: blue border and light blue background */
+
+*[class~="note"] {
+ border: solid 2px #7099C5;
+ background-color: #f0f0ff;
+ padding: 1em 6px 1em ;
+ margin: 5px;
+}
+
+*[class~="note"] th {
+ vertical-align: middle
+}
+
+*[class~="note"] table {
+ background-color: #f0f0ff;
+ border: none;
+}
+
+/* Astuce : cadre vert et fond vert clair */
+/* Tip: green border and light green background */
+
+*[class~="tip"] {
+ border: solid 2px #00ff00;
+ background-color: #f0ffff;
+ padding: 1em 6px 1em ;
+ margin: 5px;
+}
+
+*[class~="tip"] th {
+ vertical-align: middle;
+}
+
+*[class~="tip"] table {
+ background-color: #f0ffff;
+ border: none;
+}
+
+/* Avertissement : cadre rouge et fond rouge clair */
+/* Warning: red border and light red background */
+
+*[class~="warning"] {
+ border: solid 2px #ff0000;
+ background-color: #fff0f0;
+ padding: 1em 6px 1em ;
+ margin: 5px;
+}
+
+*[class~="warning"] th {
+ vertical-align: middle;
+}
+
+
+*[class~="warning"] table {
+ background-color: #fff0f0;
+ border: none;
+}
+
+/* Fin */
+/* The End */
+
