summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/Makefile5
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml564
-rw-r--r--documentation/dev-manual/figures/buildhistory-web.png (renamed from documentation/ref-manual/figures/buildhistory-web.png)bin49966 -> 49966 bytes
-rw-r--r--documentation/dev-manual/figures/buildhistory.png (renamed from documentation/ref-manual/figures/buildhistory.png)bin44900 -> 44900 bytes
-rw-r--r--documentation/ref-manual/migration.xml8
-rw-r--r--documentation/ref-manual/ref-classes.xml4
-rw-r--r--documentation/ref-manual/ref-structure.xml4
-rw-r--r--documentation/ref-manual/ref-variables.xml4
-rw-r--r--documentation/ref-manual/usingpoky.xml502
9 files changed, 576 insertions, 515 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index c08d912302..5e166a2ba0 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -146,8 +146,8 @@ TARFILES = dev-style.css dev-manual.html \
146 figures/source-repos.png figures/yp-download.png \ 146 figures/source-repos.png figures/yp-download.png \
147 figures/wip.png 147 figures/wip.png
148 else 148 else
149TARFILES = dev-style.css dev-manual.html \ 149TARFILES = dev-style.css dev-manual.html figures/buildhistory-web.png \
150 figures/dev-title.png \ 150 figures/dev-title.png figures/buildhistory.png \
151 figures/recipe-workflow.png figures/bitbake-build-flow.png \ 151 figures/recipe-workflow.png figures/bitbake-build-flow.png \
152 eclipse 152 eclipse
153 endif 153 endif
@@ -281,7 +281,6 @@ ifeq ($(DOC),ref-manual)
281XSLTOPTS = --xinclude 281XSLTOPTS = --xinclude
282ALLPREQ = html eclipse tarball 282ALLPREQ = html eclipse tarball
283TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ 283TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
284 figures/buildhistory.png figures/buildhistory-web.png \
285 figures/build-workspace-directory.png \ 284 figures/build-workspace-directory.png \
286 eclipse 285 eclipse
287MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse 286MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 13a84b9c22..0c2101fde9 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -7432,8 +7432,8 @@ Some notes from Cal:
7432 BUILDHISTORY_COMMIT = "1" 7432 BUILDHISTORY_COMMIT = "1"
7433 </literallayout> 7433 </literallayout>
7434 For information on build history, see the 7434 For information on build history, see the
7435 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" 7435 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
7436 section in the Yocto Project Reference Manual. 7436 section.
7437 </para> 7437 </para>
7438 7438
7439 <note> 7439 <note>
@@ -9089,6 +9089,566 @@ Some notes from Cal:
9089 </section> 9089 </section>
9090 </section> 9090 </section>
9091 9091
9092
9093
9094
9095 <section id='maintaining-build-output-quality'>
9096 <title>Maintaining Build Output Quality</title>
9097
9098 <para>
9099 Many factors can influence the quality of a build.
9100 For example, if you upgrade a recipe to use a new version of an
9101 upstream software package or you experiment with some new
9102 configuration options, subtle changes can occur that you might
9103 not detect until later.
9104 Consider the case where your recipe is using a newer version of
9105 an upstream package.
9106 In this case, a new version of a piece of software might
9107 introduce an optional dependency on another library, which is
9108 auto-detected.
9109 If that library has already been built when the software is
9110 building, the software will link to the built library and that
9111 library will be pulled into your image along with the new
9112 software even if you did not want the library.
9113 </para>
9114
9115 <para>
9116 The
9117 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink>
9118 class exists to help you maintain the quality of your build
9119 output.
9120 You can use the class to highlight unexpected and possibly
9121 unwanted changes in the build output.
9122 When you enable build history, it records information about the
9123 contents of each package and image and then commits that
9124 information to a local Git repository where you can examine
9125 the information.
9126 </para>
9127
9128 <para>
9129 The remainder of this section describes the following:
9130 <itemizedlist>
9131 <listitem><para>
9132 How you can enable and disable build history
9133 </para></listitem>
9134 <listitem><para>
9135 How to understand what the build history contains
9136 </para></listitem>
9137 <listitem><para>
9138 How to limit the information used for build history
9139 </para></listitem>
9140 <listitem><para>
9141 How to examine the build history from both a
9142 command-line and web interface
9143 </para></listitem>
9144 </itemizedlist>
9145 </para>
9146
9147 <section id='enabling-and-disabling-build-history'>
9148 <title>Enabling and Disabling Build History</title>
9149
9150 <para>
9151 Build history is disabled by default.
9152 To enable it, add the following <filename>INHERIT</filename>
9153 statement and set the
9154 <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></ulink>
9155 variable to "1" at the end of your
9156 <filename>conf/local.conf</filename> file found in the
9157 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
9158 <literallayout class='monospaced'>
9159 INHERIT += "buildhistory"
9160 BUILDHISTORY_COMMIT = "1"
9161 </literallayout>
9162 Enabling build history as previously described causes the
9163 OpenEmbedded build system to collect build output information
9164 and commit it as a single commit to a local
9165 <ulink url='&YOCTO_DOCS_OVERVIEW_URL;#git'>Git</ulink>
9166 repository.
9167 <note>
9168 Enabling build history increases your build times slightly,
9169 particularly for images, and increases the amount of disk
9170 space used during the build.
9171 </note>
9172 </para>
9173
9174 <para>
9175 You can disable build history by removing the previous
9176 statements from your <filename>conf/local.conf</filename>
9177 file.
9178 </para>
9179 </section>
9180
9181 <section id='understanding-what-the-build-history-contains'>
9182 <title>Understanding What the Build History Contains</title>
9183
9184 <para>
9185 Build history information is kept in
9186 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink><filename>}/buildhistory</filename>
9187 in the Build Directory as defined by the
9188 <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></ulink>
9189 variable.
9190 The following is an example abbreviated listing:
9191 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
9192 </para>
9193
9194 <para>
9195 At the top level, a <filename>metadata-revs</filename>
9196 file exists that lists the revisions of the repositories for
9197 the enabled layers when the build was produced.
9198 The rest of the data splits into separate
9199 <filename>packages</filename>, <filename>images</filename>
9200 and <filename>sdk</filename> directories, the contents of
9201 which are described as follows.
9202 </para>
9203
9204 <section id='build-history-package-information'>
9205 <title>Build History Package Information</title>
9206
9207 <para>
9208 The history for each package contains a text file that has
9209 name-value pairs with information about the package.
9210 For example,
9211 <filename>buildhistory/packages/i586-poky-linux/busybox/busybox/latest</filename>
9212 contains the following:
9213 <literallayout class='monospaced'>
9214 PV = 1.22.1
9215 PR = r32
9216 RPROVIDES =
9217 RDEPENDS = glibc (>= 2.20) update-alternatives-opkg
9218 RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d
9219 PKGSIZE = 540168
9220 FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \
9221 /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \
9222 /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \
9223 /usr/share/pixmaps /usr/share/applications /usr/share/idl \
9224 /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
9225 FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \
9226 /etc/busybox.links.nosuid /etc/busybox.links.suid
9227 </literallayout>
9228 Most of these name-value pairs correspond to variables
9229 used to produce the package.
9230 The exceptions are <filename>FILELIST</filename>, which
9231 is the actual list of files in the package, and
9232 <filename>PKGSIZE</filename>, which is the total size of
9233 files in the package in bytes.
9234 </para>
9235
9236 <para>
9237 A file also exists that corresponds to the recipe from
9238 which the package came (e.g.
9239 <filename>buildhistory/packages/i586-poky-linux/busybox/latest</filename>):
9240 <literallayout class='monospaced'>
9241 PV = 1.22.1
9242 PR = r32
9243 DEPENDS = initscripts kern-tools-native update-rc.d-native \
9244 virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \
9245 virtual/libc virtual/update-alternatives
9246 PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \
9247 busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \
9248 busybox-staticdev busybox-dev busybox-doc busybox-locale busybox
9249 </literallayout>
9250 </para>
9251
9252 <para>
9253 Finally, for those recipes fetched from a version control
9254 system (e.g., Git), a file exists that lists source
9255 revisions that are specified in the recipe and lists
9256 the actual revisions used during the build.
9257 Listed and actual revisions might differ when
9258 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
9259 is set to
9260 ${<ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink>}.
9261 Here is an example assuming
9262 <filename>buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev</filename>):
9263 <literallayout class='monospaced'>
9264 # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
9265 SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
9266 # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
9267 SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
9268 </literallayout>
9269 You can use the
9270 <filename>buildhistory-collect-srcrevs</filename>
9271 command with the <filename>-a</filename> option to
9272 collect the stored <filename>SRCREV</filename> values
9273 from build history and report them in a format suitable for
9274 use in global configuration (e.g.,
9275 <filename>local.conf</filename> or a distro include file)
9276 to override floating <filename>AUTOREV</filename> values
9277 to a fixed set of revisions.
9278 Here is some example output from this command:
9279 <literallayout class='monospaced'>
9280 $ buildhistory-collect-srcrevs -a
9281 # i586-poky-linux
9282 SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072"
9283 SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072"
9284 SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a"
9285 SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
9286 # x86_64-linux
9287 SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa"
9288 SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf"
9289 SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11"
9290 SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072"
9291 SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3"
9292 SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca"
9293 SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a"
9294 SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff"
9295 SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
9296 # qemux86-poky-linux
9297 SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
9298 SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f"
9299 # all-poky-linux
9300 SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11"
9301 </literallayout>
9302 <note>
9303 Here are some notes on using the
9304 <filename>buildhistory-collect-srcrevs</filename>
9305 command:
9306 <itemizedlist>
9307 <listitem><para>
9308 By default, only values where the
9309 <filename>SRCREV</filename> was not hardcoded
9310 (usually when <filename>AUTOREV</filename>
9311 is used) are reported.
9312 Use the <filename>-a</filename> option to
9313 see all <filename>SRCREV</filename> values.
9314 </para></listitem>
9315 <listitem><para>
9316 The output statements might not have any effect
9317 if overrides are applied elsewhere in the
9318 build system configuration.
9319 Use the <filename>-f</filename> option to add
9320 the <filename>forcevariable</filename> override
9321 to each output line if you need to work around
9322 this restriction.
9323 </para></listitem>
9324 <listitem><para>
9325 The script does apply special handling when
9326 building for multiple machines.
9327 However, the script does place a comment before
9328 each set of values that specifies which
9329 triplet to which they belong as previously
9330 shown (e.g.,
9331 <filename>i586-poky-linux</filename>).
9332 </para></listitem>
9333 </itemizedlist>
9334 </note>
9335 </para>
9336 </section>
9337
9338 <section id='build-history-image-information'>
9339 <title>Build History Image Information</title>
9340
9341 <para>
9342 The files produced for each image are as follows:
9343 <itemizedlist>
9344 <listitem><para>
9345 <filename>image-files:</filename>
9346 A directory containing selected files from the root
9347 filesystem.
9348 The files are defined by
9349 <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></ulink>.
9350 </para></listitem>
9351 <listitem><para>
9352 <filename>build-id.txt:</filename>
9353 Human-readable information about the build
9354 configuration and metadata source revisions.
9355 This file contains the full build header as printed
9356 by BitBake.
9357 </para></listitem>
9358 <listitem><para>
9359 <filename>*.dot:</filename>
9360 Dependency graphs for the image that are
9361 compatible with <filename>graphviz</filename>.
9362 </para></listitem>
9363 <listitem><para>
9364 <filename>files-in-image.txt:</filename>
9365 A list of files in the image with permissions,
9366 owner, group, size, and symlink information.
9367 </para></listitem>
9368 <listitem><para>
9369 <filename>image-info.txt:</filename>
9370 A text file containing name-value pairs with
9371 information about the image.
9372 See the following listing example for more
9373 information.
9374 </para></listitem>
9375 <listitem><para>
9376 <filename>installed-package-names.txt:</filename>
9377 A list of installed packages by name only.
9378 </para></listitem>
9379 <listitem><para>
9380 <filename>installed-package-sizes.txt:</filename>
9381 A list of installed packages ordered by size.
9382 </para></listitem>
9383 <listitem><para>
9384 <filename>installed-packages.txt:</filename>
9385 A list of installed packages with full package
9386 filenames.
9387 </para></listitem>
9388 </itemizedlist>
9389 <note>
9390 Installed package information is able to be gathered
9391 and produced even if package management is disabled
9392 for the final image.
9393 </note>
9394 </para>
9395
9396 <para>
9397 Here is an example of <filename>image-info.txt</filename>:
9398 <literallayout class='monospaced'>
9399 DISTRO = poky
9400 DISTRO_VERSION = 1.7
9401 USER_CLASSES = buildstats image-mklibs image-prelink
9402 IMAGE_CLASSES = image_types
9403 IMAGE_FEATURES = debug-tweaks
9404 IMAGE_LINGUAS =
9405 IMAGE_INSTALL = packagegroup-core-boot run-postinsts
9406 BAD_RECOMMENDATIONS =
9407 NO_RECOMMENDATIONS =
9408 PACKAGE_EXCLUDE =
9409 ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \
9410 write_image_manifest ; buildhistory_list_installed_image ; \
9411 buildhistory_get_image_installed ; ssh_allow_empty_password; \
9412 postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ;
9413 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
9414 IMAGESIZE = 6900
9415 </literallayout>
9416 Other than <filename>IMAGESIZE</filename>, which is the
9417 total size of the files in the image in Kbytes, the
9418 name-value pairs are variables that may have influenced the
9419 content of the image.
9420 This information is often useful when you are trying to
9421 determine why a change in the package or file
9422 listings has occurred.
9423 </para>
9424 </section>
9425
9426 <section id='using-build-history-to-gather-image-information-only'>
9427 <title>Using Build History to Gather Image Information Only</title>
9428
9429 <para>
9430 As you can see, build history produces image information,
9431 including dependency graphs, so you can see why something
9432 was pulled into the image.
9433 If you are just interested in this information and not
9434 interested in collecting specific package or SDK
9435 information, you can enable writing only image information
9436 without any history by adding the following to your
9437 <filename>conf/local.conf</filename> file found in the
9438 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
9439 <literallayout class='monospaced'>
9440 INHERIT += "buildhistory"
9441 BUILDHISTORY_COMMIT = "0"
9442 BUILDHISTORY_FEATURES = "image"
9443 </literallayout>
9444 Here, you set the
9445 <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></ulink>
9446 variable to use the image feature only.
9447 </para>
9448 </section>
9449
9450 <section id='build-history-sdk-information'>
9451 <title>Build History SDK Information</title>
9452
9453 <para>
9454 Build history collects similar information on the contents
9455 of SDKs
9456 (e.g. <filename>bitbake -c populate_sdk imagename</filename>)
9457 as compared to information it collects for images.
9458 Furthermore, this information differs depending on whether
9459 an extensible or standard SDK is being produced.
9460 </para>
9461
9462 <para>
9463 The following list shows the files produced for SDKs:
9464 <itemizedlist>
9465 <listitem><para>
9466 <filename>files-in-sdk.txt:</filename>
9467 A list of files in the SDK with permissions,
9468 owner, group, size, and symlink information.
9469 This list includes both the host and target parts
9470 of the SDK.
9471 </para></listitem>
9472 <listitem><para>
9473 <filename>sdk-info.txt:</filename>
9474 A text file containing name-value pairs with
9475 information about the SDK.
9476 See the following listing example for more
9477 information.
9478 </para></listitem>
9479 <listitem><para>
9480 <filename>sstate-task-sizes.txt:</filename>
9481 A text file containing name-value pairs with
9482 information about task group sizes
9483 (e.g. <filename>do_populate_sysroot</filename>
9484 tasks have a total size).
9485 The <filename>sstate-task-sizes.txt</filename> file
9486 exists only when an extensible SDK is created.
9487 </para></listitem>
9488 <listitem><para>
9489 <filename>sstate-package-sizes.txt:</filename>
9490 A text file containing name-value pairs with
9491 information for the shared-state packages and
9492 sizes in the SDK.
9493 The <filename>sstate-package-sizes.txt</filename>
9494 file exists only when an extensible SDK is created.
9495 </para></listitem>
9496 <listitem><para>
9497 <filename>sdk-files:</filename>
9498 A folder that contains copies of the files
9499 mentioned in
9500 <filename>BUILDHISTORY_SDK_FILES</filename> if the
9501 files are present in the output.
9502 Additionally, the default value of
9503 <filename>BUILDHISTORY_SDK_FILES</filename> is
9504 specific to the extensible SDK although you can
9505 set it differently if you would like to pull in
9506 specific files from the standard SDK.</para>
9507
9508 <para>The default files are
9509 <filename>conf/local.conf</filename>,
9510 <filename>conf/bblayers.conf</filename>,
9511 <filename>conf/auto.conf</filename>,
9512 <filename>conf/locked-sigs.inc</filename>, and
9513 <filename>conf/devtool.conf</filename>.
9514 Thus, for an extensible SDK, these files get
9515 copied into the <filename>sdk-files</filename>
9516 directory.
9517 </para></listitem>
9518 <listitem><para>
9519 The following information appears under
9520 each of the <filename>host</filename>
9521 and <filename>target</filename> directories
9522 for the portions of the SDK that run on the host
9523 and on the target, respectively:
9524 <note>
9525 The following files for the most part are empty
9526 when producing an extensible SDK because this
9527 type of SDK is not constructed from packages
9528 as is the standard SDK.
9529 </note>
9530 <itemizedlist>
9531 <listitem><para>
9532 <filename>depends.dot:</filename>
9533 Dependency graph for the SDK that is
9534 compatible with
9535 <filename>graphviz</filename>.
9536 </para></listitem>
9537 <listitem><para>
9538 <filename>installed-package-names.txt:</filename>
9539 A list of installed packages by name only.
9540 </para></listitem>
9541 <listitem><para>
9542 <filename>installed-package-sizes.txt:</filename>
9543 A list of installed packages ordered by size.
9544 </para></listitem>
9545 <listitem><para>
9546 <filename>installed-packages.txt:</filename>
9547 A list of installed packages with full
9548 package filenames.
9549 </para></listitem>
9550 </itemizedlist>
9551 </para></listitem>
9552 </itemizedlist>
9553 </para>
9554
9555 <para>
9556 Here is an example of <filename>sdk-info.txt</filename>:
9557 <literallayout class='monospaced'>
9558 DISTRO = poky
9559 DISTRO_VERSION = 1.3+snapshot-20130327
9560 SDK_NAME = poky-glibc-i686-arm
9561 SDK_VERSION = 1.3+snapshot
9562 SDKMACHINE =
9563 SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
9564 BAD_RECOMMENDATIONS =
9565 SDKSIZE = 352712
9566 </literallayout>
9567 Other than <filename>SDKSIZE</filename>, which is the
9568 total size of the files in the SDK in Kbytes, the
9569 name-value pairs are variables that might have influenced
9570 the content of the SDK.
9571 This information is often useful when you are trying to
9572 determine why a change in the package or file listings
9573 has occurred.
9574 </para>
9575 </section>
9576
9577 <section id='examining-build-history-information'>
9578 <title>Examining Build History Information</title>
9579
9580 <para>
9581 You can examine build history output from the command
9582 line or from a web interface.
9583 </para>
9584
9585 <para>
9586 To see any changes that have occurred (assuming you have
9587 <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></ulink><filename>&nbsp;= "1"</filename>),
9588 you can simply use any Git command that allows you to
9589 view the history of a repository.
9590 Here is one method:
9591 <literallayout class='monospaced'>
9592 $ git log -p
9593 </literallayout>
9594 You need to realize, however, that this method does show
9595 changes that are not significant (e.g. a package's size
9596 changing by a few bytes).
9597 </para>
9598
9599 <para>
9600 A command-line tool called
9601 <filename>buildhistory-diff</filename> does exist, though,
9602 that queries the Git repository and prints just the
9603 differences that might be significant in human-readable
9604 form.
9605 Here is an example:
9606 <literallayout class='monospaced'>
9607 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
9608 Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt):
9609 /etc/anotherpkg.conf was added
9610 /sbin/anotherpkg was added
9611 * (installed-package-names.txt):
9612 * anotherpkg was added
9613 Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt):
9614 anotherpkg was added
9615 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
9616 * PR changed from "r0" to "r1"
9617 * PV changed from "0.1.10" to "0.1.12"
9618 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
9619 * PR changed from "r0" to "r1"
9620 * PV changed from "0.1.10" to "0.1.12"
9621 </literallayout>
9622 <note>
9623 The <filename>buildhistory-diff</filename> tool
9624 requires the <filename>GitPython</filename> package.
9625 Be sure to install it using Pip3 as follows:
9626 <literallayout class='monospaced'>
9627 $ pip3 install GitPython --user
9628 </literallayout>
9629 Alternatively, you can install
9630 <filename>python3-git</filename> using the appropriate
9631 distribution package manager (e.g.
9632 <filename>apt-get</filename>, <filename>dnf</filename>,
9633 or <filename>zipper</filename>).
9634 </note>
9635 </para>
9636
9637 <para>
9638 To see changes to the build history using a web interface,
9639 follow the instruction in the <filename>README</filename>
9640 file here.
9641 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
9642 </para>
9643
9644 <para>
9645 Here is a sample screenshot of the interface:
9646 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
9647 </para>
9648 </section>
9649 </section>
9650 </section>
9651
9092 <section id="performing-automated-runtime-testing"> 9652 <section id="performing-automated-runtime-testing">
9093 <title>Performing Automated Runtime Testing</title> 9653 <title>Performing Automated Runtime Testing</title>
9094 9654
diff --git a/documentation/ref-manual/figures/buildhistory-web.png b/documentation/dev-manual/figures/buildhistory-web.png
index f6db86c977..f6db86c977 100644
--- a/documentation/ref-manual/figures/buildhistory-web.png
+++ b/documentation/dev-manual/figures/buildhistory-web.png
Binary files differ
diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/dev-manual/figures/buildhistory.png
index bd5f8a4908..bd5f8a4908 100644
--- a/documentation/ref-manual/figures/buildhistory.png
+++ b/documentation/dev-manual/figures/buildhistory.png
Binary files differ
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 8a6b8a18fc..01c5a982e2 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -1022,8 +1022,8 @@
1022 </para></listitem> 1022 </para></listitem>
1023 </itemizedlist> 1023 </itemizedlist>
1024 For more information on Build History, see the 1024 For more information on Build History, see the
1025 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" 1025 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1026 section. 1026 section in the Yocto Project Development Tasks Manual.
1027 </para> 1027 </para>
1028 </section> 1028 </section>
1029 1029
@@ -2026,8 +2026,8 @@
2026 You should manually remove old "build-id" files from your 2026 You should manually remove old "build-id" files from your
2027 existing build history repositories to avoid confusion. 2027 existing build history repositories to avoid confusion.
2028 For information on the build history feature, see the 2028 For information on the build history feature, see the
2029 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" 2029 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
2030 section. 2030 section in the Yocto Project Development Tasks Manual.
2031 </para></listitem> 2031 </para></listitem>
2032 </itemizedlist> 2032 </itemizedlist>
2033 </para> 2033 </para>
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index eabb60fe03..3b7ac31e6a 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -357,8 +357,8 @@
357 history of build output metadata, which can be used to detect possible 357 history of build output metadata, which can be used to detect possible
358 regressions as well as used for analysis of the build output. 358 regressions as well as used for analysis of the build output.
359 For more information on using Build History, see the 359 For more information on using Build History, see the
360 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" 360 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
361 section. 361 section in the Yocto Project Development Tasks Manual.
362 </para> 362 </para>
363</section> 363</section>
364 364
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index ad8f24efd7..7a2371d8b3 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -306,8 +306,8 @@
306 The directory tracks build information into image, packages, and 306 The directory tracks build information into image, packages, and
307 SDK subdirectories. 307 SDK subdirectories.
308 For information on the build history feature, see the 308 For information on the build history feature, see the
309 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" 309 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
310 section. 310 section in the Yocto Project Development Tasks Manual.
311 </para> 311 </para>
312 </section> 312 </section>
313 313
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index fa4724984f..c784bd7424 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1923,8 +1923,8 @@
1923 class, this variable specifies the build history features 1923 class, this variable specifies the build history features
1924 to be enabled. 1924 to be enabled.
1925 For more information on how build history works, see the 1925 For more information on how build history works, see the
1926 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" 1926 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1927 section. 1927 section in the Yocto Project Development Tasks Manual.
1928 </para> 1928 </para>
1929 1929
1930 <para> 1930 <para>
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index e379459a20..e6b71b1565 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -11,511 +11,13 @@
11 documentation set provide more details on how to use the Yocto Project. 11 documentation set provide more details on how to use the Yocto Project.
12 </para> 12 </para>
13 13
14<section id='maintaining-build-output-quality'>
15 <title>Maintaining Build Output Quality</title>
16 14
17 <para>
18 Many factors can influence the quality of a build.
19 For example, if you upgrade a recipe to use a new version of an upstream software
20 package or you experiment with some new configuration options, subtle changes
21 can occur that you might not detect until later.
22 Consider the case where your recipe is using a newer version of an upstream package.
23 In this case, a new version of a piece of software might introduce an optional
24 dependency on another library, which is auto-detected.
25 If that library has already been built when the software is building,
26 the software will link to the built library and that library will be pulled
27 into your image along with the new software even if you did not want the
28 library.
29 </para>
30
31 <para>
32 The
33 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
34 class exists to help you maintain
35 the quality of your build output.
36 You can use the class to highlight unexpected and possibly unwanted
37 changes in the build output.
38 When you enable build history, it records information about the contents of
39 each package and image and then commits that information to a local Git
40 repository where you can examine the information.
41 </para>
42 15
43 <para> 16OLD START WAS HERE.
44 The remainder of this section describes the following:
45 <itemizedlist>
46 <listitem><para>How you can enable and disable
47 build history</para></listitem>
48 <listitem><para>How to understand what the build history contains
49 </para></listitem>
50 <listitem><para>How to limit the information used for build history
51 </para></listitem>
52 <listitem><para>How to examine the build history from both a
53 command-line and web interface</para></listitem>
54 </itemizedlist>
55 </para>
56 17
57 <section id='enabling-and-disabling-build-history'>
58 <title>Enabling and Disabling Build History</title>
59 18
60 <para> 19OLD END WAS HERE.
61 Build history is disabled by default.
62 To enable it, add the following <filename>INHERIT</filename>
63 statement and set the
64 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
65 variable to "1" at the end of your
66 <filename>conf/local.conf</filename> file found in the
67 <link linkend='build-directory'>Build Directory</link>:
68 <literallayout class='monospaced'>
69 INHERIT += "buildhistory"
70 BUILDHISTORY_COMMIT = "1"
71 </literallayout>
72 Enabling build history as previously described causes the
73 OpenEmbedded build system to collect build output information and
74 commit it as a single commit to a local
75 <ulink url='&YOCTO_DOCS_OVERVIEW_URL;#git'>Git</ulink> repository.
76 <note>
77 Enabling build history increases your build times slightly,
78 particularly for images, and increases the amount of disk
79 space used during the build.
80 </note>
81 </para>
82 20
83 <para>
84 You can disable build history by removing the previous statements
85 from your <filename>conf/local.conf</filename> file.
86 </para>
87 </section>
88
89 <section id='understanding-what-the-build-history-contains'>
90 <title>Understanding What the Build History Contains</title>
91
92 <para>
93 Build history information is kept in
94 <filename>${</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>}/buildhistory</filename>
95 in the Build Directory as defined by the
96 <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link>
97 variable.
98 The following is an example abbreviated listing:
99 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
100 </para>
101
102 <para>
103 At the top level, there is a <filename>metadata-revs</filename> file
104 that lists the revisions of the repositories for the layers enabled
105 when the build was produced.
106 The rest of the data splits into separate
107 <filename>packages</filename>, <filename>images</filename> and
108 <filename>sdk</filename> directories, the contents of which are
109 described below.
110 </para>
111
112 <section id='build-history-package-information'>
113 <title>Build History Package Information</title>
114
115 <para>
116 The history for each package contains a text file that has
117 name-value pairs with information about the package.
118 For example, <filename>buildhistory/packages/i586-poky-linux/busybox/busybox/latest</filename>
119 contains the following:
120 <literallayout class='monospaced'>
121 PV = 1.22.1
122 PR = r32
123 RPROVIDES =
124 RDEPENDS = glibc (>= 2.20) update-alternatives-opkg
125 RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d
126 PKGSIZE = 540168
127 FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \
128 /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \
129 /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \
130 /usr/share/pixmaps /usr/share/applications /usr/share/idl \
131 /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
132 FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \
133 /etc/busybox.links.nosuid /etc/busybox.links.suid
134 </literallayout>
135 Most of these name-value pairs correspond to variables used
136 to produce the package.
137 The exceptions are <filename>FILELIST</filename>, which is the
138 actual list of files in the package, and
139 <filename>PKGSIZE</filename>, which is the total size of files
140 in the package in bytes.
141 </para>
142
143 <para>
144 There is also a file corresponding to the recipe from which the
145 package came (e.g.
146 <filename>buildhistory/packages/i586-poky-linux/busybox/latest</filename>):
147 <literallayout class='monospaced'>
148 PV = 1.22.1
149 PR = r32
150 DEPENDS = initscripts kern-tools-native update-rc.d-native \
151 virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \
152 virtual/libc virtual/update-alternatives
153 PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \
154 busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \
155 busybox-staticdev busybox-dev busybox-doc busybox-locale busybox
156 </literallayout>
157 </para>
158
159 <para>
160 Finally, for those recipes fetched from a version control
161 system (e.g., Git), a file exists that lists source revisions
162 that are specified in the recipe and lists the actual revisions
163 used during the build.
164 Listed and actual revisions might differ when
165 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
166 is set to
167 <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>.
168 Here is an example assuming
169 <filename>buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev</filename>):
170 <literallayout class='monospaced'>
171 # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
172 SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
173 # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
174 SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
175 </literallayout>
176 You can use the <filename>buildhistory-collect-srcrevs</filename>
177 command with the <filename>-a</filename> option to
178 collect the stored <filename>SRCREV</filename> values
179 from build history and report them in a format suitable for
180 use in global configuration (e.g.,
181 <filename>local.conf</filename> or a distro include file) to
182 override floating <filename>AUTOREV</filename> values to a
183 fixed set of revisions.
184 Here is some example output from this command:
185 <literallayout class='monospaced'>
186 $ buildhistory-collect-srcrevs -a
187 # i586-poky-linux
188 SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072"
189 SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072"
190 SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a"
191 SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
192 # x86_64-linux
193 SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa"
194 SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf"
195 SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11"
196 SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072"
197 SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3"
198 SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca"
199 SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a"
200 SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff"
201 SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
202 # qemux86-poky-linux
203 SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
204 SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f"
205 # all-poky-linux
206 SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11"
207 </literallayout>
208 <note>
209 Here are some notes on using the
210 <filename>buildhistory-collect-srcrevs</filename> command:
211 <itemizedlist>
212 <listitem><para>By default, only values where the
213 <filename>SRCREV</filename> was
214 not hardcoded (usually when <filename>AUTOREV</filename>
215 was used) are reported.
216 Use the <filename>-a</filename> option to see all
217 <filename>SRCREV</filename> values.
218 </para></listitem>
219 <listitem><para>The output statements might not have any effect
220 if overrides are applied elsewhere in the build system
221 configuration.
222 Use the <filename>-f</filename> option to add the
223 <filename>forcevariable</filename> override to each output line
224 if you need to work around this restriction.
225 </para></listitem>
226 <listitem><para>The script does apply special handling when
227 building for multiple machines.
228 However, the script does place a
229 comment before each set of values that specifies
230 which triplet to which they belong as shown above
231 (e.g., <filename>i586-poky-linux</filename>).
232 </para></listitem>
233 </itemizedlist>
234 </note>
235 </para>
236 </section>
237
238 <section id='build-history-image-information'>
239 <title>Build History Image Information</title>
240
241 <para>
242 The files produced for each image are as follows:
243 <itemizedlist>
244 <listitem><para><filename>image-files:</filename>
245 A directory containing selected files from the root
246 filesystem.
247 The files are defined by
248 <link linkend='var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></link>.
249 </para></listitem>
250 <listitem><para><filename>build-id.txt:</filename>
251 Human-readable information about the build configuration
252 and metadata source revisions.
253 This file contains the full build header as printed
254 by BitBake.</para></listitem>
255 <listitem><para><filename>*.dot:</filename>
256 Dependency graphs for the image that are
257 compatible with <filename>graphviz</filename>.
258 </para></listitem>
259 <listitem><para><filename>files-in-image.txt:</filename>
260 A list of files in the image with permissions,
261 owner, group, size, and symlink information.
262 </para></listitem>
263 <listitem><para><filename>image-info.txt:</filename>
264 A text file containing name-value pairs with information
265 about the image.
266 See the following listing example for more information.
267 </para></listitem>
268 <listitem><para><filename>installed-package-names.txt:</filename>
269 A list of installed packages by name only.</para></listitem>
270 <listitem><para><filename>installed-package-sizes.txt:</filename>
271 A list of installed packages ordered by size.
272 </para></listitem>
273 <listitem><para><filename>installed-packages.txt:</filename>
274 A list of installed packages with full package
275 filenames.</para></listitem>
276 </itemizedlist>
277 <note>
278 Installed package information is able to be gathered and
279 produced even if package management is disabled for the final
280 image.
281 </note>
282 </para>
283
284 <para>
285 Here is an example of <filename>image-info.txt</filename>:
286 <literallayout class='monospaced'>
287 DISTRO = poky
288 DISTRO_VERSION = 1.7
289 USER_CLASSES = buildstats image-mklibs image-prelink
290 IMAGE_CLASSES = image_types
291 IMAGE_FEATURES = debug-tweaks
292 IMAGE_LINGUAS =
293 IMAGE_INSTALL = packagegroup-core-boot run-postinsts
294 BAD_RECOMMENDATIONS =
295 NO_RECOMMENDATIONS =
296 PACKAGE_EXCLUDE =
297 ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \
298 write_image_manifest ; buildhistory_list_installed_image ; \
299 buildhistory_get_image_installed ; ssh_allow_empty_password; \
300 postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ;
301 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
302 IMAGESIZE = 6900
303 </literallayout>
304 Other than <filename>IMAGESIZE</filename>, which is the
305 total size of the files in the image in Kbytes, the
306 name-value pairs are variables that may have influenced the
307 content of the image.
308 This information is often useful when you are trying to determine
309 why a change in the package or file listings has occurred.
310 </para>
311 </section>
312
313 <section id='using-build-history-to-gather-image-information-only'>
314 <title>Using Build History to Gather Image Information Only</title>
315
316 <para>
317 As you can see, build history produces image information,
318 including dependency graphs, so you can see why something
319 was pulled into the image.
320 If you are just interested in this information and not
321 interested in collecting specific package or SDK information,
322 you can enable writing only image information without
323 any history by adding the following to your
324 <filename>conf/local.conf</filename> file found in the
325 <link linkend='build-directory'>Build Directory</link>:
326 <literallayout class='monospaced'>
327 INHERIT += "buildhistory"
328 BUILDHISTORY_COMMIT = "0"
329 BUILDHISTORY_FEATURES = "image"
330 </literallayout>
331 Here, you set the
332 <link linkend='var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></link>
333 variable to use the image feature only.
334 </para>
335 </section>
336
337 <section id='build-history-sdk-information'>
338 <title>Build History SDK Information</title>
339
340 <para>
341 Build history collects similar information on the contents
342 of SDKs
343 (e.g. <filename>bitbake -c populate_sdk imagename</filename>)
344 as compared to information it collects for images.
345 Furthermore, this information differs depending on whether an
346 extensible or standard SDK is being produced.
347 </para>
348
349 <para>
350 The following list shows the files produced for SDKs:
351 <itemizedlist>
352 <listitem><para><filename>files-in-sdk.txt:</filename>
353 A list of files in the SDK with permissions,
354 owner, group, size, and symlink information.
355 This list includes both the host and target parts
356 of the SDK.
357 </para></listitem>
358 <listitem><para><filename>sdk-info.txt:</filename>
359 A text file containing name-value pairs with information
360 about the SDK.
361 See the following listing example for more information.
362 </para></listitem>
363 <listitem><para><filename>sstate-task-sizes.txt:</filename>
364 A text file containing name-value pairs with information
365 about task group sizes
366 (e.g. <filename>do_populate_sysroot</filename> tasks
367 have a total size).
368 The <filename>sstate-task-sizes.txt</filename> file
369 exists only when an extensible SDK is created.
370 </para></listitem>
371 <listitem><para><filename>sstate-package-sizes.txt:</filename>
372 A text file containing name-value pairs with information
373 for the shared-state packages and sizes in the SDK.
374 The <filename>sstate-package-sizes.txt</filename> file
375 exists only when an extensible SDK is created.
376 </para></listitem>
377 <listitem><para><filename>sdk-files:</filename>
378 A folder that contains copies of the files mentioned in
379 <filename>BUILDHISTORY_SDK_FILES</filename> if the
380 files are present in the output.
381 Additionally, the default value of
382 <filename>BUILDHISTORY_SDK_FILES</filename> is specific
383 to the extensible SDK although you can set it
384 differently if you would like to pull in specific files
385 from the standard SDK.</para>
386 <para>The default files are
387 <filename>conf/local.conf</filename>,
388 <filename>conf/bblayers.conf</filename>,
389 <filename>conf/auto.conf</filename>,
390 <filename>conf/locked-sigs.inc</filename>, and
391 <filename>conf/devtool.conf</filename>.
392 Thus, for an extensible SDK, these files get copied
393 into the <filename>sdk-files</filename> directory.
394 </para></listitem>
395 <listitem><para>The following information appears under
396 each of the <filename>host</filename>
397 and <filename>target</filename> directories
398 for the portions of the SDK that run on the host and
399 on the target, respectively:
400 <note>
401 The following files for the most part are empty
402 when producing an extensible SDK because this
403 type of SDK is not constructed from packages as is
404 the standard SDK.
405 </note>
406 <itemizedlist>
407 <listitem><para><filename>depends.dot:</filename>
408 Dependency graph for the SDK that is
409 compatible with <filename>graphviz</filename>.
410 </para></listitem>
411 <listitem><para><filename>installed-package-names.txt:</filename>
412 A list of installed packages by name only.
413 </para></listitem>
414 <listitem><para><filename>installed-package-sizes.txt:</filename>
415 A list of installed packages ordered by size.
416 </para></listitem>
417 <listitem><para><filename>installed-packages.txt:</filename>
418 A list of installed packages with full package
419 filenames.</para></listitem>
420 </itemizedlist>
421 </para></listitem>
422 </itemizedlist>
423 </para>
424
425 <para>
426 Here is an example of <filename>sdk-info.txt</filename>:
427 <literallayout class='monospaced'>
428 DISTRO = poky
429 DISTRO_VERSION = 1.3+snapshot-20130327
430 SDK_NAME = poky-glibc-i686-arm
431 SDK_VERSION = 1.3+snapshot
432 SDKMACHINE =
433 SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
434 BAD_RECOMMENDATIONS =
435 SDKSIZE = 352712
436 </literallayout>
437 Other than <filename>SDKSIZE</filename>, which is the
438 total size of the files in the SDK in Kbytes, the
439 name-value pairs are variables that might have influenced the
440 content of the SDK.
441 This information is often useful when you are trying to
442 determine why a change in the package or file listings
443 has occurred.
444 </para>
445 </section>
446
447 <section id='examining-build-history-information'>
448 <title>Examining Build History Information</title>
449
450 <para>
451 You can examine build history output from the command line or
452 from a web interface.
453 </para>
454
455 <para>
456 To see any changes that have occurred (assuming you have
457 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT = "1"</filename></link>),
458 you can simply
459 use any Git command that allows you to view the history of
460 a repository.
461 Here is one method:
462 <literallayout class='monospaced'>
463 $ git log -p
464 </literallayout>
465 You need to realize, however, that this method does show
466 changes that are not significant (e.g. a package's size
467 changing by a few bytes).
468 </para>
469
470 <para>
471 A command-line tool called <filename>buildhistory-diff</filename>
472 does exist, though, that queries the Git repository and prints just
473 the differences that might be significant in human-readable form.
474 Here is an example:
475 <literallayout class='monospaced'>
476 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
477 Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt):
478 /etc/anotherpkg.conf was added
479 /sbin/anotherpkg was added
480 * (installed-package-names.txt):
481 * anotherpkg was added
482 Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt):
483 anotherpkg was added
484 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
485 * PR changed from "r0" to "r1"
486 * PV changed from "0.1.10" to "0.1.12"
487 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
488 * PR changed from "r0" to "r1"
489 * PV changed from "0.1.10" to "0.1.12"
490 </literallayout>
491 <note>
492 The <filename>buildhistory-diff</filename> tool requires
493 the <filename>GitPython</filename> package.
494 Be sure to install it using Pip3 as follows:
495 <literallayout class='monospaced'>
496 $ pip3 install GitPython --user
497 </literallayout>
498 Alternatively, you can install
499 <filename>python3-git</filename> using the appropriate
500 distribution package manager (e.g.
501 <filename>apt-get</filename>, <filename>dnf</filename>, or
502 <filename>zipper</filename>).
503 </note>
504 </para>
505
506 <para>
507 To see changes to the build history using a web interface, follow
508 the instruction in the <filename>README</filename> file here.
509 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
510 </para>
511
512 <para>
513 Here is a sample screenshot of the interface:
514 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
515 </para>
516 </section>
517 </section>
518</section>
519 21
520<section id='speeding-up-the-build'> 22<section id='speeding-up-the-build'>
521 <title>Speeding Up the Build</title> 23 <title>Speeding Up the Build</title>