diff options
Diffstat (limited to 'documentation/ref-manual/usingpoky.xml')
-rw-r--r-- | documentation/ref-manual/usingpoky.xml | 899 |
1 files changed, 0 insertions, 899 deletions
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> <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 </filename><replaceable>package</replaceable><filename> ...</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 </filename><replaceable>path</replaceable><filename> ...</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 </filename><replaceable>package</replaceable><filename> ...</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 ‐‐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 | ‐‐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>, </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 | ||