diff options
Diffstat (limited to 'documentation/ref-manual/usingpoky.xml')
-rw-r--r-- | documentation/ref-manual/usingpoky.xml | 915 |
1 files changed, 915 insertions, 0 deletions
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml new file mode 100644 index 0000000000..2116852163 --- /dev/null +++ b/documentation/ref-manual/usingpoky.xml | |||
@@ -0,0 +1,915 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <chapter id='usingpoky'> | ||
6 | <title>Using the Yocto Project</title> | ||
7 | |||
8 | <para> | ||
9 | This chapter describes common usage for the Yocto Project. | ||
10 | The information is introductory in nature as other manuals in the Yocto Project | ||
11 | documentation set provide more details on how to use the Yocto Project. | ||
12 | </para> | ||
13 | |||
14 | <section id='usingpoky-build'> | ||
15 | <title>Running a Build</title> | ||
16 | |||
17 | <para> | ||
18 | This section provides a summary of the build process and provides information | ||
19 | for less obvious aspects of the build process. | ||
20 | For general information on how to build an image using the OpenEmbedded build | ||
21 | system, see the | ||
22 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | ||
23 | section of the Yocto Project Quick Start. | ||
24 | </para> | ||
25 | |||
26 | <section id='build-overview'> | ||
27 | <title>Build Overview</title> | ||
28 | |||
29 | <para> | ||
30 | The first thing you need to do is set up the OpenEmbedded build | ||
31 | environment by sourcing an environment setup script | ||
32 | (i.e. | ||
33 | <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link> | ||
34 | or | ||
35 | <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>). | ||
36 | Here is an example: | ||
37 | <literallayout class='monospaced'> | ||
38 | $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>] | ||
39 | </literallayout> | ||
40 | </para> | ||
41 | |||
42 | <para> | ||
43 | The <replaceable>build_dir</replaceable> argument is optional and specifies the directory the | ||
44 | OpenEmbedded build system uses for the build - | ||
45 | the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
46 | If you do not specify a Build Directory, it defaults to a directory | ||
47 | named <filename>build</filename> in your current working directory. | ||
48 | A common practice is to use a different Build Directory for different targets. | ||
49 | For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename> | ||
50 | target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target. | ||
51 | </para> | ||
52 | |||
53 | <para> | ||
54 | Once the build environment is set up, you can build a target using: | ||
55 | <literallayout class='monospaced'> | ||
56 | $ bitbake <replaceable>target</replaceable> | ||
57 | </literallayout> | ||
58 | </para> | ||
59 | |||
60 | <para> | ||
61 | The <replaceable>target</replaceable> is the name of the recipe you want to build. | ||
62 | Common targets are the images in <filename>meta/recipes-core/images</filename>, | ||
63 | <filename>meta/recipes-sato/images</filename>, etc. all found in the | ||
64 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
65 | Or, the target can be the name of a recipe for a specific piece of software such as | ||
66 | BusyBox. | ||
67 | For more details about the images the OpenEmbedded build system supports, see the | ||
68 | "<link linkend="ref-images">Images</link>" chapter. | ||
69 | </para> | ||
70 | |||
71 | <note> | ||
72 | Building an image without GNU General Public License Version | ||
73 | 3 (GPLv3), or similarly licensed, components is supported for | ||
74 | only minimal and base images. | ||
75 | See the "<link linkend='ref-images'>Images</link>" chapter for more information. | ||
76 | </note> | ||
77 | </section> | ||
78 | |||
79 | <section id='building-an-image-using-gpl-components'> | ||
80 | <title>Building an Image Using GPL Components</title> | ||
81 | |||
82 | <para> | ||
83 | When building an image using GPL components, you need to maintain your original | ||
84 | settings and not switch back and forth applying different versions of the GNU | ||
85 | General Public License. | ||
86 | If you rebuild using different versions of GPL, dependency errors might occur | ||
87 | due to some components not being rebuilt. | ||
88 | </para> | ||
89 | </section> | ||
90 | </section> | ||
91 | |||
92 | <section id='usingpoky-install'> | ||
93 | <title>Installing and Using the Result</title> | ||
94 | |||
95 | <para> | ||
96 | Once an image has been built, it often needs to be installed. | ||
97 | The images and kernels built by the OpenEmbedded build system are placed in the | ||
98 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in | ||
99 | <filename class="directory">tmp/deploy/images</filename>. | ||
100 | For information on how to run pre-built images such as <filename>qemux86</filename> | ||
101 | and <filename>qemuarm</filename>, see the | ||
102 | "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" | ||
103 | section in the Yocto Project Quick Start. | ||
104 | For information about how to install these images, see the documentation for your | ||
105 | particular board or machine. | ||
106 | </para> | ||
107 | </section> | ||
108 | |||
109 | <section id='usingpoky-debugging'> | ||
110 | <title>Debugging Build Failures</title> | ||
111 | |||
112 | <para> | ||
113 | The exact method for debugging build failures depends on the nature of | ||
114 | the problem and on the system's area from which the bug originates. | ||
115 | Standard debugging practices such as comparison against the last | ||
116 | known working version with examination of the changes and the | ||
117 | re-application of steps to identify the one causing the problem are | ||
118 | valid for the Yocto Project just as they are for any other system. | ||
119 | Even though it is impossible to detail every possible potential failure, | ||
120 | this section provides some general tips to aid in debugging. | ||
121 | </para> | ||
122 | |||
123 | <para> | ||
124 | A useful feature for debugging is the error reporting tool. | ||
125 | Configuring the Yocto Project to use this tool causes the | ||
126 | OpenEmbedded build system to produce error reporting commands as | ||
127 | part of the console output. | ||
128 | You can enter the commands after the build completes | ||
129 | to log error information | ||
130 | into a common database, that can help you figure out what might be | ||
131 | going wrong. | ||
132 | For information on how to enable and use this feature, see the | ||
133 | "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>Using the Error Reporting Tool</ulink>" | ||
134 | section in the Yocto Project Development Manual. | ||
135 | </para> | ||
136 | |||
137 | <para> | ||
138 | For discussions on debugging, see the | ||
139 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" | ||
140 | and | ||
141 | "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working within Eclipse</ulink>" | ||
142 | sections in the Yocto Project Development Manual. | ||
143 | </para> | ||
144 | |||
145 | <note> | ||
146 | The remainder of this section presents many examples of the | ||
147 | <filename>bitbake</filename> command. | ||
148 | You can learn about BitBake by reading the | ||
149 | <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>. | ||
150 | </note> | ||
151 | |||
152 | |||
153 | <section id='usingpoky-debugging-taskfailures'> | ||
154 | <title>Task Failures</title> | ||
155 | |||
156 | <para>The log file for shell tasks is available in | ||
157 | <filename>${WORKDIR}/temp/log.do_<replaceable>taskname</replaceable>.pid</filename>. | ||
158 | For example, the <filename>do_compile</filename> task for the QEMU minimal image for the x86 | ||
159 | machine (<filename>qemux86</filename>) might be | ||
160 | <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>. | ||
161 | To see what | ||
162 | <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> | ||
163 | runs to generate that log, look at the corresponding | ||
164 | <filename>run.do_<replaceable>taskname</replaceable>.pid</filename> file located in the same directory. | ||
165 | </para> | ||
166 | |||
167 | <para> | ||
168 | Presently, the output from Python tasks is sent directly to the console. | ||
169 | </para> | ||
170 | </section> | ||
171 | |||
172 | <section id='usingpoky-debugging-taskrunning'> | ||
173 | <title>Running Specific Tasks</title> | ||
174 | |||
175 | <para> | ||
176 | Any given package consists of a set of tasks. | ||
177 | The standard BitBake behavior in most cases is: | ||
178 | <filename>do_fetch</filename>, | ||
179 | <filename>do_unpack</filename>, | ||
180 | <filename>do_patch</filename>, <filename>do_configure</filename>, | ||
181 | <filename>do_compile</filename>, <filename>do_install</filename>, | ||
182 | <filename>do_package</filename>, | ||
183 | <filename>do_package_write_*</filename>, and | ||
184 | <filename>do_build</filename>. | ||
185 | The default task is <filename>do_build</filename> and any tasks | ||
186 | on which it depends build first. | ||
187 | Some tasks, such as <filename>do_devshell</filename>, are not part | ||
188 | of the default build chain. | ||
189 | If you wish to run a task that is not part of the default build | ||
190 | chain, you can use the <filename>-c</filename> option in BitBake. | ||
191 | Here is an example: | ||
192 | <literallayout class='monospaced'> | ||
193 | $ bitbake matchbox-desktop -c devshell | ||
194 | </literallayout> | ||
195 | </para> | ||
196 | |||
197 | <para> | ||
198 | If you wish to rerun a task, use the <filename>-f</filename> force | ||
199 | option. | ||
200 | For example, the following sequence forces recompilation after | ||
201 | changing files in the work directory. | ||
202 | <literallayout class='monospaced'> | ||
203 | $ bitbake matchbox-desktop | ||
204 | . | ||
205 | . | ||
206 | <replaceable>make some changes to the source code in the work directory</replaceable> | ||
207 | . | ||
208 | . | ||
209 | $ bitbake matchbox-desktop -c compile -f | ||
210 | $ bitbake matchbox-desktop | ||
211 | </literallayout> | ||
212 | </para> | ||
213 | |||
214 | <para> | ||
215 | This sequence first builds and then recompiles | ||
216 | <filename>matchbox-desktop</filename>. | ||
217 | The last command reruns all tasks (basically the packaging tasks) | ||
218 | after the compile. | ||
219 | BitBake recognizes that the <filename>do_compile</filename> | ||
220 | task was rerun and therefore understands that the other tasks | ||
221 | also need to be run again. | ||
222 | </para> | ||
223 | |||
224 | <para> | ||
225 | You can view a list of tasks in a given package by running the | ||
226 | <filename>do_listtasks</filename> task as follows: | ||
227 | <literallayout class='monospaced'> | ||
228 | $ bitbake matchbox-desktop -c listtasks | ||
229 | </literallayout> | ||
230 | The results appear as output to the console and are also in the | ||
231 | file <filename>${WORKDIR}/temp/log.do_listtasks</filename>. | ||
232 | </para> | ||
233 | </section> | ||
234 | |||
235 | <section id='usingpoky-debugging-dependencies'> | ||
236 | <title>Dependency Graphs</title> | ||
237 | |||
238 | <para> | ||
239 | Sometimes it can be hard to see why BitBake wants to build | ||
240 | other packages before building a given package you have specified. | ||
241 | The <filename>bitbake -g <replaceable>targetname</replaceable></filename> command | ||
242 | creates the <filename>pn-buildlist</filename>, | ||
243 | <filename>pn-depends.dot</filename>, | ||
244 | <filename>package-depends.dot</filename>, and | ||
245 | <filename>task-depends.dot</filename> files in the current | ||
246 | directory. | ||
247 | These files show what will be built and the package and task | ||
248 | dependencies, which are useful for debugging problems. | ||
249 | You can use the | ||
250 | <filename>bitbake -g -u depexp <replaceable>targetname</replaceable></filename> | ||
251 | command to display the results in a more human-readable form. | ||
252 | </para> | ||
253 | </section> | ||
254 | |||
255 | <section id='usingpoky-debugging-bitbake'> | ||
256 | <title>General BitBake Problems</title> | ||
257 | |||
258 | <para> | ||
259 | You can see debug output from BitBake by using the <filename>-D</filename> option. | ||
260 | The debug output gives more information about what BitBake | ||
261 | is doing and the reason behind it. | ||
262 | Each <filename>-D</filename> option you use increases the logging level. | ||
263 | The most common usage is <filename>-DDD</filename>. | ||
264 | </para> | ||
265 | |||
266 | <para> | ||
267 | The output from <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable> can reveal why | ||
268 | BitBake chose a certain version of a package or why BitBake | ||
269 | picked a certain provider. | ||
270 | This command could also help you in a situation where you think BitBake did something | ||
271 | unexpected. | ||
272 | </para> | ||
273 | </section> | ||
274 | |||
275 | <section id='development-host-system-issues'> | ||
276 | <title>Development Host System Issues</title> | ||
277 | |||
278 | <para> | ||
279 | Sometimes issues on the host development system can cause your | ||
280 | build to fail. | ||
281 | Following are known, host-specific problems. | ||
282 | Be sure to always consult the | ||
283 | <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink> | ||
284 | for a look at all release-related issues. | ||
285 | <itemizedlist> | ||
286 | <listitem><para><emphasis><filename>glibc-initial</filename> fails to build</emphasis>: | ||
287 | If your development host system has the unpatched | ||
288 | <filename>GNU Make 3.82</filename>, | ||
289 | the | ||
290 | <link linkend='ref-tasks-install'><filename>do_install</filename></link> | ||
291 | task fails for <filename>glibc-initial</filename> during | ||
292 | the build.</para> | ||
293 | <para>Typically, every distribution that ships | ||
294 | <filename>GNU Make 3.82</filename> as | ||
295 | the default already has the patched version. | ||
296 | However, some distributions, such as Debian, have | ||
297 | <filename>GNU Make 3.82</filename> as an option, which | ||
298 | is unpatched. | ||
299 | You will see this error on these types of distributions. | ||
300 | Switch to <filename>GNU Make 3.81</filename> or patch | ||
301 | your <filename>make</filename> to solve the problem. | ||
302 | </para></listitem> | ||
303 | </itemizedlist> | ||
304 | </para> | ||
305 | </section> | ||
306 | |||
307 | <section id='usingpoky-debugging-buildfile'> | ||
308 | <title>Building with No Dependencies</title> | ||
309 | <para> | ||
310 | To build a specific recipe (<filename>.bb</filename> file), | ||
311 | you can use the following command form: | ||
312 | <literallayout class='monospaced'> | ||
313 | $ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb | ||
314 | </literallayout> | ||
315 | This command form does not check for dependencies. | ||
316 | Consequently, you should use it | ||
317 | only when you know existing dependencies have been met. | ||
318 | <note> | ||
319 | You can also specify fragments of the filename. | ||
320 | In this case, BitBake checks for a unique match. | ||
321 | </note> | ||
322 | </para> | ||
323 | </section> | ||
324 | |||
325 | <section id='usingpoky-debugging-variables'> | ||
326 | <title>Variables</title> | ||
327 | <para> | ||
328 | You can use the <filename>-e</filename> BitBake option to | ||
329 | display the parsing environment for a configuration. | ||
330 | The following displays the general parsing environment: | ||
331 | <literallayout class='monospaced'> | ||
332 | $ bitbake -e | ||
333 | </literallayout> | ||
334 | This next example shows the parsing environment for a specific | ||
335 | recipe: | ||
336 | <literallayout class='monospaced'> | ||
337 | $ bitbake -e <replaceable>recipename</replaceable> | ||
338 | </literallayout> | ||
339 | </para> | ||
340 | </section> | ||
341 | |||
342 | <section id='recipe-logging-mechanisms'> | ||
343 | <title>Recipe Logging Mechanisms</title> | ||
344 | <para> | ||
345 | Best practices exist while writing recipes that both log build progress and | ||
346 | act on build conditions such as warnings and errors. | ||
347 | Both Python and Bash language bindings exist for the logging mechanism: | ||
348 | <itemizedlist> | ||
349 | <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake | ||
350 | supports several loglevels: <filename>bb.fatal</filename>, | ||
351 | <filename>bb.error</filename>, <filename>bb.warn</filename>, | ||
352 | <filename>bb.note</filename>, <filename>bb.plain</filename>, | ||
353 | and <filename>bb.debug</filename>.</para></listitem> | ||
354 | <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set | ||
355 | of loglevels exist and are accessed with a similar syntax: | ||
356 | <filename>bbfatal</filename>, <filename>bberror</filename>, | ||
357 | <filename>bbwarn</filename>, <filename>bbnote</filename>, | ||
358 | <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> | ||
359 | </itemizedlist> | ||
360 | </para> | ||
361 | |||
362 | <para> | ||
363 | For guidance on how logging is handled in both Python and Bash recipes, see the | ||
364 | <filename>logging.bbclass</filename> file in the | ||
365 | <filename>meta/classes</filename> folder of the | ||
366 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
367 | </para> | ||
368 | |||
369 | <section id='logging-with-python'> | ||
370 | <title>Logging With Python</title> | ||
371 | <para> | ||
372 | When creating recipes using Python and inserting code that handles build logs, | ||
373 | keep in mind the goal is to have informative logs while keeping the console as | ||
374 | "silent" as possible. | ||
375 | Also, if you want status messages in the log, use the "debug" loglevel. | ||
376 | </para> | ||
377 | |||
378 | <para> | ||
379 | Following is an example written in Python. | ||
380 | The code handles logging for a function that determines the | ||
381 | number of tasks needed to be run. | ||
382 | See the | ||
383 | "<link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>" | ||
384 | section for additional information: | ||
385 | <literallayout class='monospaced'> | ||
386 | python do_listtasks() { | ||
387 | bb.debug(2, "Starting to figure out the task list") | ||
388 | if noteworthy_condition: | ||
389 | bb.note("There are 47 tasks to run") | ||
390 | bb.debug(2, "Got to point xyz") | ||
391 | if warning_trigger: | ||
392 | bb.warn("Detected warning_trigger, this might be a problem later.") | ||
393 | if recoverable_error: | ||
394 | bb.error("Hit recoverable_error, you really need to fix this!") | ||
395 | if fatal_error: | ||
396 | bb.fatal("fatal_error detected, unable to print the task list") | ||
397 | bb.plain("The tasks present are abc") | ||
398 | bb.debug(2, "Finished figuring out the tasklist") | ||
399 | } | ||
400 | </literallayout> | ||
401 | </para> | ||
402 | </section> | ||
403 | |||
404 | <section id='logging-with-bash'> | ||
405 | <title>Logging With Bash</title> | ||
406 | <para> | ||
407 | When creating recipes using Bash and inserting code that handles build | ||
408 | logs, you have the same goals - informative with minimal console output. | ||
409 | The syntax you use for recipes written in Bash is similar to that of | ||
410 | recipes written in Python described in the previous section. | ||
411 | </para> | ||
412 | |||
413 | <para> | ||
414 | Following is an example written in Bash. | ||
415 | The code logs the progress of the <filename>do_my_function</filename> function. | ||
416 | <literallayout class='monospaced'> | ||
417 | do_my_function() { | ||
418 | bbdebug 2 "Running do_my_function" | ||
419 | if [ exceptional_condition ]; then | ||
420 | bbnote "Hit exceptional_condition" | ||
421 | fi | ||
422 | bbdebug 2 "Got to point xyz" | ||
423 | if [ warning_trigger ]; then | ||
424 | bbwarn "Detected warning_trigger, this might cause a problem later." | ||
425 | fi | ||
426 | if [ recoverable_error ]; then | ||
427 | bberror "Hit recoverable_error, correcting" | ||
428 | fi | ||
429 | if [ fatal_error ]; then | ||
430 | bbfatal "fatal_error detected" | ||
431 | fi | ||
432 | bbdebug 2 "Completed do_my_function" | ||
433 | } | ||
434 | </literallayout> | ||
435 | </para> | ||
436 | </section> | ||
437 | </section> | ||
438 | |||
439 | <section id='usingpoky-debugging-others'> | ||
440 | <title>Other Tips</title> | ||
441 | |||
442 | <para> | ||
443 | Here are some other tips that you might find useful: | ||
444 | <itemizedlist> | ||
445 | <listitem><para>When adding new packages, it is worth watching for | ||
446 | undesirable items making their way into compiler command lines. | ||
447 | For example, you do not want references to local system files like | ||
448 | <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. | ||
449 | </para></listitem> | ||
450 | <listitem><para>If you want to remove the <filename>psplash</filename> | ||
451 | boot splashscreen, | ||
452 | add <filename>psplash=false</filename> to the kernel command line. | ||
453 | Doing so prevents <filename>psplash</filename> from loading | ||
454 | and thus allows you to see the console. | ||
455 | It is also possible to switch out of the splashscreen by | ||
456 | switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). | ||
457 | </para></listitem> | ||
458 | </itemizedlist> | ||
459 | </para> | ||
460 | </section> | ||
461 | </section> | ||
462 | |||
463 | <section id='maintaining-build-output-quality'> | ||
464 | <title>Maintaining Build Output Quality</title> | ||
465 | |||
466 | <para> | ||
467 | Many factors can influence the quality of a build. | ||
468 | For example, if you upgrade a recipe to use a new version of an upstream software | ||
469 | package or you experiment with some new configuration options, subtle changes | ||
470 | can occur that you might not detect until later. | ||
471 | Consider the case where your recipe is using a newer version of an upstream package. | ||
472 | In this case, a new version of a piece of software might introduce an optional | ||
473 | dependency on another library, which is auto-detected. | ||
474 | If that library has already been built when the software is building, | ||
475 | the software will link to the built library and that library will be pulled | ||
476 | into your image along with the new software even if you did not want the | ||
477 | library. | ||
478 | </para> | ||
479 | |||
480 | <para> | ||
481 | The | ||
482 | <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> | ||
483 | class exists to help you maintain | ||
484 | the quality of your build output. | ||
485 | You can use the class to highlight unexpected and possibly unwanted | ||
486 | changes in the build output. | ||
487 | When you enable build history, it records information about the contents of | ||
488 | each package and image and then commits that information to a local Git | ||
489 | repository where you can examine the information. | ||
490 | </para> | ||
491 | |||
492 | <para> | ||
493 | The remainder of this section describes the following: | ||
494 | <itemizedlist> | ||
495 | <listitem><para>How you can enable and disable | ||
496 | build history</para></listitem> | ||
497 | <listitem><para>How to understand what the build history contains | ||
498 | </para></listitem> | ||
499 | <listitem><para>How to limit the information used for build history | ||
500 | </para></listitem> | ||
501 | <listitem><para>How to examine the build history from both a | ||
502 | command-line and web interface</para></listitem> | ||
503 | </itemizedlist> | ||
504 | </para> | ||
505 | |||
506 | <section id='enabling-and-disabling-build-history'> | ||
507 | <title>Enabling and Disabling Build History</title> | ||
508 | |||
509 | <para> | ||
510 | Build history is disabled by default. | ||
511 | To enable it, add the following <filename>INHERIT</filename> | ||
512 | statement and set the | ||
513 | <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link> | ||
514 | variable to "1" at the end of your | ||
515 | <filename>conf/local.conf</filename> file found in the | ||
516 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | ||
517 | <literallayout class='monospaced'> | ||
518 | INHERIT += "buildhistory" | ||
519 | BUILDHISTORY_COMMIT = "1" | ||
520 | </literallayout> | ||
521 | Enabling build history as previously described | ||
522 | causes the build process to collect build | ||
523 | output information and commit it to a local | ||
524 | <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository. | ||
525 | <note> | ||
526 | Enabling build history increases your build times slightly, | ||
527 | particularly for images, and increases the amount of disk | ||
528 | space used during the build. | ||
529 | </note> | ||
530 | </para> | ||
531 | |||
532 | <para> | ||
533 | You can disable build history by removing the previous statements | ||
534 | from your <filename>conf/local.conf</filename> file. | ||
535 | </para> | ||
536 | </section> | ||
537 | |||
538 | <section id='understanding-what-the-build-history-contains'> | ||
539 | <title>Understanding What the Build History Contains</title> | ||
540 | |||
541 | <para> | ||
542 | Build history information is kept in | ||
543 | <filename>${</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>}/buildhistory</filename> | ||
544 | in the Build Directory as defined by the | ||
545 | <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link> | ||
546 | variable. | ||
547 | The following is an example abbreviated listing: | ||
548 | <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" /> | ||
549 | </para> | ||
550 | |||
551 | <para> | ||
552 | At the top level, there is a <filename>metadata-revs</filename> file | ||
553 | that lists the revisions of the repositories for the layers enabled | ||
554 | when the build was produced. | ||
555 | The rest of the data splits into separate | ||
556 | <filename>packages</filename>, <filename>images</filename> and | ||
557 | <filename>sdk</filename> directories, the contents of which are | ||
558 | described below. | ||
559 | </para> | ||
560 | |||
561 | <section id='build-history-package-information'> | ||
562 | <title>Build History Package Information</title> | ||
563 | |||
564 | <para> | ||
565 | The history for each package contains a text file that has | ||
566 | name-value pairs with information about the package. | ||
567 | For example, <filename>buildhistory/packages/i586-poky-linux/busybox/busybox/latest</filename> | ||
568 | contains the following: | ||
569 | <literallayout class='monospaced'> | ||
570 | PV = 1.22.1 | ||
571 | PR = r32 | ||
572 | RPROVIDES = | ||
573 | RDEPENDS = glibc (>= 2.20) update-alternatives-opkg | ||
574 | RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d | ||
575 | PKGSIZE = 540168 | ||
576 | FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \ | ||
577 | /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \ | ||
578 | /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \ | ||
579 | /usr/share/pixmaps /usr/share/applications /usr/share/idl \ | ||
580 | /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers | ||
581 | FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \ | ||
582 | /etc/busybox.links.nosuid /etc/busybox.links.suid | ||
583 | </literallayout> | ||
584 | Most of these name-value pairs correspond to variables used | ||
585 | to produce the package. | ||
586 | The exceptions are <filename>FILELIST</filename>, which is the | ||
587 | actual list of files in the package, and | ||
588 | <filename>PKGSIZE</filename>, which is the total size of files | ||
589 | in the package in bytes. | ||
590 | </para> | ||
591 | |||
592 | <para> | ||
593 | There is also a file corresponding to the recipe from which the | ||
594 | package came (e.g. | ||
595 | <filename>buildhistory/packages/i586-poky-linux/busybox/latest</filename>): | ||
596 | <literallayout class='monospaced'> | ||
597 | PV = 1.22.1 | ||
598 | PR = r32 | ||
599 | DEPENDS = initscripts kern-tools-native update-rc.d-native \ | ||
600 | virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \ | ||
601 | virtual/libc virtual/update-alternatives | ||
602 | PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \ | ||
603 | busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \ | ||
604 | busybox-staticdev busybox-dev busybox-doc busybox-locale busybox | ||
605 | </literallayout> | ||
606 | </para> | ||
607 | |||
608 | <para> | ||
609 | Finally, for those recipes fetched from a version control | ||
610 | system (e.g., Git), a file exists that lists source revisions | ||
611 | that are specified in the recipe and lists the actual revisions | ||
612 | used during the build. | ||
613 | Listed and actual revisions might differ when | ||
614 | <link linkend='var-SRCREV'><filename>SRCREV</filename></link> | ||
615 | is set to | ||
616 | <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>. | ||
617 | Here is an example assuming | ||
618 | <filename>buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev</filename>): | ||
619 | <literallayout class='monospaced'> | ||
620 | # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" | ||
621 | SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" | ||
622 | # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f" | ||
623 | SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f" | ||
624 | </literallayout> | ||
625 | You can use the <filename>buildhistory-collect-srcrevs</filename> | ||
626 | command with the <filename>-a</filename> option to | ||
627 | collect the stored <filename>SRCREV</filename> values | ||
628 | from build history and report them in a format suitable for | ||
629 | use in global configuration (e.g., | ||
630 | <filename>local.conf</filename> or a distro include file) to | ||
631 | override floating <filename>AUTOREV</filename> values to a | ||
632 | fixed set of revisions. | ||
633 | Here is some example output from this command: | ||
634 | <literallayout class='monospaced'> | ||
635 | $ buildhistory-collect-srcrevs -a | ||
636 | # i586-poky-linux | ||
637 | SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072" | ||
638 | SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072" | ||
639 | SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a" | ||
640 | SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4" | ||
641 | # x86_64-linux | ||
642 | SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa" | ||
643 | SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf" | ||
644 | SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11" | ||
645 | SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072" | ||
646 | SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3" | ||
647 | SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca" | ||
648 | SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a" | ||
649 | SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff" | ||
650 | SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4" | ||
651 | # qemux86-poky-linux | ||
652 | SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" | ||
653 | SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f" | ||
654 | # all-poky-linux | ||
655 | SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11" | ||
656 | </literallayout> | ||
657 | <note> | ||
658 | Here are some notes on using the | ||
659 | <filename>buildhistory-collect-srcrevs</filename> command: | ||
660 | <itemizedlist> | ||
661 | <listitem><para>By default, only values where the | ||
662 | <filename>SRCREV</filename> was | ||
663 | not hardcoded (usually when <filename>AUTOREV</filename> | ||
664 | was used) are reported. | ||
665 | Use the <filename>-a</filename> option to see all | ||
666 | <filename>SRCREV</filename> values. | ||
667 | </para></listitem> | ||
668 | <listitem><para>The output statements might not have any effect | ||
669 | if overrides are applied elsewhere in the build system | ||
670 | configuration. | ||
671 | Use the <filename>-f</filename> option to add the | ||
672 | <filename>forcevariable</filename> override to each output line | ||
673 | if you need to work around this restriction. | ||
674 | </para></listitem> | ||
675 | <listitem><para>The script does apply special handling when | ||
676 | building for multiple machines. | ||
677 | However, the script does place a | ||
678 | comment before each set of values that specifies | ||
679 | which triplet to which they belong as shown above | ||
680 | (e.g., <filename>i586-poky-linux</filename>). | ||
681 | </para></listitem> | ||
682 | </itemizedlist> | ||
683 | </note> | ||
684 | </para> | ||
685 | </section> | ||
686 | |||
687 | <section id='build-history-image-information'> | ||
688 | <title>Build History Image Information</title> | ||
689 | |||
690 | <para> | ||
691 | The files produced for each image are as follows: | ||
692 | <itemizedlist> | ||
693 | <listitem><para><filename>image-files:</filename> | ||
694 | A directory containing selected files from the root | ||
695 | filesystem. | ||
696 | The files are defined by | ||
697 | <link linkend='var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></link>. | ||
698 | </para></listitem> | ||
699 | <listitem><para><filename>build-id.txt:</filename> | ||
700 | Human-readable information about the build configuration | ||
701 | and metadata source revisions. | ||
702 | This file contains the full build header as printed | ||
703 | by BitBake.</para></listitem> | ||
704 | <listitem><para><filename>*.dot:</filename> | ||
705 | Dependency graphs for the image that are | ||
706 | compatible with <filename>graphviz</filename>. | ||
707 | </para></listitem> | ||
708 | <listitem><para><filename>files-in-image.txt:</filename> | ||
709 | A list of files in the image with permissions, | ||
710 | owner, group, size, and symlink information. | ||
711 | </para></listitem> | ||
712 | <listitem><para><filename>image-info.txt:</filename> | ||
713 | A text file containing name-value pairs with information | ||
714 | about the image. | ||
715 | See the following listing example for more information. | ||
716 | </para></listitem> | ||
717 | <listitem><para><filename>installed-package-names.txt:</filename> | ||
718 | A list of installed packages by name only.</para></listitem> | ||
719 | <listitem><para><filename>installed-package-sizes.txt:</filename> | ||
720 | A list of installed packages ordered by size. | ||
721 | </para></listitem> | ||
722 | <listitem><para><filename>installed-packages.txt:</filename> | ||
723 | A list of installed packages with full package | ||
724 | filenames.</para></listitem> | ||
725 | </itemizedlist> | ||
726 | <note> | ||
727 | Installed package information is able to be gathered and | ||
728 | produced even if package management is disabled for the final | ||
729 | image. | ||
730 | </note> | ||
731 | </para> | ||
732 | |||
733 | <para> | ||
734 | Here is an example of <filename>image-info.txt</filename>: | ||
735 | <literallayout class='monospaced'> | ||
736 | DISTRO = poky | ||
737 | DISTRO_VERSION = 1.7 | ||
738 | USER_CLASSES = buildstats image-mklibs image-prelink | ||
739 | IMAGE_CLASSES = image_types | ||
740 | IMAGE_FEATURES = debug-tweaks | ||
741 | IMAGE_LINGUAS = | ||
742 | IMAGE_INSTALL = packagegroup-core-boot run-postinsts | ||
743 | BAD_RECOMMENDATIONS = | ||
744 | NO_RECOMMENDATIONS = | ||
745 | PACKAGE_EXCLUDE = | ||
746 | ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \ | ||
747 | write_image_manifest ; buildhistory_list_installed_image ; \ | ||
748 | buildhistory_get_image_installed ; ssh_allow_empty_password; \ | ||
749 | postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ; | ||
750 | IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; | ||
751 | IMAGESIZE = 6900 | ||
752 | </literallayout> | ||
753 | Other than <filename>IMAGESIZE</filename>, which is the | ||
754 | total size of the files in the image in Kbytes, the | ||
755 | name-value pairs are variables that may have influenced the | ||
756 | content of the image. | ||
757 | This information is often useful when you are trying to determine | ||
758 | why a change in the package or file listings has occurred. | ||
759 | </para> | ||
760 | </section> | ||
761 | |||
762 | <section id='using-build-history-to-gather-image-information-only'> | ||
763 | <title>Using Build History to Gather Image Information Only</title> | ||
764 | |||
765 | <para> | ||
766 | As you can see, build history produces image information, | ||
767 | including dependency graphs, so you can see why something | ||
768 | was pulled into the image. | ||
769 | If you are just interested in this information and not | ||
770 | interested in collecting specific package or SDK information, | ||
771 | you can enable writing only image information without | ||
772 | any history by adding the following to your | ||
773 | <filename>conf/local.conf</filename> file found in the | ||
774 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | ||
775 | <literallayout class='monospaced'> | ||
776 | INHERIT += "buildhistory" | ||
777 | BUILDHISTORY_COMMIT = "0" | ||
778 | BUILDHISTORY_FEATURES = "image" | ||
779 | </literallayout> | ||
780 | Here, you set the | ||
781 | <link linkend='var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></link> | ||
782 | variable to use the image feature only. | ||
783 | </para> | ||
784 | </section> | ||
785 | |||
786 | <section id='build-history-sdk-information'> | ||
787 | <title>Build History SDK Information</title> | ||
788 | <para> | ||
789 | Build history collects similar information on the contents | ||
790 | of SDKs (e.g. <filename>meta-toolchain</filename> | ||
791 | or <filename>bitbake -c populate_sdk imagename</filename>) | ||
792 | as compared to information it collects for images. | ||
793 | The following list shows the files produced for each SDK: | ||
794 | <itemizedlist> | ||
795 | <listitem><para><filename>files-in-sdk.txt:</filename> | ||
796 | A list of files in the SDK with permissions, | ||
797 | owner, group, size, and symlink information. | ||
798 | This list includes both the host and target parts | ||
799 | of the SDK. | ||
800 | </para></listitem> | ||
801 | <listitem><para><filename>sdk-info.txt:</filename> | ||
802 | A text file containing name-value pairs with information | ||
803 | about the SDK. | ||
804 | See the following listing example for more information. | ||
805 | </para></listitem> | ||
806 | <listitem><para>The following information appears under | ||
807 | each of the <filename>host</filename> | ||
808 | and <filename>target</filename> directories | ||
809 | for the portions of the SDK that run on the host and | ||
810 | on the target, respectively: | ||
811 | <itemizedlist> | ||
812 | <listitem><para><filename>depends.dot:</filename> | ||
813 | Dependency graph for the SDK that is | ||
814 | compatible with <filename>graphviz</filename>. | ||
815 | </para></listitem> | ||
816 | <listitem><para><filename>installed-package-names.txt:</filename> | ||
817 | A list of installed packages by name only. | ||
818 | </para></listitem> | ||
819 | <listitem><para><filename>installed-package-sizes.txt:</filename> | ||
820 | A list of installed packages ordered by size. | ||
821 | </para></listitem> | ||
822 | <listitem><para><filename>installed-packages.txt:</filename> | ||
823 | A list of installed packages with full package | ||
824 | filenames.</para></listitem> | ||
825 | </itemizedlist> | ||
826 | </para></listitem> | ||
827 | </itemizedlist> | ||
828 | </para> | ||
829 | |||
830 | <para> | ||
831 | Here is an example of <filename>sdk-info.txt</filename>: | ||
832 | <literallayout class='monospaced'> | ||
833 | DISTRO = poky | ||
834 | DISTRO_VERSION = 1.3+snapshot-20130327 | ||
835 | SDK_NAME = poky-glibc-i686-arm | ||
836 | SDK_VERSION = 1.3+snapshot | ||
837 | SDKMACHINE = | ||
838 | SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs | ||
839 | BAD_RECOMMENDATIONS = | ||
840 | SDKSIZE = 352712 | ||
841 | </literallayout> | ||
842 | Other than <filename>SDKSIZE</filename>, which is the | ||
843 | total size of the files in the SDK in Kbytes, the | ||
844 | name-value pairs are variables that might have influenced the | ||
845 | content of the SDK. | ||
846 | This information is often useful when you are trying to | ||
847 | determine why a change in the package or file listings | ||
848 | has occurred. | ||
849 | </para> | ||
850 | </section> | ||
851 | |||
852 | <section id='examining-build-history-information'> | ||
853 | <title>Examining Build History Information</title> | ||
854 | |||
855 | <para> | ||
856 | You can examine build history output from the command line or | ||
857 | from a web interface. | ||
858 | </para> | ||
859 | |||
860 | <para> | ||
861 | To see any changes that have occurred (assuming you have | ||
862 | <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT = "1"</filename></link>), | ||
863 | you can simply | ||
864 | use any Git command that allows you to view the history of | ||
865 | a repository. | ||
866 | Here is one method: | ||
867 | <literallayout class='monospaced'> | ||
868 | $ git log -p | ||
869 | </literallayout> | ||
870 | You need to realize, however, that this method does show | ||
871 | changes that are not significant (e.g. a package's size | ||
872 | changing by a few bytes). | ||
873 | </para> | ||
874 | |||
875 | <para> | ||
876 | A command-line tool called <filename>buildhistory-diff</filename> | ||
877 | does exist, though, that queries the Git repository and prints just | ||
878 | the differences that might be significant in human-readable form. | ||
879 | Here is an example: | ||
880 | <literallayout class='monospaced'> | ||
881 | $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ | ||
882 | Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt): | ||
883 | /etc/anotherpkg.conf was added | ||
884 | /sbin/anotherpkg was added | ||
885 | * (installed-package-names.txt): | ||
886 | * anotherpkg was added | ||
887 | Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt): | ||
888 | anotherpkg was added | ||
889 | packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras" | ||
890 | * PR changed from "r0" to "r1" | ||
891 | * PV changed from "0.1.10" to "0.1.12" | ||
892 | packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%) | ||
893 | * PR changed from "r0" to "r1" | ||
894 | * PV changed from "0.1.10" to "0.1.12" | ||
895 | </literallayout> | ||
896 | </para> | ||
897 | |||
898 | <para> | ||
899 | To see changes to the build history using a web interface, follow | ||
900 | the instruction in the <filename>README</filename> file here. | ||
901 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>. | ||
902 | </para> | ||
903 | |||
904 | <para> | ||
905 | Here is a sample screenshot of the interface: | ||
906 | <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" /> | ||
907 | </para> | ||
908 | </section> | ||
909 | </section> | ||
910 | </section> | ||
911 | |||
912 | </chapter> | ||
913 | <!-- | ||
914 | vim: expandtab tw=80 ts=4 | ||
915 | --> | ||