summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/usingpoky.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/usingpoky.xml')
-rw-r--r--documentation/ref-manual/usingpoky.xml915
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<!--
914vim: expandtab tw=80 ts=4
915-->