Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml
new file mode 100644
index 0000000..995c2fa
--- /dev/null
+++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml
@@ -0,0 +1,891 @@
+<!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>How to assemble the generated artifacts into
+ one or more installable packages</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 <firstterm>recipes</firstterm>.
+ <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, distribution configuration,
+ possible compiler tuning, general common
+ configuration, and user configuration.
+ 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
+ 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 <firstterm>Board Support Package</firstterm> (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
+ "<filename>%</filename>" 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.</filename><replaceable>x</replaceable><filename>.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>
+ <note><title>Important</title>
+ The use of the "<filename>%</filename>" character
+ is limited in that it only works directly in front of the
+ <filename>.bbappend</filename> portion of the append file's
+ name.
+ You cannot use the wildcard character in any other
+ location of the name.
+ </note>
+ 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.
+ 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 recipe:do_task ...]
+
+ 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.
+ -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 Enable tracing of shell tasks (with 'set -x'). Also
+ print bb.note(...) messages to stdout (in addition to
+ writing them to ${T}/log.do_<task>).
+ -D, --debug Increase the debug level. You can specify this more
+ than once. -D sets the debug level to 1, where only
+ bb.debug(1, ...) messages are printed to stdout; -DD
+ sets the debug level to 2, where both bb.debug(1, ...)
+ and bb.debug(2, ...) messages are printed; etc.
+ Without -D, no debug messages are printed. Note that
+ -D only affects output to stdout. All debug messages
+ are written to ${T}/log.do_taskname, regardless of the
+ debug level.
+ -q, --quiet Output less log message data to the terminal. 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 (knotty, ncurses or taskexp
+ - default knotty).
+ --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 xmlrpc server to bind
+ to.
+ -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
+ Set timeout to unload bitbake server due to
+ inactivity, set to -1 means no unload, default:
+ Environment variable BB_SERVER_TIMEOUT.
+ --no-setscene Do not run any setscene tasks. sstate will be ignored
+ and everything needed, built.
+ --setscene-only Only run setscene tasks, don't run any real tasks.
+ --remote-server=REMOTE_SERVER
+ Connect to the specified server.
+ -m, --kill-server Terminate any running bitbake server.
+ --observe-only Connect to a server as an observing-only client.
+ --status-only Check the status of the remote bitbake server.
+ -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
+ Writes the event log of the build to a bitbake event
+ json file. Use '' (empty string) to assign the name
+ automatically.
+ --runall=RUNALL Run the specified task for any recipe in the taskgraph
+ of the specified target (even if it wouldn't otherwise
+ have run).
+ --runonly=RUNONLY Run only the specified task within the taskgraph of
+ the specified targets (and any task dependencies those
+ tasks may have).
+ </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='executing-a-list-of-task-and-recipe-combinations'>
+ <title>Executing a List of Task and Recipe Combinations</title>
+
+ <para>
+ The BitBake command line supports specifying different
+ tasks for individual targets when you specify multiple
+ targets.
+ For example, suppose you had two targets (or recipes)
+ <filename>myfirstrecipe</filename> and
+ <filename>mysecondrecipe</filename> and you needed
+ BitBake to run <filename>taskA</filename> for the first
+ recipe and <filename>taskB</filename> for the second
+ recipe:
+ <literallayout class='monospaced'>
+ $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
+ </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 two files
+ to the current working directory:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>task-depends.dot</filename>:</emphasis>
+ Shows dependencies between tasks.
+ These dependencies match BitBake's internal task execution list.
+ </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 id='executing-a-multiple-configuration-build'>
+ <title>Executing a Multiple Configuration Build</title>
+
+ <para>
+ BitBake is able to build multiple images or packages
+ using a single command where the different targets
+ require different configurations (multiple configuration
+ builds).
+ Each target, in this scenario, is referred to as a
+ "multiconfig".
+ </para>
+
+ <para>
+ To accomplish a multiple configuration build, you must
+ define each target's configuration separately using
+ a parallel configuration file in the build directory.
+ The location for these multiconfig configuration files
+ is specific.
+ They must reside in the current build directory in
+ a sub-directory of <filename>conf</filename> named
+ <filename>multiconfig</filename>.
+ Following is an example for two separate targets:
+ <imagedata fileref="figures/bb_multiconfig_files.png" align="center" width="4in" depth="3in" />
+ </para>
+
+ <para>
+ The reason for this required file hierarchy
+ is because the <filename>BBPATH</filename> variable
+ is not constructed until the layers are parsed.
+ Consequently, using the configuration file as a
+ pre-configuration file is not possible unless it is
+ located in the current working directory.
+ </para>
+
+ <para>
+ Minimally, each configuration file must define the
+ machine and the temporary directory BitBake uses
+ for the build.
+ Suggested practice dictates that you do not
+ overlap the temporary directories used during the
+ builds.
+ </para>
+
+ <para>
+ Aside from separate configuration files for each
+ target, you must also enable BitBake to perform multiple
+ configuration builds.
+ Enabling is accomplished by setting the
+ <link linkend='var-bb-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></link>
+ variable in the <filename>local.conf</filename>
+ configuration file.
+ As an example, suppose you had configuration files
+ for <filename>target1</filename> and
+ <filename>target2</filename> defined in the build
+ directory.
+ The following statement in the
+ <filename>local.conf</filename> file both enables
+ BitBake to perform multiple configuration builds and
+ specifies the two extra multiconfigs:
+ <literallayout class='monospaced'>
+ BBMULTICONFIG = "target1 target2"
+ </literallayout>
+ </para>
+
+ <para>
+ Once the target configuration files are in place and
+ BitBake has been enabled to perform multiple configuration
+ builds, use the following command form to start the
+ builds:
+ <literallayout class='monospaced'>
+ $ bitbake [mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
+ </literallayout>
+ Here is an example for two extra multiconfigs:
+ <filename>target1</filename> and
+ <filename>target2</filename>:
+ <literallayout class='monospaced'>
+ $ bitbake mc::<replaceable>target</replaceable> mc:target1:<replaceable>target</replaceable> mc:target2:<replaceable>target</replaceable>
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='bb-enabling-multiple-configuration-build-dependencies'>
+ <title>Enabling Multiple Configuration Build Dependencies</title>
+
+ <para>
+ Sometimes dependencies can exist between targets
+ (multiconfigs) in a multiple configuration build.
+ For example, suppose that in order to build an image
+ for a particular architecture, the root filesystem of
+ another build for a different architecture needs to
+ exist.
+ In other words, the image for the first multiconfig depends
+ on the root filesystem of the second multiconfig.
+ This dependency is essentially that the task in the recipe
+ that builds one multiconfig is dependent on the
+ completion of the task in the recipe that builds
+ another multiconfig.
+ </para>
+
+ <para>
+ To enable dependencies in a multiple configuration
+ build, you must declare the dependencies in the recipe
+ using the following statement form:
+ <literallayout class='monospaced'>
+ <replaceable>task_or_package</replaceable>[mcdepends] = "mc:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>"
+ </literallayout>
+ To better show how to use this statement, consider an
+ example with two multiconfigs: <filename>target1</filename>
+ and <filename>target2</filename>:
+ <literallayout class='monospaced'>
+ <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>rootfs_task</replaceable>"
+ </literallayout>
+ In this example, the
+ <replaceable>from_multiconfig</replaceable> is "target1" and
+ the <replaceable>to_multiconfig</replaceable> is "target2".
+ The task on which the image whose recipe contains
+ <replaceable>image_task</replaceable> depends on the
+ completion of the <replaceable>rootfs_task</replaceable>
+ used to build out <replaceable>image2</replaceable>, which
+ is associated with the "target2" multiconfig.
+ </para>
+
+ <para>
+ Once you set up this dependency, you can build the
+ "target1" multiconfig using a BitBake command as follows:
+ <literallayout class='monospaced'>
+ $ bitbake mc:target1:<replaceable>image1</replaceable>
+ </literallayout>
+ This command executes all the tasks needed to create
+ <replaceable>image1</replaceable> for the "target1"
+ multiconfig.
+ Because of the dependency, BitBake also executes through
+ the <replaceable>rootfs_task</replaceable> for the "target2"
+ multiconfig build.
+ </para>
+
+ <para>
+ Having a recipe depend on the root filesystem of another
+ build might not seem that useful.
+ Consider this change to the statement in the
+ <replaceable>image1</replaceable> recipe:
+ <literallayout class='monospaced'>
+ <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>image_task</replaceable>"
+ </literallayout>
+ In this case, BitBake must create
+ <replaceable>image2</replaceable> for the "target2"
+ build since the "target1" build depends on it.
+ </para>
+
+ <para>
+ Because "target1" and "target2" are enabled for multiple
+ configuration builds and have separate configuration
+ files, BitBake places the artifacts for each build in the
+ respective temporary build directories.
+ </para>
+ </section>
+ </section>
+ </section>
+</chapter>