368 lines
15 KiB
XML
368 lines
15 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 id='bitbake-command-introduction'>
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
Bitbake is the primary command in the system.
|
|
It facilitates executing tasks in a single <filename>.bb</filename>
|
|
file, or executing a given task on a set of multiple
|
|
<filename>.bb</filename> files, accounting for interdependencies
|
|
amongst them.
|
|
</para>
|
|
</section>
|
|
|
|
<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, --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>
|
|
</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 (or “build” by default).
|
|
BitBake obeys inter-task dependencies when doing
|
|
so.
|
|
</para>
|
|
|
|
<para>
|
|
The following command runs the clean task on the
|
|
<filename>foo_1.0.bb</filename> recipe file:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake -b foo.bb -c clean
|
|
</literallayout>
|
|
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>
|
|
</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 we
|
|
want to execute at this time.
|
|
There also needs to be a way for each <filename>.bb</filename>
|
|
to express its dependencies, both for build-time and
|
|
runtime.
|
|
There must be a way for the user to express their preferences
|
|
when multiple recipes provide the same functionality, or when
|
|
there are multiple versions of a <filename>.bb</filename> file.
|
|
</para>
|
|
|
|
<para>
|
|
The next section, Metadata, outlines how to specify such things.
|
|
</para>
|
|
|
|
<para>
|
|
The <filename>bitbake</filename> command, when not using
|
|
"--buildfile", accepts a PROVIDER, not a filename or
|
|
anything else.
|
|
By default, a <filename>.bb</filename> 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>
|
|
</section>
|
|
|
|
<section id='generating-dependency-graphs'>
|
|
<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 dot
|
|
application from
|
|
<ulink url='http://www.graphviz.org'>Graphviz</ulink>.
|
|
Two files will be written into the current working directory:
|
|
<filename>depends.dot</filename> containing dependency information
|
|
at the package level and <filename>task-depends.dot</filename>
|
|
containing a breakdown of the dependencies at the task level.
|
|
To stop depending on common depends, one can use the "-I" depend
|
|
option to omit these from the graph.
|
|
This can lead to more readable graphs.
|
|
This way, <filename>DEPENDS</filename> from inherited classes
|
|
such as <filename>base.bbclass</filename> can be removed from the
|
|
graph.
|
|
<literallayout class='monospaced'>
|
|
$ bitbake -g foo
|
|
|
|
$ bitbake -g -I virtual/whatever -I bloom foo
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='special-variables'>
|
|
<title>Special Variables</title>
|
|
|
|
<para>
|
|
Certain variables affect BitBake operation:
|
|
</para>
|
|
|
|
<section id='bb-number-threads'>
|
|
<title><filename>BB_NUMBER_THREADS</filename></title>
|
|
|
|
<para>
|
|
The number of threads BitBake should run at once (default: 1).
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='bitbake-command-metadata'>
|
|
<title>Metadata</title>
|
|
|
|
<para>
|
|
As you may have seen in the usage information, or in the
|
|
information about <filename>.bb</filename> files, the
|
|
<filename>BBFILES</filename> variable is how the BitBake
|
|
tool locates its files.
|
|
This variable is a space-separated list of files
|
|
that are available, and supports wildcards.
|
|
</para>
|
|
|
|
<section id='setting-bbfiles'>
|
|
<title>Setting <filename>BBFILES</filename></title>
|
|
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
BBFILES = "/path/to/bbfiles/*.bb"
|
|
</literallayout>
|
|
With regard to dependencies, it expects the
|
|
<filename>.bb</filename> to define a
|
|
<filename>DEPENDS</filename> variable, which contains a
|
|
space separated list of “package names”, which themselves
|
|
are the <filename>PN</filename> variable. The
|
|
<filename>PN</filename> variable is, in general,
|
|
set to a component of the <filename>.bb</filename>
|
|
filename by default.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='depending-on-another-recipe-file'>
|
|
<title>Depending on Another Recipe File</title>
|
|
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
a.bb:
|
|
|
|
PN = "package-a"
|
|
DEPENDS += "package-b"
|
|
|
|
b.bb:
|
|
|
|
PN = "package-b"
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='using-provides'>
|
|
<title>Using <filename>PROVIDES</filename></title>
|
|
|
|
<para>
|
|
This example shows the usage of the
|
|
<filename>PROVIDES</filename> variable, which allows a
|
|
given <filename>.bb</filename> 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
|
|
recipes 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 <filename>.conf</filename>
|
|
file, to select package1:
|
|
<literallayout class='monospaced'>
|
|
PREFERRED_PROVIDER_virtual/package = "package1"
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='specifying-version-preference'>
|
|
<title>Specifying Version Preference</title>
|
|
|
|
<para>
|
|
When there are multiple “versions” of a given package,
|
|
BitBake defaults to selecting the most recent
|
|
version, unless otherwise specified.
|
|
If the <filename>.bb</filename> in question has a
|
|
<filename>DEFAULT_PREFERENCE</filename> 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 <filename>.bb</filename> files to specify
|
|
their preference for the default selected version.
|
|
In addition, the user can specify their preferred version.
|
|
</para>
|
|
|
|
<para>
|
|
If the first <filename>.bb</filename> is named
|
|
<filename>a_1.1.bb</filename>, then the
|
|
<filename>PN</filename> variable will be set to
|
|
“a”, and the <filename>PV</filename> 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
|
|
<filename>.conf</filename> file that BitBake parses, we
|
|
can change that.
|
|
<literallayout class='monospaced'>
|
|
PREFERRED_VERSION_a = "1.1"
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='using-recipe-file-collections'>
|
|
<title>Using Recipe File Collections</title>
|
|
|
|
<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>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|