summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-16 10:59:43 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:29 +0000
commit0d52f18d39ee46290a266fabf0d01ad1dffd7bac (patch)
treea1ebfbf384583e6ff91c0c31f697c79a0df4273b /documentation/ref-manual
parent09e9f81c34f1edf432ea217c1c12e99ff0ef4f44 (diff)
downloadpoky-0d52f18d39ee46290a266fabf0d01ad1dffd7bac.tar.gz
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>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/ref-variables.xml9
-rw-r--r--documentation/ref-manual/usingpoky.xml899
2 files changed, 5 insertions, 903 deletions
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 29f227e58c..fa4724984f 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9286,8 +9286,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
9286 <filename>OVERRIDES</filename> in the output of the 9286 <filename>OVERRIDES</filename> in the output of the
9287 <filename>bitbake -e</filename> command. 9287 <filename>bitbake -e</filename> command.
9288 See the 9288 See the
9289 "<link linkend='usingpoky-debugging-viewing-variable-values'>Viewing Variable Values</link>" 9289 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
9290 section for more information. 9290 section in the Yocto Project Development Tasks
9291 Manual for more information.
9291 </note> 9292 </note>
9292 </para> 9293 </para>
9293 </glossdef> 9294 </glossdef>
@@ -10413,8 +10414,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
10413 For examples of how this data is used, see the 10414 For examples of how this data is used, see the
10414 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" 10415 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10415 section in the Yocto Project Overview Manual and the 10416 section in the Yocto Project Overview Manual and the
10416 "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>" 10417 "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
10417 section elsewhere in this manual. 10418 section in the Yocto Project Development Tasks Manual.
10418 </para> 10419 </para>
10419 </glossdef> 10420 </glossdef>
10420 </glossentry> 10421 </glossentry>
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index bfca60a99b..7c2f0f67bc 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -11,905 +11,6 @@
11 documentation set provide more details on how to use the Yocto Project. 11 documentation set provide more details on how to use the Yocto Project.
12 </para> 12 </para>
13 13
14<section id='usingpoky-debugging-tools-and-techniques'>
15 <title>Debugging Tools and Techniques</title>
16
17 <para>
18 The exact method for debugging build failures depends on the nature of
19 the problem and on the system's area from which the bug originates.
20 Standard debugging practices such as comparison against the last
21 known working version with examination of the changes and the
22 re-application of steps to identify the one causing the problem are
23 valid for the Yocto Project just as they are for any other system.
24 Even though it is impossible to detail every possible potential failure,
25 this section provides some general tips to aid in debugging.
26 </para>
27
28 <para>
29 A useful feature for debugging is the error reporting tool.
30 Configuring the Yocto Project to use this tool causes the
31 OpenEmbedded build system to produce error reporting commands as
32 part of the console output.
33 You can enter the commands after the build completes
34 to log error information
35 into a common database, that can help you figure out what might be
36 going wrong.
37 For information on how to enable and use this feature, see the
38 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>Using the Error Reporting Tool</ulink>"
39 section in the Yocto Project Development Tasks Manual.
40 </para>
41
42 <para>
43 For discussions on debugging, see the
44 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" section
45 in the Yocto Project Development Tasks Manual
46 and the
47 "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>"
48 section in the Yocto Project Application Development and the
49 Extensible Software Development Kit (eSDK) manual.
50 </para>
51
52 <note>
53 The remainder of this section presents many examples of the
54 <filename>bitbake</filename> command.
55 You can learn about BitBake by reading the
56 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
57 </note>
58
59 <section id='usingpoky-debugging-viewing-logs-from-failed-tasks'>
60 <title>Viewing Logs from Failed Tasks</title>
61
62 <para>
63 You can find the log for a task in the file
64 <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>.
65 For example, the log for the
66 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
67 task of the QEMU minimal image for the x86 machine
68 (<filename>qemux86</filename>) might be in
69 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
70 To see the commands
71 <link linkend='bitbake-term'>BitBake</link> ran
72 to generate a log, look at the corresponding
73 <filename>run.do_</filename><replaceable>taskname</replaceable>
74 file in the same directory.
75 </para>
76
77 <para>
78 <filename>log.do_</filename><replaceable>taskname</replaceable> and
79 <filename>run.do_</filename><replaceable>taskname</replaceable>
80 are actually symbolic links to
81 <filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>
82 and
83 <filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>,
84 where <replaceable>pid</replaceable> is the PID the task had when
85 it ran.
86 The symlinks always point to the files corresponding to the most
87 recent run.
88 </para>
89 </section>
90
91 <section id='usingpoky-debugging-viewing-variable-values'>
92 <title>Viewing Variable Values</title>
93 <para>
94 BitBake's <filename>-e</filename> option is used to display
95 variable values after parsing.
96 The following command displays the variable values after the
97 configuration files (i.e. <filename>local.conf</filename>,
98 <filename>bblayers.conf</filename>,
99 <filename>bitbake.conf</filename> and so forth) have been
100 parsed:
101 <literallayout class='monospaced'>
102 $ bitbake -e
103 </literallayout>
104 The following command displays variable values after a specific
105 recipe has been parsed.
106 The variables include those from the configuration as well:
107 <literallayout class='monospaced'>
108 $ bitbake -e recipename
109 </literallayout>
110 <note><para>
111 Each recipe has its own private set of variables (datastore).
112 Internally, after parsing the configuration, a copy of the
113 resulting datastore is made prior to parsing each recipe.
114 This copying implies that variables set in one recipe will
115 not be visible to other recipes.</para>
116
117 <para>Likewise, each task within a recipe gets a private
118 datastore based on the recipe datastore, which means that
119 variables set within one task will not be visible to
120 other tasks.</para>
121 </note>
122 </para>
123
124 <para>
125 In the output of <filename>bitbake -e</filename>, each variable is
126 preceded by a description of how the variable got its value,
127 including temporary values that were later overriden.
128 This description also includes variable flags (varflags) set on
129 the variable.
130 The output can be very helpful during debugging.
131 </para>
132
133 <para>
134 Variables that are exported to the environment are preceded by
135 <filename>export</filename> in the output of
136 <filename>bitbake -e</filename>.
137 See the following example:
138 <literallayout class='monospaced'>
139 export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
140 </literallayout>
141 </para>
142
143 <para>
144 In addition to variable values, the output of the
145 <filename>bitbake -e</filename> and
146 <filename>bitbake -e</filename>&nbsp;<replaceable>recipe</replaceable>
147 commands includes the following information:
148 <itemizedlist>
149 <listitem><para>
150 The output starts with a tree listing all configuration
151 files and classes included globally, recursively listing
152 the files they include or inherit in turn.
153 Much of the behavior of the OpenEmbedded build system
154 (including the behavior of the
155 <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>)
156 is implemented in the
157 <link linkend='ref-classes-base'><filename>base</filename></link>
158 class and the classes it inherits, rather than being built
159 into BitBake itself.
160 </para></listitem>
161 <listitem><para>
162 After the variable values, all functions appear in the
163 output.
164 For shell functions, variables referenced within the
165 function body are expanded.
166 If a function has been modified using overrides or
167 using override-style operators like
168 <filename>_append</filename> and
169 <filename>_prepend</filename>, then the final assembled
170 function body appears in the output.
171 </para></listitem>
172 </itemizedlist>
173 </para>
174 </section>
175
176 <section id='viewing-package-information-with-oe-pkgdata-util'>
177 <title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title>
178
179 <para>
180 You can use the <filename>oe-pkgdata-util</filename> command-line
181 utility to query
182 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
183 and display various package-related information.
184 When you use the utility, you must use it to view information
185 on packages that have already been built.
186 </para>
187
188 <para>
189 Following are a few of the available
190 <filename>oe-pkgdata-util</filename> subcommands.
191 <note>
192 You can use the standard * and ? globbing wildcards as part of
193 package names and paths.
194 </note>
195 <itemizedlist>
196 <listitem><para>
197 <filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>:
198 Lists all packages that have been built, optionally
199 limiting the match to packages that match
200 <replaceable>pattern</replaceable>.
201 </para></listitem>
202 <listitem><para>
203 <filename>oe-pkgdata-util list-pkg-files&nbsp;</filename><replaceable>package</replaceable><filename>&nbsp;...</filename>:
204 Lists the files and directories contained in the given
205 packages.
206 <note>
207 <para>
208 A different way to view the contents of a package is
209 to look at the
210 <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/packages-split</filename>
211 directory of the recipe that generates the
212 package.
213 This directory is created by the
214 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
215 task and has one subdirectory for each package the
216 recipe generates, which contains the files stored in
217 that package.</para>
218 <para>
219 If you want to inspect the
220 <filename>${WORKDIR}/packages-split</filename>
221 directory, make sure that
222 <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link>
223 is not enabled when you build the recipe.
224 </para>
225 </note>
226 </para></listitem>
227 <listitem><para>
228 <filename>oe-pkgdata-util find-path&nbsp;</filename><replaceable>path</replaceable><filename>&nbsp;...</filename>:
229 Lists the names of the packages that contain the given
230 paths.
231 For example, the following tells us that
232 <filename>/usr/share/man/man1/make.1</filename>
233 is contained in the <filename>make-doc</filename>
234 package:
235 <literallayout class='monospaced'>
236 $ oe-pkgdata-util find-path /usr/share/man/man1/make.1
237 make-doc: /usr/share/man/man1/make.1
238 </literallayout>
239 </para></listitem>
240 <listitem><para>
241 <filename>oe-pkgdata-util lookup-recipe&nbsp;</filename><replaceable>package</replaceable><filename>&nbsp;...</filename>:
242 Lists the name of the recipes that
243 produce the given packages.
244 </para></listitem>
245 </itemizedlist>
246 </para>
247
248 <para>
249 For more information on the <filename>oe-pkgdata-util</filename>
250 command, use the help facility:
251 <literallayout class='monospaced'>
252 $ oe-pkgdata-util &dash;&dash;help
253 $ oe-pkgdata-util <replaceable>subcommand</replaceable> --help
254 </literallayout>
255 </para>
256 </section>
257
258 <section id='usingpoky-viewing-dependencies-between-recipes-and-tasks'>
259 <title>Viewing Dependencies Between Recipes and Tasks</title>
260
261 <para>
262 Sometimes it can be hard to see why BitBake wants to build other
263 recipes before the one you have specified.
264 Dependency information can help you understand why a recipe is
265 built.
266 </para>
267
268 <para>
269 To generate dependency information for a recipe, run the following
270 command:
271 <literallayout class='monospaced'>
272 $ bitbake -g <replaceable>recipename</replaceable>
273 </literallayout>
274 This command writes the following files in the current directory:
275 <itemizedlist>
276 <listitem><para>
277 <filename>pn-buildlist</filename>: A list of
278 recipes/targets involved in building
279 <replaceable>recipename</replaceable>.
280 "Involved" here means that at least one task from the
281 recipe needs to run when building
282 <replaceable>recipename</replaceable> from scratch.
283 Targets that are in
284 <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
285 are not listed.
286 </para></listitem>
287 <listitem><para>
288 <filename>task-depends.dot</filename>: A graph showing
289 dependencies between tasks.
290 </para></listitem>
291 </itemizedlist>
292 </para>
293
294 <para>
295 The graphs are in
296 <ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink>
297 format and can be converted to images (e.g. using the
298 <filename>dot</filename> tool from
299 <ulink url='http://www.graphviz.org/'>Graphviz</ulink>).
300 <note><title>Notes</title>
301 <itemizedlist>
302 <listitem><para>
303 DOT files use a plain text format.
304 The graphs generated using the
305 <filename>bitbake -g</filename> command are often so
306 large as to be difficult to read without special
307 pruning (e.g. with Bitbake's
308 <filename>-I</filename> option) and processing.
309 Despite the form and size of the graphs, the
310 corresponding <filename>.dot</filename> files can still
311 be possible to read and provide useful information.
312 </para>
313
314 <para>As an example, the
315 <filename>task-depends.dot</filename> file contains
316 lines such as the following:
317 <literallayout class='monospaced'>
318 "libxslt.do_configure" -> "libxml2.do_populate_sysroot"
319 </literallayout>
320 The above example line reveals that the
321 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
322 task in <filename>libxslt</filename> depends on the
323 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
324 task in <filename>libxml2</filename>, which is a normal
325 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
326 dependency between the two recipes.
327 </para></listitem>
328 <listitem><para>
329 For an example of how <filename>.dot</filename> files
330 can be processed, see the
331 <filename>scripts/contrib/graph-tool</filename> Python
332 script, which finds and displays paths between graph
333 nodes.
334 </para></listitem>
335 </itemizedlist>
336 </note>
337 </para>
338
339 <para>
340 You can use a different method to view dependency information
341 by using the following command:
342 <literallayout class='monospaced'>
343 $ bitbake -g -u taskexp <replaceable>recipename</replaceable>
344 </literallayout>
345 This command displays a GUI window from which you can view
346 build-time and runtime dependencies for the recipes involved in
347 building <replaceable>recipename</replaceable>.
348 </para>
349 </section>
350
351 <section id='usingpoky-viewing-task-variable-dependencies'>
352 <title>Viewing Task Variable Dependencies</title>
353
354 <para>
355 As mentioned in the
356 "<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>"
357 section of the BitBake User Manual, BitBake tries to automatically
358 determine what variables a task depends on so that it can rerun
359 the task if any values of the variables change.
360 This determination is usually reliable.
361 However, if you do things like construct variable names at runtime,
362 then you might have to manually declare dependencies on those
363 variables using <filename>vardeps</filename> as described in the
364 "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
365 section of the BitBake User Manual.
366 </para>
367
368 <para>
369 If you are unsure whether a variable dependency is being picked up
370 automatically for a given task, you can list the variable
371 dependencies BitBake has determined by doing the following:
372 <orderedlist>
373 <listitem><para>
374 Build the recipe containing the task:
375 <literallayout class='monospaced'>
376 $ bitbake <replaceable>recipename</replaceable>
377 </literallayout>
378 </para></listitem>
379 <listitem><para>
380 Inside the
381 <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>
382 directory, find the signature data
383 (<filename>sigdata</filename>) file that corresponds to the
384 task.
385 The <filename>sigdata</filename> files contain a pickled
386 Python database of all the metadata that went into creating
387 the input checksum for the task.
388 As an example, for the
389 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
390 task of the <filename>db</filename> recipe, the
391 <filename>sigdata</filename> file might be found in the
392 following location:
393 <literallayout class='monospaced'>
394 ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
395 </literallayout>
396 For tasks that are accelerated through the shared state
397 (<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#shared-state-cache'>sstate</ulink>)
398 cache, an additional <filename>siginfo</filename> file is
399 written into
400 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
401 along with the cached task output.
402 The <filename>siginfo</filename> files contain exactly the
403 same information as <filename>sigdata</filename> files.
404 </para></listitem>
405 <listitem><para>
406 Run <filename>bitbake-dumpsig</filename> on the
407 <filename>sigdata</filename> or
408 <filename>siginfo</filename> file.
409 Here is an example:
410 <literallayout class='monospaced'>
411 $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
412 </literallayout>
413 In the output of the above command, you will find a line
414 like the following, which lists all the (inferred) variable
415 dependencies for the task.
416 This list also includes indirect dependencies from
417 variables depending on other variables, recursively.
418 <literallayout class='monospaced'>
419 Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch']
420 </literallayout>
421 <note>
422 Functions (e.g. <filename>base_do_fetch</filename>)
423 also count as variable dependencies.
424 These functions in turn depend on the variables they
425 reference.
426 </note>
427 The output of <filename>bitbake-dumpsig</filename> also includes
428 the value each variable had, a list of dependencies for each
429 variable, and
430 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>
431 information.
432 </para></listitem>
433 </orderedlist>
434 </para>
435
436 <para>
437 There is also a <filename>bitbake-diffsigs</filename> command for
438 comparing two <filename>siginfo</filename> or
439 <filename>sigdata</filename> files.
440 This command can be helpful when trying to figure out what changed
441 between two versions of a task.
442 If you call <filename>bitbake-diffsigs</filename> with just one
443 file, the command behaves like
444 <filename>bitbake-dumpsig</filename>.
445 </para>
446
447 <para>
448 You can also use BitBake to dump out the signature construction
449 information without executing tasks by using either of the
450 following BitBake command-line options:
451 <literallayout class='monospaced'>
452 &dash;&dash;dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable>
453 -S <replaceable>SIGNATURE_HANDLER</replaceable>
454 </literallayout>
455 <note>
456 Two common values for
457 <replaceable>SIGNATURE_HANDLER</replaceable> are "none" and
458 "printdiff", which dump only the signature or compare the
459 dumped signature with the cached one, respectively.
460 </note>
461 Using BitBake with either of these options causes BitBake to dump
462 out <filename>sigdata</filename> files in the
463 <filename>stamps</filename> directory for every task it would have
464 executed instead of building the specified target package.
465 </para>
466 </section>
467
468 <section id='usingpoky-debugging-taskrunning'>
469 <title>Running Specific Tasks</title>
470
471 <para>
472 Any given recipe consists of a set of tasks.
473 The standard BitBake behavior in most cases is:
474 <filename>do_fetch</filename>,
475 <filename>do_unpack</filename>,
476 <filename>do_patch</filename>, <filename>do_configure</filename>,
477 <filename>do_compile</filename>, <filename>do_install</filename>,
478 <filename>do_package</filename>,
479 <filename>do_package_write_*</filename>, and
480 <filename>do_build</filename>.
481 The default task is <filename>do_build</filename> and any tasks
482 on which it depends build first.
483 Some tasks, such as <filename>do_devshell</filename>, are not part
484 of the default build chain.
485 If you wish to run a task that is not part of the default build
486 chain, you can use the <filename>-c</filename> option in BitBake.
487 Here is an example:
488 <literallayout class='monospaced'>
489 $ bitbake matchbox-desktop -c devshell
490 </literallayout>
491 </para>
492
493 <para>
494 The <filename>-c</filename> option respects task dependencies,
495 which means that all other tasks (including tasks from other
496 recipes) that the specified task depends on will be run before the
497 task.
498 Even when you manually specify a task to run with
499 <filename>-c</filename>, BitBake will only run the task if it
500 considers it "out of date".
501 See the
502 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
503 section in the Yocto Project Overview Manual for how BitBake
504 determines whether a task is "out of date".
505 </para>
506
507 <para>
508 If you want to force an up-to-date task to be rerun (e.g.
509 because you made manual modifications to the recipe's
510 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
511 that you want to try out), then you can use the
512 <filename>-f</filename> option.
513 <note>
514 The reason <filename>-f</filename> is never required when
515 running the
516 <link linkend='ref-tasks-devshell'><filename>do_devshell</filename></link>
517 task is because the
518 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
519 variable flag is already set for the task.
520 </note>
521 The following example shows one way you can use the
522 <filename>-f</filename> option:
523 <literallayout class='monospaced'>
524 $ bitbake matchbox-desktop
525 .
526 .
527 make some changes to the source code in the work directory
528 .
529 .
530 $ bitbake matchbox-desktop -c compile -f
531 $ bitbake matchbox-desktop
532 </literallayout>
533 </para>
534
535 <para>
536 This sequence first builds and then recompiles
537 <filename>matchbox-desktop</filename>.
538 The last command reruns all tasks (basically the packaging tasks)
539 after the compile.
540 BitBake recognizes that the <filename>do_compile</filename>
541 task was rerun and therefore understands that the other tasks
542 also need to be run again.
543 </para>
544
545 <para>
546 Another, shorter way to rerun a task and all
547 <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>
548 that depend on it is to use the <filename>-C</filename>
549 option.
550 <note>
551 This option is upper-cased and is separate from the
552 <filename>-c</filename> option, which is lower-cased.
553 </note>
554 Using this option invalidates the given task and then runs the
555 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
556 task, which is the default task if no task is given, and the
557 tasks on which it depends.
558 You could replace the final two commands in the previous example
559 with the following single command:
560 <literallayout class='monospaced'>
561 $ bitbake matchbox-desktop -C compile
562 </literallayout>
563 Internally, the <filename>-f</filename> and
564 <filename>-C</filename> options work by tainting (modifying) the
565 input checksum of the specified task.
566 This tainting indirectly causes the task and its
567 dependent tasks to be rerun through the normal task dependency
568 mechanisms.
569 <note>
570 BitBake explicitly keeps track of which tasks have been
571 tainted in this fashion, and will print warnings such as the
572 following for builds involving such tasks:
573 <literallayout class='monospaced'>
574 WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
575 </literallayout>
576 The purpose of the warning is to let you know that the work
577 directory and build output might not be in the clean state they
578 would be in for a "normal" build, depending on what actions
579 you took.
580 To get rid of such warnings, you can remove the work directory
581 and rebuild the recipe, as follows:
582 <literallayout class='monospaced'>
583 $ bitbake matchbox-desktop -c clean
584 $ bitbake matchbox-desktop
585 </literallayout>
586 </note>
587 </para>
588
589 <para>
590 You can view a list of tasks in a given package by running the
591 <filename>do_listtasks</filename> task as follows:
592 <literallayout class='monospaced'>
593 $ bitbake matchbox-desktop -c listtasks
594 </literallayout>
595 The results appear as output to the console and are also in the
596 file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
597 </para>
598 </section>
599
600 <section id='usingpoky-debugging-bitbake'>
601 <title>General BitBake Problems</title>
602
603 <para>
604 You can see debug output from BitBake by using the <filename>-D</filename> option.
605 The debug output gives more information about what BitBake
606 is doing and the reason behind it.
607 Each <filename>-D</filename> option you use increases the logging level.
608 The most common usage is <filename>-DDD</filename>.
609 </para>
610
611 <para>
612 The output from <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable> can reveal why
613 BitBake chose a certain version of a package or why BitBake
614 picked a certain provider.
615 This command could also help you in a situation where you think BitBake did something
616 unexpected.
617 </para>
618 </section>
619
620 <section id='development-host-system-issues'>
621 <title>Development Host System Issues</title>
622
623 <para>
624 Sometimes issues on the host development system can cause your
625 build to fail.
626 Following are known, host-specific problems.
627 Be sure to always consult the
628 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
629 for a look at all release-related issues.
630 <itemizedlist>
631 <listitem><para><emphasis><filename>glibc-initial</filename> fails to build</emphasis>:
632 If your development host system has the unpatched
633 <filename>GNU Make 3.82</filename>,
634 the
635 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
636 task fails for <filename>glibc-initial</filename> during
637 the build.</para>
638 <para>Typically, every distribution that ships
639 <filename>GNU Make 3.82</filename> as
640 the default already has the patched version.
641 However, some distributions, such as Debian, have
642 <filename>GNU Make 3.82</filename> as an option, which
643 is unpatched.
644 You will see this error on these types of distributions.
645 Switch to <filename>GNU Make 3.81</filename> or patch
646 your <filename>make</filename> to solve the problem.
647 </para></listitem>
648 </itemizedlist>
649 </para>
650 </section>
651
652 <section id='usingpoky-debugging-buildfile'>
653 <title>Building with No Dependencies</title>
654 <para>
655 To build a specific recipe (<filename>.bb</filename> file),
656 you can use the following command form:
657 <literallayout class='monospaced'>
658 $ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb
659 </literallayout>
660 This command form does not check for dependencies.
661 Consequently, you should use it
662 only when you know existing dependencies have been met.
663 <note>
664 You can also specify fragments of the filename.
665 In this case, BitBake checks for a unique match.
666 </note>
667 </para>
668 </section>
669
670 <section id='recipe-logging-mechanisms'>
671 <title>Recipe Logging Mechanisms</title>
672 <para>
673 The Yocto Project provides several logging functions for producing
674 debugging output and reporting errors and warnings.
675 For Python functions, the following logging functions exist.
676 All of these functions log to
677 <filename>${T}/log.do_</filename><replaceable>task</replaceable>,
678 and can also log to standard output (stdout) with the right
679 settings:
680 <itemizedlist>
681 <listitem><para>
682 <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:
683 Writes <replaceable>msg</replaceable> as is to the log while
684 also logging to stdout.
685 </para></listitem>
686 <listitem><para>
687 <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:
688 Writes "NOTE: <replaceable>msg</replaceable>" to the log.
689 Also logs to stdout if BitBake is called with "-v".
690 </para></listitem>
691 <listitem><para>
692 <filename>bb.debug(</filename><replaceable>level</replaceable><filename>,&nbsp;</filename><replaceable>msg</replaceable><filename>)</filename>:
693 Writes "DEBUG: <replaceable>msg</replaceable>" to the log.
694 Also logs to stdout if the log level is greater than or
695 equal to <replaceable>level</replaceable>.
696 See the
697 "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"
698 option in the BitBake User Manual for more information.
699 </para></listitem>
700 <listitem><para>
701 <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:
702 Writes "WARNING: <replaceable>msg</replaceable>" to the log
703 while also logging to stdout.
704 </para></listitem>
705 <listitem><para>
706 <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:
707 Writes "ERROR: <replaceable>msg</replaceable>" to the log
708 while also logging to stdout.
709 <note>
710 Calling this function does not cause the task to fail.
711 </note>
712 </para></listitem>
713 <listitem><para>
714 <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:
715 This logging function is similar to
716 <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>
717 but also causes the calling task to fail.
718 <note>
719 <filename>bb.fatal()</filename> raises an exception,
720 which means you do not need to put a "return"
721 statement after the function.
722 </note>
723 </para></listitem>
724 </itemizedlist>
725 </para>
726
727 <para>
728 The same logging functions are also available in shell functions,
729 under the names
730 <filename>bbplain</filename>, <filename>bbnote</filename>,
731 <filename>bbdebug</filename>, <filename>bbwarn</filename>,
732 <filename>bberror</filename>, and <filename>bbfatal</filename>.
733 The
734 <link linkend='ref-classes-logging'><filename>logging</filename></link>
735 class implements these functions.
736 See that class in the
737 <filename>meta/classes</filename> folder of the
738 <link linkend='source-directory'>Source Directory</link>
739 for information.
740 </para>
741
742 <section id='logging-with-python'>
743 <title>Logging With Python</title>
744 <para>
745 When creating recipes using Python and inserting code that handles build logs,
746 keep in mind the goal is to have informative logs while keeping the console as
747 "silent" as possible.
748 Also, if you want status messages in the log, use the "debug" loglevel.
749 </para>
750
751 <para>
752 Following is an example written in Python.
753 The code handles logging for a function that determines the
754 number of tasks needed to be run.
755 See the
756 "<link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>"
757 section for additional information:
758 <literallayout class='monospaced'>
759 python do_listtasks() {
760 bb.debug(2, "Starting to figure out the task list")
761 if noteworthy_condition:
762 bb.note("There are 47 tasks to run")
763 bb.debug(2, "Got to point xyz")
764 if warning_trigger:
765 bb.warn("Detected warning_trigger, this might be a problem later.")
766 if recoverable_error:
767 bb.error("Hit recoverable_error, you really need to fix this!")
768 if fatal_error:
769 bb.fatal("fatal_error detected, unable to print the task list")
770 bb.plain("The tasks present are abc")
771 bb.debug(2, "Finished figuring out the tasklist")
772 }
773 </literallayout>
774 </para>
775 </section>
776
777 <section id='logging-with-bash'>
778 <title>Logging With Bash</title>
779 <para>
780 When creating recipes using Bash and inserting code that handles build
781 logs, you have the same goals - informative with minimal console output.
782 The syntax you use for recipes written in Bash is similar to that of
783 recipes written in Python described in the previous section.
784 </para>
785
786 <para>
787 Following is an example written in Bash.
788 The code logs the progress of the <filename>do_my_function</filename> function.
789 <literallayout class='monospaced'>
790 do_my_function() {
791 bbdebug 2 "Running do_my_function"
792 if [ exceptional_condition ]; then
793 bbnote "Hit exceptional_condition"
794 fi
795 bbdebug 2 "Got to point xyz"
796 if [ warning_trigger ]; then
797 bbwarn "Detected warning_trigger, this might cause a problem later."
798 fi
799 if [ recoverable_error ]; then
800 bberror "Hit recoverable_error, correcting"
801 fi
802 if [ fatal_error ]; then
803 bbfatal "fatal_error detected"
804 fi
805 bbdebug 2 "Completed do_my_function"
806 }
807 </literallayout>
808 </para>
809 </section>
810 </section>
811
812 <section id='usingpoky-debugging-others'>
813 <title>Other Tips</title>
814
815 <para>
816 Here are some other tips that you might find useful:
817 <itemizedlist>
818 <listitem><para>
819 When adding new packages, it is worth watching for
820 undesirable items making their way into compiler command
821 lines.
822 For example, you do not want references to local system
823 files like
824 <filename>/usr/lib/</filename> or
825 <filename>/usr/include/</filename>.
826 </para></listitem>
827 <listitem><para>
828 If you want to remove the <filename>psplash</filename>
829 boot splashscreen,
830 add <filename>psplash=false</filename> to the kernel
831 command line.
832 Doing so prevents <filename>psplash</filename> from loading
833 and thus allows you to see the console.
834 It is also possible to switch out of the splashscreen by
835 switching the virtual console (e.g. Fn+Left or Fn+Right
836 on a Zaurus).
837 </para></listitem>
838 <listitem><para>
839 Removing
840 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
841 (usually <filename>tmp/</filename>, within the
842 <link linkend='build-directory'>Build Directory</link>)
843 can often fix temporary build issues.
844 Removing <filename>TMPDIR</filename> is usually a
845 relatively cheap operation, because task output will be
846 cached in
847 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
848 (usually <filename>sstate-cache/</filename>, which is
849 also in the Build Directory).
850 <note>
851 Removing <filename>TMPDIR</filename> might be a
852 workaround rather than a fix.
853 Consequently, trying to determine the underlying cause
854 of an issue before removing the directory is a good
855 idea.
856 </note>
857 </para></listitem>
858 <listitem><para>
859 Understanding how a feature is used in practice within
860 existing recipes can be very helpful.
861 It is recommended that you configure some method that
862 allows you to quickly search through files.</para>
863
864 <para>Using GNU Grep, you can use the following shell
865 function to recursively search through common
866 recipe-related files, skipping binary files,
867 <filename>.git</filename> directories, and the
868 Build Directory (assuming its name starts with
869 "build"):
870 <literallayout class='monospaced'>
871 g() {
872 grep -Ir \
873 --exclude-dir=.git \
874 --exclude-dir='build*' \
875 --include='*.bb*' \
876 --include='*.inc*' \
877 --include='*.conf*' \
878 --include='*.py*' \
879 "$@"
880 }
881 </literallayout>
882 Following are some usage examples:
883 <literallayout class='monospaced'>
884 $ g FOO # Search recursively for "FOO"
885 $ g -i foo # Search recursively for "foo", ignoring case
886 $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR"
887 </literallayout>
888 If figuring out how some feature works requires a lot of
889 searching, it might indicate that the documentation should
890 be extended or improved.
891 In such cases, consider filing a documentation bug using
892 the Yocto Project implementation of
893 <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.
894 For general information on how to submit a bug against
895 the Yocto Project, see the Yocto Project Bugzilla
896 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>"
897 or the
898 <ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
899 section, which is in the Yocto Project Development Tasks
900 Manual.
901 <note>
902 The manuals might not be the right place to document
903 variables that are purely internal and have a limited
904 scope (e.g. internal variables used to implement a
905 single <filename>.bbclass</filename> file).
906 </note>
907 </para></listitem>
908 </itemizedlist>
909 </para>
910 </section>
911</section>
912
913<section id='ref-quick-emulator-qemu'> 14<section id='ref-quick-emulator-qemu'>
914 <title>Quick EMUlator (QEMU)</title> 15 <title>Quick EMUlator (QEMU)</title>
915 16
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-07-17 10:20:27 +0000