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