diff options
Diffstat (limited to 'documentation/ref-manual')
| -rw-r--r-- | documentation/ref-manual/figures/buildhistory-web.png | bin | 49966 -> 0 bytes | |||
| -rw-r--r-- | documentation/ref-manual/figures/buildhistory.png | bin | 44900 -> 0 bytes | |||
| -rw-r--r-- | documentation/ref-manual/migration.xml | 8 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-classes.xml | 4 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-structure.xml | 4 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-variables.xml | 4 | ||||
| -rw-r--r-- | documentation/ref-manual/usingpoky.xml | 502 |
7 files changed, 12 insertions, 510 deletions
diff --git a/documentation/ref-manual/figures/buildhistory-web.png b/documentation/ref-manual/figures/buildhistory-web.png deleted file mode 100644 index f6db86c977..0000000000 --- a/documentation/ref-manual/figures/buildhistory-web.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/ref-manual/figures/buildhistory.png deleted file mode 100644 index bd5f8a4908..0000000000 --- a/documentation/ref-manual/figures/buildhistory.png +++ /dev/null | |||
| 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> | 16 | OLD 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> | 19 | OLD 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> |
