summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml280
1 files changed, 280 insertions, 0 deletions
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index b824a28869..bc82c70d90 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -360,6 +360,286 @@
360 </section> 360 </section>
361</section> 361</section>
362 362
363<section id='maintaining-build-output-quality'>
364 <title>Maintaining Build Output Quality</title>
365
366 <para>
367 A build's quality can be influenced by several things.
368 For example, if you upgrade a recipe to use a new version of an upstream software
369 package or you experiment with some new configuration options, subtle changes
370 can occur that you might not detect until later.
371 Consider the case where your recipe is using a newer version of an upstream package.
372 In this case, a new version of a piece of software might introduce an optional
373 dependency on another library, which is auto-detected.
374 If that library has already been built when the software is building,
375 then the software will link to the built library and that library will be pulled
376 into your image along with the new software even if you did not want the
377 library.
378 </para>
379
380 <para>
381 The <filename>buildhistory</filename> class exists to help you maintain
382 the quality of your build output.
383 You can use the class to highlight unexpected and possibly unwanted
384 changes in the build output.
385 When you enable build history it records information about the contents of
386 each package and image and then commits that information to a local Git
387 repository where you can examine the information.
388 </para>
389
390 <para>
391 The remainder of this section describes the following:
392 <itemizedlist>
393 <listitem><para>How you can enable and disable
394 build history</para></listitem>
395 <listitem><para>How to understand what the build history contains
396 </para></listitem>
397 <listitem><para>How to limit the information used for build history
398 </para></listitem>
399 <listitem><para>How to examine the build history from both a
400 command-line and web interface</para></listitem>
401 </itemizedlist>
402 </para>
403
404 <section id='enabling-and-disabling-build-history'>
405 <title>Enabling and Disabling Build History</title>
406
407 <para>
408 Build history is disabled by default.
409 To enable it, add the following statements to the end of your
410 <filename>conf/local.conf</filename> file found in the
411 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
412 <literallayout class='monospaced'>
413 INHERIT += "buildhistory"
414 BUILDHISTORY_COMMIT = "1"
415 </literallayout>
416 Enabling build history causes the build process to collect build
417 output information and commit it to a local
418 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
419 <note>
420 Enabling build history increases your build times slightly,
421 particularly for images, and increases the amount of disk
422 space used during the build.
423 </note>
424 </para>
425
426 <para>
427 You can disable build history by removing the previous statements
428 from your <filename>conf/local.conf</filename> file.
429 However, you should realize that enabling and disabling
430 build history in this manner can change the
431 <filename>do_package</filename> task checksums, which if you
432 are using the OEBasicHash signature generator (the default
433 for some distro configurations) will result in the packaging
434 tasks being re-run during the subsequent build.
435 </para>
436
437 <para>
438 To disable the build history functionality without causing the
439 packaging tasks to be re-run, add just this statement to your
440 <filename>conf/local.conf</filename> file:
441 <literallayout class='monospaced'>
442 BUILDHISTORY_FEATURES = ""
443 </literallayout>
444 </para>
445 </section>
446
447 <section id='understanding-what-the-build-history-contains'>
448 <title>Understanding What the Build History Contains</title>
449
450 <para>
451 Build history information is kept in
452 <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename>
453 in the Build Directory.
454 The following is an example abbreviated listing:
455 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
456 </para>
457
458 <section id='build-history-package-information'>
459 <title>Build History Package Information</title>
460
461 <para>
462 The history for each package contains a text file that has
463 name-value pairs with information about the package.
464 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
465 contains the following:
466 <literallayout class='monospaced'>
467 PV = 1.19.3
468 PR = r3
469 RDEPENDS = update-rc.d eglibc (>= 2.13)
470 RRECOMMENDS = busybox-syslog busybox-udhcpc
471 PKGSIZE = 564701
472 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
473 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
474 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
475 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
476 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
477 </literallayout>
478 Most of these name-value pairs corresponds to variables used
479 to produce the package.
480 The exceptions are <filename>FILELIST</filename>, which is the
481 actual list of files in the package, and
482 <filename>PKGSIZE</filename>, which is the total size of files
483 in the package in bytes.
484 </para>
485
486 <para>
487 There is also a file corresponding to the recipe from which the
488 package came (e.g.
489 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
490 <literallayout class='monospaced'>
491 PV = 1.19.3
492 PR = r3
493 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
494 virtual/libc update-rc.d-native
495 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
496 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
497 busybox-staticdev busybox-locale
498 </literallayout>
499 </para>
500 </section>
501
502 <section id='build-history-image-information'>
503 <title>Build History Image Information</title>
504
505 <para>
506 The files produced for each image are as follows:
507 <itemizedlist>
508 <listitem><para><emphasis>build-id:</emphasis>
509 Human-readable information about the build configuration
510 and metadata source revisions.</para></listitem>
511 <listitem><para><emphasis>*.dot:</emphasis>
512 Dependency graphs for the image that are
513 compatible with <filename>graphviz</filename>.
514 </para></listitem>
515 <listitem><para><emphasis>files-in-image.txt:</emphasis>
516 A list of files in the image with permissions,
517 owner, group, size, and symlink information.
518 </para></listitem>
519 <listitem><para><emphasis>image-info.txt:</emphasis>
520 A text file containing name-value pairs with information
521 about the image.
522 See the following listing example for more information.
523 </para></listitem>
524 <listitem><para><emphasis>installed-package-names.txt:</emphasis>
525 A list of installed packages by name only.</para></listitem>
526 <listitem><para><emphasis>installed-package-sizes.txt:</emphasis>
527 A list of installed packages ordered by size.
528 </para></listitem>
529 <listitem><para><emphasis>installed-packages.txt:</emphasis>
530 A list of installed packages with fuill package
531 filenames.</para></listitem>
532 </itemizedlist>
533 <note>
534 Installed package information is able to be gathered and
535 produced even if packaging is disabled for the final image.
536 </note>
537 </para>
538
539 <para>
540 Here is an example of <filename>image-info.txt</filename>:
541 <literallayout class='monospaced'>
542 DISTRO = poky
543 DISTRO_VERSION = 1.1+snapshot-20120207
544 USER_CLASSES = image-mklibs image-prelink
545 IMAGE_CLASSES = image_types
546 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
547 package-management ssh-server-dropbear package-management
548 IMAGE_LINGUAS = en-us en-gb
549 IMAGE_INSTALL = task-core-boot task-base-extended
550 BAD_RECOMMENDATIONS =
551 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
552 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
553 IMAGESIZE = 171816
554 </literallayout>
555 Other than <filename>IMAGESIZE</filename>, which is the
556 total size of the files in the image in Kbytes, the
557 name-value pairs are variables that may have influenced the
558 content of the image.
559 This information is often useful when you are trying to determine
560 why a change in the package or file listings has occurred.
561 </para>
562 </section>
563
564 <section id='limiting-build-history-information'>
565 <title>Limiting Build History Information</title>
566
567 <para>
568 As you can see, build history produces image information,
569 including dependency graphs, so you can see why something
570 was pulled into the image.
571 If you are just interested in this information and not
572 interested in collecting history or any package information,
573 you can limit the build history output by adding the following
574 to your <filename>conf/local.conf</filename> file found in the
575 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
576 <literallayout class='monospaced'>
577 INHERIT += "buildhistory"
578 BUILDHISTORY_COMMIT = "0"
579 BUILDHISTORY_FEATURES = "image"
580 </literallayout>
581 </para>
582 </section>
583
584 <section id='examining-build-history-information'>
585 <title>Examining Build History Information</title>
586
587 <para>
588 You can examine build history output from the command line or
589 from a web interface.
590 </para>
591
592 <para>
593 To see any changes that have occurred (assuming you have
594 <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply
595 use any Git command that allows you to view the history of
596 a repository.
597 Here is one method:
598 <literallayout class='monospaced'>
599 $ git log -p
600 </literallayout>
601 You need to realize, however, that this method does show
602 changes that are not significant (e.g. a package's size
603 changing by a few bytes).
604 </para>
605
606 <para>
607 A command-line tool called <filename>buildhistory-diff</filename>
608 does exist though that queries the Git repository and prints just
609 the differences that might be significant in human-readable form.
610 Here is an example:
611 <literallayout class='monospaced'>
612 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
613 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
614 /etc/anotherpkg.conf was added
615 /sbin/anotherpkg was added
616 * (installed-package-names.txt):
617 * anotherpkg was added
618 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
619 anotherpkg was added
620 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
621 * PR changed from "r0" to "r1"
622 * PV changed from "0.1.10" to "0.1.12"
623 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
624 * PR changed from "r0" to "r1"
625 * PV changed from "0.1.10" to "0.1.12"
626 </literallayout>
627 </para>
628
629 <para>
630 To see changes to the build history using a web interface, follow
631 the instruction in the <filename>README</filename> file here.
632 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
633 </para>
634
635 <para>
636 Here is a sample screenshot of the interface:
637 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
638 </para>
639 </section>
640 </section>
641</section>
642
363</chapter> 643</chapter>
364<!-- 644<!--
365vim: expandtab tw=80 ts=4 645vim: expandtab tw=80 ts=4