mirror of
https://git.yoctoproject.org/poky
synced 2026-04-18 03:32:13 +02:00
dev-manual, ref-manual: Consolidated debug info into dev-manual
Fixes [YOCTO #12370] Moved the debug information from the ref-manual to the dev-manual where other debug information exists. We now have a single area (section) that deals with various debugging techniques and tips. (From yocto-docs rev: 95394197fc04981bf7571e581ff8a0fd9c76223f) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
committed by
Richard Purdie
Richard Purdie
parent
09e9f81c34
commit
0d52f18d39
File diff suppressed because it is too large
Load Diff
@@ -1033,8 +1033,8 @@
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
|
||||
For information on how to view and interpret information in
|
||||
<filename>siginfo</filename> files, see the
|
||||
"<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
|
||||
section in the Yocto Project Reference Manual.
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
|
||||
section in the Yocto Project Development Tasks Manual.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
||||
@@ -2541,8 +2541,8 @@
|
||||
<para>
|
||||
For details on how to view information about a task's
|
||||
signature, see the
|
||||
"<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
|
||||
section in the Yocto Project Reference Manual.
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
|
||||
section in the Yocto Project Development Tasks Manual.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
||||
@@ -9286,8 +9286,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
|
||||
<filename>OVERRIDES</filename> in the output of the
|
||||
<filename>bitbake -e</filename> command.
|
||||
See the
|
||||
"<link linkend='usingpoky-debugging-viewing-variable-values'>Viewing Variable Values</link>"
|
||||
section for more information.
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
|
||||
section in the Yocto Project Development Tasks
|
||||
Manual for more information.
|
||||
</note>
|
||||
</para>
|
||||
</glossdef>
|
||||
@@ -10413,8 +10414,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
|
||||
For examples of how this data is used, see the
|
||||
"<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
|
||||
section in the Yocto Project Overview Manual and the
|
||||
"<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
|
||||
section elsewhere in this manual.
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
|
||||
section in the Yocto Project Development Tasks Manual.
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
|
||||
@@ -11,905 +11,6 @@
|
||||
documentation set provide more details on how to use the Yocto Project.
|
||||
</para>
|
||||
|
||||
<section id='usingpoky-debugging-tools-and-techniques'>
|
||||
<title>Debugging Tools and Techniques</title>
|
||||
|
||||
<para>
|
||||
The exact method for debugging build failures depends on the nature of
|
||||
the problem and on the system's area from which the bug originates.
|
||||
Standard debugging practices such as comparison against the last
|
||||
known working version with examination of the changes and the
|
||||
re-application of steps to identify the one causing the problem are
|
||||
valid for the Yocto Project just as they are for any other system.
|
||||
Even though it is impossible to detail every possible potential failure,
|
||||
this section provides some general tips to aid in debugging.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A useful feature for debugging is the error reporting tool.
|
||||
Configuring the Yocto Project to use this tool causes the
|
||||
OpenEmbedded build system to produce error reporting commands as
|
||||
part of the console output.
|
||||
You can enter the commands after the build completes
|
||||
to log error information
|
||||
into a common database, that can help you figure out what might be
|
||||
going wrong.
|
||||
For information on how to enable and use this feature, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>Using the Error Reporting Tool</ulink>"
|
||||
section in the Yocto Project Development Tasks Manual.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For discussions on debugging, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" section
|
||||
in the Yocto Project Development Tasks Manual
|
||||
and the
|
||||
"<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>"
|
||||
section in the Yocto Project Application Development and the
|
||||
Extensible Software Development Kit (eSDK) manual.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
The remainder of this section presents many examples of the
|
||||
<filename>bitbake</filename> command.
|
||||
You can learn about BitBake by reading the
|
||||
<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
|
||||
</note>
|
||||
|
||||
<section id='usingpoky-debugging-viewing-logs-from-failed-tasks'>
|
||||
<title>Viewing Logs from Failed Tasks</title>
|
||||
|
||||
<para>
|
||||
You can find the log for a task in the file
|
||||
<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>.
|
||||
For example, the log for the
|
||||
<link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
|
||||
task of the QEMU minimal image for the x86 machine
|
||||
(<filename>qemux86</filename>) might be in
|
||||
<filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
|
||||
To see the commands
|
||||
<link linkend='bitbake-term'>BitBake</link> ran
|
||||
to generate a log, look at the corresponding
|
||||
<filename>run.do_</filename><replaceable>taskname</replaceable>
|
||||
file in the same directory.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<filename>log.do_</filename><replaceable>taskname</replaceable> and
|
||||
<filename>run.do_</filename><replaceable>taskname</replaceable>
|
||||
are actually symbolic links to
|
||||
<filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>
|
||||
and
|
||||
<filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>,
|
||||
where <replaceable>pid</replaceable> is the PID the task had when
|
||||
it ran.
|
||||
The symlinks always point to the files corresponding to the most
|
||||
recent run.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-debugging-viewing-variable-values'>
|
||||
<title>Viewing Variable Values</title>
|
||||
<para>
|
||||
BitBake's <filename>-e</filename> option is used to display
|
||||
variable values after parsing.
|
||||
The following command displays the variable values after the
|
||||
configuration files (i.e. <filename>local.conf</filename>,
|
||||
<filename>bblayers.conf</filename>,
|
||||
<filename>bitbake.conf</filename> and so forth) have been
|
||||
parsed:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake -e
|
||||
</literallayout>
|
||||
The following command displays variable values after a specific
|
||||
recipe has been parsed.
|
||||
The variables include those from the configuration as well:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake -e recipename
|
||||
</literallayout>
|
||||
<note><para>
|
||||
Each recipe has its own private set of variables (datastore).
|
||||
Internally, after parsing the configuration, a copy of the
|
||||
resulting datastore is made prior to parsing each recipe.
|
||||
This copying implies that variables set in one recipe will
|
||||
not be visible to other recipes.</para>
|
||||
|
||||
<para>Likewise, each task within a recipe gets a private
|
||||
datastore based on the recipe datastore, which means that
|
||||
variables set within one task will not be visible to
|
||||
other tasks.</para>
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In the output of <filename>bitbake -e</filename>, each variable is
|
||||
preceded by a description of how the variable got its value,
|
||||
including temporary values that were later overriden.
|
||||
This description also includes variable flags (varflags) set on
|
||||
the variable.
|
||||
The output can be very helpful during debugging.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Variables that are exported to the environment are preceded by
|
||||
<filename>export</filename> in the output of
|
||||
<filename>bitbake -e</filename>.
|
||||
See the following example:
|
||||
<literallayout class='monospaced'>
|
||||
export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In addition to variable values, the output of the
|
||||
<filename>bitbake -e</filename> and
|
||||
<filename>bitbake -e</filename> <replaceable>recipe</replaceable>
|
||||
commands includes the following information:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
The output starts with a tree listing all configuration
|
||||
files and classes included globally, recursively listing
|
||||
the files they include or inherit in turn.
|
||||
Much of the behavior of the OpenEmbedded build system
|
||||
(including the behavior of the
|
||||
<link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>)
|
||||
is implemented in the
|
||||
<link linkend='ref-classes-base'><filename>base</filename></link>
|
||||
class and the classes it inherits, rather than being built
|
||||
into BitBake itself.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
After the variable values, all functions appear in the
|
||||
output.
|
||||
For shell functions, variables referenced within the
|
||||
function body are expanded.
|
||||
If a function has been modified using overrides or
|
||||
using override-style operators like
|
||||
<filename>_append</filename> and
|
||||
<filename>_prepend</filename>, then the final assembled
|
||||
function body appears in the output.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='viewing-package-information-with-oe-pkgdata-util'>
|
||||
<title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title>
|
||||
|
||||
<para>
|
||||
You can use the <filename>oe-pkgdata-util</filename> command-line
|
||||
utility to query
|
||||
<link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
|
||||
and display various package-related information.
|
||||
When you use the utility, you must use it to view information
|
||||
on packages that have already been built.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Following are a few of the available
|
||||
<filename>oe-pkgdata-util</filename> subcommands.
|
||||
<note>
|
||||
You can use the standard * and ? globbing wildcards as part of
|
||||
package names and paths.
|
||||
</note>
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
<filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>:
|
||||
Lists all packages that have been built, optionally
|
||||
limiting the match to packages that match
|
||||
<replaceable>pattern</replaceable>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>oe-pkgdata-util list-pkg-files </filename><replaceable>package</replaceable><filename> ...</filename>:
|
||||
Lists the files and directories contained in the given
|
||||
packages.
|
||||
<note>
|
||||
<para>
|
||||
A different way to view the contents of a package is
|
||||
to look at the
|
||||
<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/packages-split</filename>
|
||||
directory of the recipe that generates the
|
||||
package.
|
||||
This directory is created by the
|
||||
<link linkend='ref-tasks-package'><filename>do_package</filename></link>
|
||||
task and has one subdirectory for each package the
|
||||
recipe generates, which contains the files stored in
|
||||
that package.</para>
|
||||
<para>
|
||||
If you want to inspect the
|
||||
<filename>${WORKDIR}/packages-split</filename>
|
||||
directory, make sure that
|
||||
<link linkend='ref-classes-rm-work'><filename>rm_work</filename></link>
|
||||
is not enabled when you build the recipe.
|
||||
</para>
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>oe-pkgdata-util find-path </filename><replaceable>path</replaceable><filename> ...</filename>:
|
||||
Lists the names of the packages that contain the given
|
||||
paths.
|
||||
For example, the following tells us that
|
||||
<filename>/usr/share/man/man1/make.1</filename>
|
||||
is contained in the <filename>make-doc</filename>
|
||||
package:
|
||||
<literallayout class='monospaced'>
|
||||
$ oe-pkgdata-util find-path /usr/share/man/man1/make.1
|
||||
make-doc: /usr/share/man/man1/make.1
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>oe-pkgdata-util lookup-recipe </filename><replaceable>package</replaceable><filename> ...</filename>:
|
||||
Lists the name of the recipes that
|
||||
produce the given packages.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For more information on the <filename>oe-pkgdata-util</filename>
|
||||
command, use the help facility:
|
||||
<literallayout class='monospaced'>
|
||||
$ oe-pkgdata-util ‐‐help
|
||||
$ oe-pkgdata-util <replaceable>subcommand</replaceable> --help
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-viewing-dependencies-between-recipes-and-tasks'>
|
||||
<title>Viewing Dependencies Between Recipes and Tasks</title>
|
||||
|
||||
<para>
|
||||
Sometimes it can be hard to see why BitBake wants to build other
|
||||
recipes before the one you have specified.
|
||||
Dependency information can help you understand why a recipe is
|
||||
built.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To generate dependency information for a recipe, run the following
|
||||
command:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake -g <replaceable>recipename</replaceable>
|
||||
</literallayout>
|
||||
This command writes the following files in the current directory:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
<filename>pn-buildlist</filename>: A list of
|
||||
recipes/targets involved in building
|
||||
<replaceable>recipename</replaceable>.
|
||||
"Involved" here means that at least one task from the
|
||||
recipe needs to run when building
|
||||
<replaceable>recipename</replaceable> from scratch.
|
||||
Targets that are in
|
||||
<link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
|
||||
are not listed.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>task-depends.dot</filename>: A graph showing
|
||||
dependencies between tasks.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The graphs are in
|
||||
<ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink>
|
||||
format and can be converted to images (e.g. using the
|
||||
<filename>dot</filename> tool from
|
||||
<ulink url='http://www.graphviz.org/'>Graphviz</ulink>).
|
||||
<note><title>Notes</title>
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
DOT files use a plain text format.
|
||||
The graphs generated using the
|
||||
<filename>bitbake -g</filename> command are often so
|
||||
large as to be difficult to read without special
|
||||
pruning (e.g. with Bitbake's
|
||||
<filename>-I</filename> option) and processing.
|
||||
Despite the form and size of the graphs, the
|
||||
corresponding <filename>.dot</filename> files can still
|
||||
be possible to read and provide useful information.
|
||||
</para>
|
||||
|
||||
<para>As an example, the
|
||||
<filename>task-depends.dot</filename> file contains
|
||||
lines such as the following:
|
||||
<literallayout class='monospaced'>
|
||||
"libxslt.do_configure" -> "libxml2.do_populate_sysroot"
|
||||
</literallayout>
|
||||
The above example line reveals that the
|
||||
<link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
|
||||
task in <filename>libxslt</filename> depends on the
|
||||
<link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
|
||||
task in <filename>libxml2</filename>, which is a normal
|
||||
<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
|
||||
dependency between the two recipes.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
For an example of how <filename>.dot</filename> files
|
||||
can be processed, see the
|
||||
<filename>scripts/contrib/graph-tool</filename> Python
|
||||
script, which finds and displays paths between graph
|
||||
nodes.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can use a different method to view dependency information
|
||||
by using the following command:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake -g -u taskexp <replaceable>recipename</replaceable>
|
||||
</literallayout>
|
||||
This command displays a GUI window from which you can view
|
||||
build-time and runtime dependencies for the recipes involved in
|
||||
building <replaceable>recipename</replaceable>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-viewing-task-variable-dependencies'>
|
||||
<title>Viewing Task Variable Dependencies</title>
|
||||
|
||||
<para>
|
||||
As mentioned in the
|
||||
"<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>"
|
||||
section of the BitBake User Manual, BitBake tries to automatically
|
||||
determine what variables a task depends on so that it can rerun
|
||||
the task if any values of the variables change.
|
||||
This determination is usually reliable.
|
||||
However, if you do things like construct variable names at runtime,
|
||||
then you might have to manually declare dependencies on those
|
||||
variables using <filename>vardeps</filename> as described in the
|
||||
"<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
|
||||
section of the BitBake User Manual.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are unsure whether a variable dependency is being picked up
|
||||
automatically for a given task, you can list the variable
|
||||
dependencies BitBake has determined by doing the following:
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
Build the recipe containing the task:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake <replaceable>recipename</replaceable>
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Inside the
|
||||
<link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>
|
||||
directory, find the signature data
|
||||
(<filename>sigdata</filename>) file that corresponds to the
|
||||
task.
|
||||
The <filename>sigdata</filename> files contain a pickled
|
||||
Python database of all the metadata that went into creating
|
||||
the input checksum for the task.
|
||||
As an example, for the
|
||||
<link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
|
||||
task of the <filename>db</filename> recipe, the
|
||||
<filename>sigdata</filename> file might be found in the
|
||||
following location:
|
||||
<literallayout class='monospaced'>
|
||||
${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
|
||||
</literallayout>
|
||||
For tasks that are accelerated through the shared state
|
||||
(<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#shared-state-cache'>sstate</ulink>)
|
||||
cache, an additional <filename>siginfo</filename> file is
|
||||
written into
|
||||
<link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
|
||||
along with the cached task output.
|
||||
The <filename>siginfo</filename> files contain exactly the
|
||||
same information as <filename>sigdata</filename> files.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Run <filename>bitbake-dumpsig</filename> on the
|
||||
<filename>sigdata</filename> or
|
||||
<filename>siginfo</filename> file.
|
||||
Here is an example:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
|
||||
</literallayout>
|
||||
In the output of the above command, you will find a line
|
||||
like the following, which lists all the (inferred) variable
|
||||
dependencies for the task.
|
||||
This list also includes indirect dependencies from
|
||||
variables depending on other variables, recursively.
|
||||
<literallayout class='monospaced'>
|
||||
Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch']
|
||||
</literallayout>
|
||||
<note>
|
||||
Functions (e.g. <filename>base_do_fetch</filename>)
|
||||
also count as variable dependencies.
|
||||
These functions in turn depend on the variables they
|
||||
reference.
|
||||
</note>
|
||||
The output of <filename>bitbake-dumpsig</filename> also includes
|
||||
the value each variable had, a list of dependencies for each
|
||||
variable, and
|
||||
<ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>
|
||||
information.
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There is also a <filename>bitbake-diffsigs</filename> command for
|
||||
comparing two <filename>siginfo</filename> or
|
||||
<filename>sigdata</filename> files.
|
||||
This command can be helpful when trying to figure out what changed
|
||||
between two versions of a task.
|
||||
If you call <filename>bitbake-diffsigs</filename> with just one
|
||||
file, the command behaves like
|
||||
<filename>bitbake-dumpsig</filename>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can also use BitBake to dump out the signature construction
|
||||
information without executing tasks by using either of the
|
||||
following BitBake command-line options:
|
||||
<literallayout class='monospaced'>
|
||||
‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable>
|
||||
-S <replaceable>SIGNATURE_HANDLER</replaceable>
|
||||
</literallayout>
|
||||
<note>
|
||||
Two common values for
|
||||
<replaceable>SIGNATURE_HANDLER</replaceable> are "none" and
|
||||
"printdiff", which dump only the signature or compare the
|
||||
dumped signature with the cached one, respectively.
|
||||
</note>
|
||||
Using BitBake with either of these options causes BitBake to dump
|
||||
out <filename>sigdata</filename> files in the
|
||||
<filename>stamps</filename> directory for every task it would have
|
||||
executed instead of building the specified target package.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-debugging-taskrunning'>
|
||||
<title>Running Specific Tasks</title>
|
||||
|
||||
<para>
|
||||
Any given recipe consists of a set of tasks.
|
||||
The standard BitBake behavior in most cases is:
|
||||
<filename>do_fetch</filename>,
|
||||
<filename>do_unpack</filename>,
|
||||
<filename>do_patch</filename>, <filename>do_configure</filename>,
|
||||
<filename>do_compile</filename>, <filename>do_install</filename>,
|
||||
<filename>do_package</filename>,
|
||||
<filename>do_package_write_*</filename>, and
|
||||
<filename>do_build</filename>.
|
||||
The default task is <filename>do_build</filename> and any tasks
|
||||
on which it depends build first.
|
||||
Some tasks, such as <filename>do_devshell</filename>, are not part
|
||||
of the default build chain.
|
||||
If you wish to run a task that is not part of the default build
|
||||
chain, you can use the <filename>-c</filename> option in BitBake.
|
||||
Here is an example:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake matchbox-desktop -c devshell
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>-c</filename> option respects task dependencies,
|
||||
which means that all other tasks (including tasks from other
|
||||
recipes) that the specified task depends on will be run before the
|
||||
task.
|
||||
Even when you manually specify a task to run with
|
||||
<filename>-c</filename>, BitBake will only run the task if it
|
||||
considers it "out of date".
|
||||
See the
|
||||
"<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
|
||||
section in the Yocto Project Overview Manual for how BitBake
|
||||
determines whether a task is "out of date".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you want to force an up-to-date task to be rerun (e.g.
|
||||
because you made manual modifications to the recipe's
|
||||
<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
|
||||
that you want to try out), then you can use the
|
||||
<filename>-f</filename> option.
|
||||
<note>
|
||||
The reason <filename>-f</filename> is never required when
|
||||
running the
|
||||
<link linkend='ref-tasks-devshell'><filename>do_devshell</filename></link>
|
||||
task is because the
|
||||
<filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
|
||||
variable flag is already set for the task.
|
||||
</note>
|
||||
The following example shows one way you can use the
|
||||
<filename>-f</filename> option:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake matchbox-desktop
|
||||
.
|
||||
.
|
||||
make some changes to the source code in the work directory
|
||||
.
|
||||
.
|
||||
$ bitbake matchbox-desktop -c compile -f
|
||||
$ bitbake matchbox-desktop
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This sequence first builds and then recompiles
|
||||
<filename>matchbox-desktop</filename>.
|
||||
The last command reruns all tasks (basically the packaging tasks)
|
||||
after the compile.
|
||||
BitBake recognizes that the <filename>do_compile</filename>
|
||||
task was rerun and therefore understands that the other tasks
|
||||
also need to be run again.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Another, shorter way to rerun a task and all
|
||||
<link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>
|
||||
that depend on it is to use the <filename>-C</filename>
|
||||
option.
|
||||
<note>
|
||||
This option is upper-cased and is separate from the
|
||||
<filename>-c</filename> option, which is lower-cased.
|
||||
</note>
|
||||
Using this option invalidates the given task and then runs the
|
||||
<link linkend='ref-tasks-build'><filename>do_build</filename></link>
|
||||
task, which is the default task if no task is given, and the
|
||||
tasks on which it depends.
|
||||
You could replace the final two commands in the previous example
|
||||
with the following single command:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake matchbox-desktop -C compile
|
||||
</literallayout>
|
||||
Internally, the <filename>-f</filename> and
|
||||
<filename>-C</filename> options work by tainting (modifying) the
|
||||
input checksum of the specified task.
|
||||
This tainting indirectly causes the task and its
|
||||
dependent tasks to be rerun through the normal task dependency
|
||||
mechanisms.
|
||||
<note>
|
||||
BitBake explicitly keeps track of which tasks have been
|
||||
tainted in this fashion, and will print warnings such as the
|
||||
following for builds involving such tasks:
|
||||
<literallayout class='monospaced'>
|
||||
WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
|
||||
</literallayout>
|
||||
The purpose of the warning is to let you know that the work
|
||||
directory and build output might not be in the clean state they
|
||||
would be in for a "normal" build, depending on what actions
|
||||
you took.
|
||||
To get rid of such warnings, you can remove the work directory
|
||||
and rebuild the recipe, as follows:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake matchbox-desktop -c clean
|
||||
$ bitbake matchbox-desktop
|
||||
</literallayout>
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can view a list of tasks in a given package by running the
|
||||
<filename>do_listtasks</filename> task as follows:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake matchbox-desktop -c listtasks
|
||||
</literallayout>
|
||||
The results appear as output to the console and are also in the
|
||||
file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-debugging-bitbake'>
|
||||
<title>General BitBake Problems</title>
|
||||
|
||||
<para>
|
||||
You can see debug output from BitBake by using the <filename>-D</filename> option.
|
||||
The debug output gives more information about what BitBake
|
||||
is doing and the reason behind it.
|
||||
Each <filename>-D</filename> option you use increases the logging level.
|
||||
The most common usage is <filename>-DDD</filename>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The output from <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable> can reveal why
|
||||
BitBake chose a certain version of a package or why BitBake
|
||||
picked a certain provider.
|
||||
This command could also help you in a situation where you think BitBake did something
|
||||
unexpected.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='development-host-system-issues'>
|
||||
<title>Development Host System Issues</title>
|
||||
|
||||
<para>
|
||||
Sometimes issues on the host development system can cause your
|
||||
build to fail.
|
||||
Following are known, host-specific problems.
|
||||
Be sure to always consult the
|
||||
<ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
|
||||
for a look at all release-related issues.
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis><filename>glibc-initial</filename> fails to build</emphasis>:
|
||||
If your development host system has the unpatched
|
||||
<filename>GNU Make 3.82</filename>,
|
||||
the
|
||||
<link linkend='ref-tasks-install'><filename>do_install</filename></link>
|
||||
task fails for <filename>glibc-initial</filename> during
|
||||
the build.</para>
|
||||
<para>Typically, every distribution that ships
|
||||
<filename>GNU Make 3.82</filename> as
|
||||
the default already has the patched version.
|
||||
However, some distributions, such as Debian, have
|
||||
<filename>GNU Make 3.82</filename> as an option, which
|
||||
is unpatched.
|
||||
You will see this error on these types of distributions.
|
||||
Switch to <filename>GNU Make 3.81</filename> or patch
|
||||
your <filename>make</filename> to solve the problem.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-debugging-buildfile'>
|
||||
<title>Building with No Dependencies</title>
|
||||
<para>
|
||||
To build a specific recipe (<filename>.bb</filename> file),
|
||||
you can use the following command form:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb
|
||||
</literallayout>
|
||||
This command form does not check for dependencies.
|
||||
Consequently, you should use it
|
||||
only when you know existing dependencies have been met.
|
||||
<note>
|
||||
You can also specify fragments of the filename.
|
||||
In this case, BitBake checks for a unique match.
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='recipe-logging-mechanisms'>
|
||||
<title>Recipe Logging Mechanisms</title>
|
||||
<para>
|
||||
The Yocto Project provides several logging functions for producing
|
||||
debugging output and reporting errors and warnings.
|
||||
For Python functions, the following logging functions exist.
|
||||
All of these functions log to
|
||||
<filename>${T}/log.do_</filename><replaceable>task</replaceable>,
|
||||
and can also log to standard output (stdout) with the right
|
||||
settings:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
<filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:
|
||||
Writes <replaceable>msg</replaceable> as is to the log while
|
||||
also logging to stdout.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:
|
||||
Writes "NOTE: <replaceable>msg</replaceable>" to the log.
|
||||
Also logs to stdout if BitBake is called with "-v".
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>bb.debug(</filename><replaceable>level</replaceable><filename>, </filename><replaceable>msg</replaceable><filename>)</filename>:
|
||||
Writes "DEBUG: <replaceable>msg</replaceable>" to the log.
|
||||
Also logs to stdout if the log level is greater than or
|
||||
equal to <replaceable>level</replaceable>.
|
||||
See the
|
||||
"<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"
|
||||
option in the BitBake User Manual for more information.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:
|
||||
Writes "WARNING: <replaceable>msg</replaceable>" to the log
|
||||
while also logging to stdout.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:
|
||||
Writes "ERROR: <replaceable>msg</replaceable>" to the log
|
||||
while also logging to stdout.
|
||||
<note>
|
||||
Calling this function does not cause the task to fail.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:
|
||||
This logging function is similar to
|
||||
<filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>
|
||||
but also causes the calling task to fail.
|
||||
<note>
|
||||
<filename>bb.fatal()</filename> raises an exception,
|
||||
which means you do not need to put a "return"
|
||||
statement after the function.
|
||||
</note>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The same logging functions are also available in shell functions,
|
||||
under the names
|
||||
<filename>bbplain</filename>, <filename>bbnote</filename>,
|
||||
<filename>bbdebug</filename>, <filename>bbwarn</filename>,
|
||||
<filename>bberror</filename>, and <filename>bbfatal</filename>.
|
||||
The
|
||||
<link linkend='ref-classes-logging'><filename>logging</filename></link>
|
||||
class implements these functions.
|
||||
See that class in the
|
||||
<filename>meta/classes</filename> folder of the
|
||||
<link linkend='source-directory'>Source Directory</link>
|
||||
for information.
|
||||
</para>
|
||||
|
||||
<section id='logging-with-python'>
|
||||
<title>Logging With Python</title>
|
||||
<para>
|
||||
When creating recipes using Python and inserting code that handles build logs,
|
||||
keep in mind the goal is to have informative logs while keeping the console as
|
||||
"silent" as possible.
|
||||
Also, if you want status messages in the log, use the "debug" loglevel.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Following is an example written in Python.
|
||||
The code handles logging for a function that determines the
|
||||
number of tasks needed to be run.
|
||||
See the
|
||||
"<link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>"
|
||||
section for additional information:
|
||||
<literallayout class='monospaced'>
|
||||
python do_listtasks() {
|
||||
bb.debug(2, "Starting to figure out the task list")
|
||||
if noteworthy_condition:
|
||||
bb.note("There are 47 tasks to run")
|
||||
bb.debug(2, "Got to point xyz")
|
||||
if warning_trigger:
|
||||
bb.warn("Detected warning_trigger, this might be a problem later.")
|
||||
if recoverable_error:
|
||||
bb.error("Hit recoverable_error, you really need to fix this!")
|
||||
if fatal_error:
|
||||
bb.fatal("fatal_error detected, unable to print the task list")
|
||||
bb.plain("The tasks present are abc")
|
||||
bb.debug(2, "Finished figuring out the tasklist")
|
||||
}
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='logging-with-bash'>
|
||||
<title>Logging With Bash</title>
|
||||
<para>
|
||||
When creating recipes using Bash and inserting code that handles build
|
||||
logs, you have the same goals - informative with minimal console output.
|
||||
The syntax you use for recipes written in Bash is similar to that of
|
||||
recipes written in Python described in the previous section.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Following is an example written in Bash.
|
||||
The code logs the progress of the <filename>do_my_function</filename> function.
|
||||
<literallayout class='monospaced'>
|
||||
do_my_function() {
|
||||
bbdebug 2 "Running do_my_function"
|
||||
if [ exceptional_condition ]; then
|
||||
bbnote "Hit exceptional_condition"
|
||||
fi
|
||||
bbdebug 2 "Got to point xyz"
|
||||
if [ warning_trigger ]; then
|
||||
bbwarn "Detected warning_trigger, this might cause a problem later."
|
||||
fi
|
||||
if [ recoverable_error ]; then
|
||||
bberror "Hit recoverable_error, correcting"
|
||||
fi
|
||||
if [ fatal_error ]; then
|
||||
bbfatal "fatal_error detected"
|
||||
fi
|
||||
bbdebug 2 "Completed do_my_function"
|
||||
}
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-debugging-others'>
|
||||
<title>Other Tips</title>
|
||||
|
||||
<para>
|
||||
Here are some other tips that you might find useful:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
When adding new packages, it is worth watching for
|
||||
undesirable items making their way into compiler command
|
||||
lines.
|
||||
For example, you do not want references to local system
|
||||
files like
|
||||
<filename>/usr/lib/</filename> or
|
||||
<filename>/usr/include/</filename>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
If you want to remove the <filename>psplash</filename>
|
||||
boot splashscreen,
|
||||
add <filename>psplash=false</filename> to the kernel
|
||||
command line.
|
||||
Doing so prevents <filename>psplash</filename> from loading
|
||||
and thus allows you to see the console.
|
||||
It is also possible to switch out of the splashscreen by
|
||||
switching the virtual console (e.g. Fn+Left or Fn+Right
|
||||
on a Zaurus).
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Removing
|
||||
<link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
|
||||
(usually <filename>tmp/</filename>, within the
|
||||
<link linkend='build-directory'>Build Directory</link>)
|
||||
can often fix temporary build issues.
|
||||
Removing <filename>TMPDIR</filename> is usually a
|
||||
relatively cheap operation, because task output will be
|
||||
cached in
|
||||
<link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
|
||||
(usually <filename>sstate-cache/</filename>, which is
|
||||
also in the Build Directory).
|
||||
<note>
|
||||
Removing <filename>TMPDIR</filename> might be a
|
||||
workaround rather than a fix.
|
||||
Consequently, trying to determine the underlying cause
|
||||
of an issue before removing the directory is a good
|
||||
idea.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Understanding how a feature is used in practice within
|
||||
existing recipes can be very helpful.
|
||||
It is recommended that you configure some method that
|
||||
allows you to quickly search through files.</para>
|
||||
|
||||
<para>Using GNU Grep, you can use the following shell
|
||||
function to recursively search through common
|
||||
recipe-related files, skipping binary files,
|
||||
<filename>.git</filename> directories, and the
|
||||
Build Directory (assuming its name starts with
|
||||
"build"):
|
||||
<literallayout class='monospaced'>
|
||||
g() {
|
||||
grep -Ir \
|
||||
--exclude-dir=.git \
|
||||
--exclude-dir='build*' \
|
||||
--include='*.bb*' \
|
||||
--include='*.inc*' \
|
||||
--include='*.conf*' \
|
||||
--include='*.py*' \
|
||||
"$@"
|
||||
}
|
||||
</literallayout>
|
||||
Following are some usage examples:
|
||||
<literallayout class='monospaced'>
|
||||
$ g FOO # Search recursively for "FOO"
|
||||
$ g -i foo # Search recursively for "foo", ignoring case
|
||||
$ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR"
|
||||
</literallayout>
|
||||
If figuring out how some feature works requires a lot of
|
||||
searching, it might indicate that the documentation should
|
||||
be extended or improved.
|
||||
In such cases, consider filing a documentation bug using
|
||||
the Yocto Project implementation of
|
||||
<ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.
|
||||
For general information on how to submit a bug against
|
||||
the Yocto Project, see the Yocto Project Bugzilla
|
||||
<ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>"
|
||||
or the
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
|
||||
section, which is in the Yocto Project Development Tasks
|
||||
Manual.
|
||||
<note>
|
||||
The manuals might not be the right place to document
|
||||
variables that are purely internal and have a limited
|
||||
scope (e.g. internal variables used to implement a
|
||||
single <filename>.bbclass</filename> file).
|
||||
</note>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id='ref-quick-emulator-qemu'>
|
||||
<title>Quick EMUlator (QEMU)</title>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user