347 lines
14 KiB
XML
347 lines
14 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<chapter>
|
|
<title>The BitBake command</title>
|
|
|
|
<section>
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
bitbake is the primary command in the system.
|
|
It facilitates executing tasks in a single .bb
|
|
file, or executing a given task on a set of multiple
|
|
.bb files, accounting for interdependencies
|
|
amongst them.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Usage and syntax</title>
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
<prompt>$ </prompt>bitbake --help
|
|
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, --dump-signatures
|
|
Don't execute, just dump out the signature
|
|
construction information.
|
|
-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-package 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.
|
|
--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>
|
|
<para>
|
|
|
|
<example>
|
|
|
|
<title>Executing a task against a single .bb</title>
|
|
|
|
<para>
|
|
Executing tasks for a single file is relatively simple.
|
|
You specify the file in question, and BitBake parses
|
|
it and executes the specified task (or <quote>build</quote> by default).
|
|
It obeys intertask dependencies when doing so.
|
|
</para>
|
|
|
|
<para><quote>clean</quote> task:</para>
|
|
<literallayout class='monospaced'>
|
|
$ bitbake -b foo.bb -c clean
|
|
</literallayout>
|
|
|
|
<para><quote>build</quote> task:</para>
|
|
<literallayout class='monospaced'>
|
|
$ bitbake -b foo_1.0.bb
|
|
</literallayout>
|
|
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Executing tasks against a set of .bb files</title>
|
|
<para>
|
|
There are a number of additional complexities introduced
|
|
when one wants to manage multiple .bb
|
|
files.
|
|
Clearly there needs to be a way to tell BitBake what
|
|
files are available, and of those, which we
|
|
want to execute at this time
|
|
There also needs to be a way for each .bb
|
|
to express its dependencies, both for build time and
|
|
runtime.
|
|
There must be a way for the user to express their preferences
|
|
when multiple .bb's provide the same functionality, or when
|
|
there are multiple versions of a .bb.
|
|
</para>
|
|
|
|
<para>
|
|
The next section, Metadata, outlines how to specify such things.
|
|
</para>
|
|
|
|
<para>
|
|
Note that the bitbake command, when not using
|
|
--buildfile, accepts a <varname>PROVIDER</varname>, not a filename or
|
|
anything else.
|
|
By default, a .bb generally PROVIDES its
|
|
packagename, packagename-version, and packagename-version-revision.
|
|
<literallayout class='monospaced'>
|
|
$ bitbake foo
|
|
|
|
$ bitbake foo-1.0
|
|
|
|
$ bitbake foo-1.0-r0
|
|
|
|
$ bitbake -c clean foo
|
|
|
|
$ bitbake virtual/whatever
|
|
|
|
$ bitbake -c clean virtual/whatever
|
|
</literallayout>
|
|
</para>
|
|
</example>
|
|
<example>
|
|
<title>Generating dependency graphs</title>
|
|
<para>
|
|
BitBake is able to generate dependency graphs using
|
|
the dot syntax.
|
|
These graphs can be converted to images using the <application>dot</application>
|
|
application from
|
|
<ulink url="http://www.graphviz.org">Graphviz</ulink>.
|
|
Two files will be written into the current working directory,
|
|
<emphasis>depends.dot</emphasis> containing dependency information
|
|
at the package level and <emphasis>task-depends.dot</emphasis>
|
|
containing a breakdown of the dependencies at the task level.
|
|
To stop depending on common depends, one can use the <prompt>-I depend</prompt>
|
|
to omit these from the graph.
|
|
This can lead to more readable graphs.
|
|
This way, <varname>DEPENDS</varname> from inherited classes
|
|
such as base.bbclass can be removed from the
|
|
graph.
|
|
<literallayout class='monospaced'>
|
|
$ bitbake -g foo
|
|
|
|
$ bitbake -g -I virtual/whatever -I bloom foo
|
|
</literallayout>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Special variables</title>
|
|
|
|
<para>
|
|
Certain variables affect BitBake operation:
|
|
</para>
|
|
|
|
<section>
|
|
<title><varname>BB_NUMBER_THREADS</varname></title>
|
|
|
|
<para>
|
|
The number of threads BitBake should run at once (default: 1).
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Metadata</title>
|
|
<para>
|
|
As you may have seen in the usage information, or in the
|
|
information about .bb files, the
|
|
<varname>BBFILES</varname> variable is how the BitBake
|
|
tool locates its files.
|
|
This variable is a space separated list of files
|
|
that are available, and supports wildcards.
|
|
<example>
|
|
<title>Setting BBFILES</title>
|
|
|
|
<literallayout class='monospaced'>
|
|
BBFILES = "/path/to/bbfiles/*.bb"
|
|
</literallayout>
|
|
</example></para>
|
|
<para>
|
|
With regard to dependencies, it expects the
|
|
.bb to define a
|
|
<varname>DEPENDS</varname> variable, which contains a
|
|
space separated list of <quote>package names</quote>, which themselves
|
|
are the <varname>PN</varname> variable. The
|
|
<varname>PN</varname> variable is, in general,
|
|
set to a component of the .bb
|
|
filename by default.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Depending on another .bb</title>
|
|
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
a.bb:
|
|
|
|
PN = "package-a"
|
|
DEPENDS += "package-b"
|
|
|
|
b.bb:
|
|
|
|
PN = "package-b"
|
|
</literallayout>
|
|
</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Using PROVIDES</title>
|
|
|
|
<para>
|
|
This example shows the usage of the <varname>PROVIDES</varname> variable, which allows a given .bb to specify what functionality it provides.
|
|
<literallayout class='monospaced'>
|
|
package1.bb:
|
|
|
|
PROVIDES += "virtual/package"
|
|
|
|
package2.bb:
|
|
|
|
DEPENDS += "virtual/package"
|
|
|
|
package3.bb:
|
|
|
|
PROVIDES += "virtual/package"
|
|
</literallayout>
|
|
As you can see, we have two different
|
|
.bb's that provide the same functionality
|
|
(virtual/package).
|
|
Clearly, there needs to be a way for the person running
|
|
BitBake to control which of those providers
|
|
gets used.
|
|
There is, indeed, such a way.
|
|
</para>
|
|
<para>
|
|
The following would go into a .conf file, to select package1:
|
|
<literallayout class='monospaced'>
|
|
PREFERRED_PROVIDER_virtual/package = "package1"
|
|
</literallayout>
|
|
</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Specifying version preference</title>
|
|
|
|
<para>
|
|
When there are multiple <quote>versions</quote> of a given package,
|
|
BitBake defaults to selecting the most recent version,
|
|
unless otherwise specified.
|
|
If the .bb in question has a
|
|
<varname>DEFAULT_PREFERENCE</varname> set lower than
|
|
the other .bb's (default is 0), then it will not be
|
|
selected.
|
|
This allows the person or persons maintaining
|
|
the repository of .bb files to specify
|
|
their preference for the default selected version.
|
|
In addition, the user can specify their preferred version.
|
|
</para>
|
|
|
|
<para>
|
|
If the first .bb is named
|
|
<filename>a_1.1.bb</filename>, then the
|
|
<varname>PN</varname> variable will be set to
|
|
<quote>a</quote>, and the <varname>PV</varname> variable will be
|
|
set to 1.1.
|
|
</para>
|
|
|
|
<para>
|
|
If we then have an <filename>a_1.2.bb</filename>, BitBake
|
|
will choose 1.2 by default.
|
|
However, if we define the following variable in a
|
|
.conf that BitBake parses, we
|
|
can change that.
|
|
<literallayout class='monospaced'>
|
|
PREFERRED_VERSION_a = "1.1"
|
|
</literallayout>
|
|
|
|
</para>
|
|
</example>
|
|
<example>
|
|
|
|
<title>Using <quote>bbfile collections</quote></title>
|
|
|
|
<para>
|
|
bbfile collections exist to allow the user to
|
|
have multiple repositories of
|
|
bbfiles 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.
|
|
Usage:
|
|
<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>
|
|
</para>
|
|
</example>
|
|
</section>
|
|
</chapter>
|