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> |