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>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
128b6be901
commit
255ca146cc
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue