From 255ca146cc507654bed8c3dcba7e1453e2f690a5 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 2 Nov 2012 13:44:27 -0700 Subject: documentation: poky-ref-manual - New Build History section added. First draft of this new section. Information based on Paul Eggleton's wiki. (From yocto-docs rev: b459d68ab7dd51b258fd378ad15260cba4522dc4) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/usingpoky.xml | 280 ++++++++++++++++++++++++++++ 1 file changed, 280 insertions(+) (limited to 'documentation/poky-ref-manual/usingpoky.xml') 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 @@ +
+ Maintaining Build Output Quality + + + A build's quality can be influenced by several things. + For example, if you upgrade a recipe to use a new version of an upstream software + package or you experiment with some new configuration options, subtle changes + can occur that you might not detect until later. + Consider the case where your recipe is using a newer version of an upstream package. + In this case, a new version of a piece of software might introduce an optional + dependency on another library, which is auto-detected. + If that library has already been built when the software is building, + then the software will link to the built library and that library will be pulled + into your image along with the new software even if you did not want the + library. + + + + The buildhistory class exists to help you maintain + the quality of your build output. + You can use the class to highlight unexpected and possibly unwanted + changes in the build output. + When you enable build history it records information about the contents of + each package and image and then commits that information to a local Git + repository where you can examine the information. + + + + The remainder of this section describes the following: + + How you can enable and disable + build history + How to understand what the build history contains + + How to limit the information used for build history + + How to examine the build history from both a + command-line and web interface + + + +
+ Enabling and Disabling Build History + + + Build history is disabled by default. + To enable it, add the following statements to the end of your + conf/local.conf file found in the + Build Directory: + + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "1" + + Enabling build history causes the build process to collect build + output information and commit it to a local + Git repository. + + Enabling build history increases your build times slightly, + particularly for images, and increases the amount of disk + space used during the build. + + + + + You can disable build history by removing the previous statements + from your conf/local.conf file. + However, you should realize that enabling and disabling + build history in this manner can change the + do_package task checksums, which if you + are using the OEBasicHash signature generator (the default + for some distro configurations) will result in the packaging + tasks being re-run during the subsequent build. + + + + To disable the build history functionality without causing the + packaging tasks to be re-run, add just this statement to your + conf/local.conf file: + + BUILDHISTORY_FEATURES = "" + + +
+ +
+ Understanding What the Build History Contains + + + Build history information is kept in + $TMPDIR/buildhistory + in the Build Directory. + The following is an example abbreviated listing: + + + +
+ Build History Package Information + + + The history for each package contains a text file that has + name-value pairs with information about the package. + For example, buildhistory/packages/core2-poky-linux/busybox/busybox/latest + contains the following: + + PV = 1.19.3 + PR = r3 + RDEPENDS = update-rc.d eglibc (>= 2.13) + RRECOMMENDS = busybox-syslog busybox-udhcpc + PKGSIZE = 564701 + FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ + /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \ + /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ + /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers + FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh + + Most of these name-value pairs corresponds to variables used + to produce the package. + The exceptions are FILELIST, which is the + actual list of files in the package, and + PKGSIZE, which is the total size of files + in the package in bytes. + + + + There is also a file corresponding to the recipe from which the + package came (e.g. + buildhistory/packages/core2-poky-linux/busybox/latest): + + PV = 1.19.3 + PR = r3 + DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \ + virtual/libc update-rc.d-native + PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \ + busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \ + busybox-staticdev busybox-locale + + +
+ +
+ Build History Image Information + + + The files produced for each image are as follows: + + build-id: + Human-readable information about the build configuration + and metadata source revisions. + *.dot: + Dependency graphs for the image that are + compatible with graphviz. + + files-in-image.txt: + A list of files in the image with permissions, + owner, group, size, and symlink information. + + image-info.txt: + A text file containing name-value pairs with information + about the image. + See the following listing example for more information. + + installed-package-names.txt: + A list of installed packages by name only. + installed-package-sizes.txt: + A list of installed packages ordered by size. + + installed-packages.txt: + A list of installed packages with fuill package + filenames. + + + Installed package information is able to be gathered and + produced even if packaging is disabled for the final image. + + + + + Here is an example of image-info.txt: + + DISTRO = poky + DISTRO_VERSION = 1.1+snapshot-20120207 + USER_CLASSES = image-mklibs image-prelink + IMAGE_CLASSES = image_types + IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \ + package-management ssh-server-dropbear package-management + IMAGE_LINGUAS = en-us en-gb + IMAGE_INSTALL = task-core-boot task-base-extended + BAD_RECOMMENDATIONS = + ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; + IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; + IMAGESIZE = 171816 + + Other than IMAGESIZE, which is the + total size of the files in the image in Kbytes, the + name-value pairs are variables that may have influenced the + content of the image. + This information is often useful when you are trying to determine + why a change in the package or file listings has occurred. + +
+ +
+ Limiting Build History Information + + + As you can see, build history produces image information, + including dependency graphs, so you can see why something + was pulled into the image. + If you are just interested in this information and not + interested in collecting history or any package information, + you can limit the build history output by adding the following + to your conf/local.conf file found in the + Build Directory: + + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "0" + BUILDHISTORY_FEATURES = "image" + + +
+ +
+ Examining Build History Information + + + You can examine build history output from the command line or + from a web interface. + + + + To see any changes that have occurred (assuming you have + BUILDHISTORY_COMMIT = "1"), you can simply + use any Git command that allows you to view the history of + a repository. + Here is one method: + + $ git log -p + + You need to realize, however, that this method does show + changes that are not significant (e.g. a package's size + changing by a few bytes). + + + + A command-line tool called buildhistory-diff + does exist though that queries the Git repository and prints just + the differences that might be significant in human-readable form. + Here is an example: + + $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ + Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt): + /etc/anotherpkg.conf was added + /sbin/anotherpkg was added + * (installed-package-names.txt): + * anotherpkg was added + Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt): + anotherpkg was added + packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras" + * PR changed from "r0" to "r1" + * PV changed from "0.1.10" to "0.1.12" + packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%) + * PR changed from "r0" to "r1" + * PV changed from "0.1.10" to "0.1.12" + + + + + To see changes to the build history using a web interface, follow + the instruction in the README file here. + . + + + + Here is a sample screenshot of the interface: + + +
+
+
+