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:
parent
128b6be901
commit
255ca146cc
|
@ -360,6 +360,286 @@
|
||||||
</section>
|
</section>
|
||||||
</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>
|
</chapter>
|
||||||
<!--
|
<!--
|
||||||
vim: expandtab tw=80 ts=4
|
vim: expandtab tw=80 ts=4
|
||||||
|
|
Loading…
Reference in New Issue