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 <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

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 @@
     </section>
 </section>
 
+<section id='maintaining-build-output-quality'>
+    <title>Maintaining Build Output Quality</title>
+
+    <para>
+        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.
+    </para>
+
+    <para>
+        The <filename>buildhistory</filename> 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.
+    </para>
+
+    <para>
+        The remainder of this section describes the following:
+        <itemizedlist>
+           <listitem><para>How you can enable and disable
+               build history</para></listitem>
+           <listitem><para>How to understand what the build history contains
+               </para></listitem>
+           <listitem><para>How to limit the information used for build history
+               </para></listitem>
+           <listitem><para>How to examine the build history from both a 
+               command-line and web interface</para></listitem>
+       </itemizedlist>
+    </para>
+
+    <section id='enabling-and-disabling-build-history'>
+        <title>Enabling and Disabling Build History</title>
+
+        <para>
+            Build history is disabled by default.
+            To enable it, add the following statements to the end of your 
+            <filename>conf/local.conf</filename> file found in the 
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+            <literallayout class='monospaced'>
+     INHERIT += "buildhistory"
+     BUILDHISTORY_COMMIT = "1"
+            </literallayout>
+            Enabling build history causes the build process to collect build
+            output information and commit it to a local 
+            <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
+            <note>
+                Enabling build history increases your build times slightly, 
+                particularly for images, and increases the amount of disk
+                space used during the build.
+            </note> 
+        </para>
+
+        <para>
+            You can disable build history by removing the previous statements
+            from your <filename>conf/local.conf</filename> file.
+            However, you should realize that enabling and disabling 
+            build history in this manner can change the 
+            <filename>do_package</filename> 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.
+        </para>
+
+        <para>
+            To disable the build history functionality without causing the 
+            packaging tasks to be re-run, add just this statement to your 
+            <filename>conf/local.conf</filename> file:               
+            <literallayout class='monospaced'>
+     BUILDHISTORY_FEATURES = ""
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='understanding-what-the-build-history-contains'>
+        <title>Understanding What the Build History Contains</title>
+
+        <para>
+            Build history information is kept in  
+            <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename>
+            in the Build Directory.
+            The following is an example abbreviated listing:
+            <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
+        </para>
+ 
+        <section id='build-history-package-information'>
+            <title>Build History Package Information</title>
+
+            <para>
+                The history for each package contains a text file that has
+                name-value pairs with information about the package. 
+                For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
+                contains the following:
+                <literallayout class='monospaced'>
+     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
+                </literallayout>
+                Most of these name-value pairs corresponds to variables used 
+                to produce the package.
+                The exceptions are <filename>FILELIST</filename>, which is the 
+                actual list of files in the package, and 
+                <filename>PKGSIZE</filename>, which is the total size of files 
+                in the package in bytes.
+            </para>
+
+            <para>
+                There is also a file corresponding to the recipe from which the 
+                package came (e.g.  
+                <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
+                <literallayout class='monospaced'>
+     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
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='build-history-image-information'>
+            <title>Build History Image Information</title>
+
+            <para>
+                The files produced for each image are as follows:
+                <itemizedlist>
+                    <listitem><para><emphasis>build-id:</emphasis>
+                        Human-readable information about the build configuration 
+                        and metadata source revisions.</para></listitem>
+                    <listitem><para><emphasis>*.dot:</emphasis>
+                        Dependency graphs for the image that are 
+                        compatible with <filename>graphviz</filename>.
+                        </para></listitem>
+                    <listitem><para><emphasis>files-in-image.txt:</emphasis>
+                            A list of files in the image with permissions, 
+                        owner, group, size, and symlink information.
+                        </para></listitem>
+                    <listitem><para><emphasis>image-info.txt:</emphasis>
+                        A text file containing name-value pairs with information 
+                        about the image.
+                        See the following listing example for more information.
+                        </para></listitem>
+                    <listitem><para><emphasis>installed-package-names.txt:</emphasis>
+                        A list of installed packages by name only.</para></listitem>
+                    <listitem><para><emphasis>installed-package-sizes.txt:</emphasis>
+                        A list of installed packages ordered by size.
+                        </para></listitem>
+                    <listitem><para><emphasis>installed-packages.txt:</emphasis>
+                        A list of installed packages with fuill package
+                        filenames.</para></listitem>
+                </itemizedlist>
+                <note>
+                    Installed package information is able to be gathered and 
+                    produced even if packaging is disabled for the final image.
+                </note>
+            </para>
+
+            <para>
+                Here is an example of <filename>image-info.txt</filename>:
+                <literallayout class='monospaced'>
+     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
+                </literallayout>
+                Other than <filename>IMAGESIZE</filename>, 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.
+            </para>
+        </section>
+
+        <section id='limiting-build-history-information'>
+            <title>Limiting Build History Information</title>
+
+            <para> 
+                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 <filename>conf/local.conf</filename> file found in the 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                <literallayout class='monospaced'>
+     INHERIT += "buildhistory"
+     BUILDHISTORY_COMMIT = "0"
+     BUILDHISTORY_FEATURES = "image"
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='examining-build-history-information'>
+            <title>Examining Build History Information</title>
+
+            <para>
+                You can examine build history output from the command line or 
+                from a web interface.
+            </para>
+
+            <para>
+                To see any changes that have occurred (assuming you have 
+                <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply 
+                use any Git command that allows you to view the history of 
+                a repository. 
+                Here is one method:
+                <literallayout class='monospaced'>
+      $ git log -p 
+                </literallayout>
+                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).
+            </para>
+
+            <para>
+                A command-line tool called <filename>buildhistory-diff</filename>
+                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:
+                <literallayout class='monospaced'>
+     $ ~/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"
+                </literallayout>
+            </para>
+
+            <para>
+                To see changes to the build history using a web interface, follow    
+                the instruction in the <filename>README</filename> file here.
+                <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
+            </para>
+
+            <para>
+                Here is a sample screenshot of the interface:
+                <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
+            </para>
+        </section>
+    </section>
+</section>
+
 </chapter>
 <!-- 
 vim: expandtab tw=80 ts=4