summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual/usingpoky.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-07 17:29:51 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-12-11 16:17:56 +0000
commit73ffb8298b545a1a1fb96bc5952b7365c4c43bfd (patch)
tree9c6473cb4e3c5dd8370c2d417c304e1a302fa643 /documentation/poky-ref-manual/usingpoky.xml
parentacb3f72afaa28ba5d23ca6e5cdf9f1162ea656a3 (diff)
downloadpoky-73ffb8298b545a1a1fb96bc5952b7365c4c43bfd.tar.gz
Documentation: poky-ref-manual - Removed all trailing whitespace.
(From yocto-docs rev: 564a28c2501034ea7e2eb16afc43dfaf931b6f6f) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/poky-ref-manual/usingpoky.xml')
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml264
1 files changed, 132 insertions, 132 deletions
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index e5b5edb846..286b5fa783 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -17,8 +17,8 @@
17 <para> 17 <para>
18 This section provides a summary of the build process and provides information 18 This section provides a summary of the build process and provides information
19 for less obvious aspects of the build process. 19 for less obvious aspects of the build process.
20 For general information on how to build an image using the OpenEmbedded build 20 For general information on how to build an image using the OpenEmbedded build
21 system, see the 21 system, see the
22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
23 section of the Yocto Project Quick Start. 23 section of the Yocto Project Quick Start.
24 </para> 24 </para>
@@ -35,12 +35,12 @@
35 </para> 35 </para>
36 36
37 <para> 37 <para>
38 The <filename>build_dir</filename> is optional and specifies the directory the 38 The <filename>build_dir</filename> is optional and specifies the directory the
39 OpenEmbedded build system uses for the build - 39 OpenEmbedded build system uses for the build -
40 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 40 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
41 If you do not specify a Build Directory it defaults to <filename>build</filename> 41 If you do not specify a Build Directory it defaults to <filename>build</filename>
42 in your current working directory. 42 in your current working directory.
43 A common practice is to use a different Build Directory for different targets. 43 A common practice is to use a different Build Directory for different targets.
44 For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename> 44 For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
45 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target. 45 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
46 See <link linkend="structure-core-script">&OE_INIT_FILE;</link> 46 See <link linkend="structure-core-script">&OE_INIT_FILE;</link>
@@ -55,13 +55,13 @@
55 </para> 55 </para>
56 56
57 <para> 57 <para>
58 The <filename>target</filename> is the name of the recipe you want to build. 58 The <filename>target</filename> is the name of the recipe you want to build.
59 Common targets are the images in <filename>meta/recipes-core/images</filename>, 59 Common targets are the images in <filename>meta/recipes-core/images</filename>,
60 <filename>/meta/recipes-sato/images</filename>, etc. all found in the 60 <filename>/meta/recipes-sato/images</filename>, etc. all found in the
61 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 61 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
62 Or, the target can be the name of a recipe for a specific piece of software such as 62 Or, the target can be the name of a recipe for a specific piece of software such as
63 <application>busybox</application>. 63 <application>busybox</application>.
64 For more details about the images the OpenEmbedded build system supports, see the 64 For more details about the images the OpenEmbedded build system supports, see the
65 "<link linkend="ref-images">Images</link>" chapter. 65 "<link linkend="ref-images">Images</link>" chapter.
66 </para> 66 </para>
67 67
@@ -76,9 +76,9 @@
76 <title>Building an Image Using GPL Components</title> 76 <title>Building an Image Using GPL Components</title>
77 77
78 <para> 78 <para>
79 When building an image using GPL components, you need to maintain your original 79 When building an image using GPL components, you need to maintain your original
80 settings and not switch back and forth applying different versions of the GNU 80 settings and not switch back and forth applying different versions of the GNU
81 General Public License. 81 General Public License.
82 If you rebuild using different versions of GPL, dependency errors might occur 82 If you rebuild using different versions of GPL, dependency errors might occur
83 due to some components not being rebuilt. 83 due to some components not being rebuilt.
84 </para> 84 </para>
@@ -89,11 +89,11 @@
89 <title>Installing and Using the Result</title> 89 <title>Installing and Using the Result</title>
90 90
91 <para> 91 <para>
92 Once an image has been built, it often needs to be installed. 92 Once an image has been built, it often needs to be installed.
93 The images and kernels built by the OpenEmbedded build system are placed in the 93 The images and kernels built by the OpenEmbedded build system are placed in the
94 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in 94 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
95 <filename class="directory">tmp/deploy/images</filename>. 95 <filename class="directory">tmp/deploy/images</filename>.
96 For information on how to run pre-built images such as <filename>qemux86</filename> 96 For information on how to run pre-built images such as <filename>qemux86</filename>
97 and <filename>qemuarm</filename>, see the 97 and <filename>qemuarm</filename>, see the
98 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" 98 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
99 section in the Yocto Project Quick Start. 99 section in the Yocto Project Quick Start.
@@ -106,25 +106,25 @@
106 <title>Debugging Build Failures</title> 106 <title>Debugging Build Failures</title>
107 107
108 <para> 108 <para>
109 The exact method for debugging build failures depends on the nature of the 109 The exact method for debugging build failures depends on the nature of the
110 problem and on the system's area from which the bug originates. 110 problem and on the system's area from which the bug originates.
111 Standard debugging practices such as comparison against the last 111 Standard debugging practices such as comparison against the last
112 known working version with examination of the changes and the re-application of steps 112 known working version with examination of the changes and the re-application of steps
113 to identify the one causing the problem are 113 to identify the one causing the problem are
114 valid for the Yocto Project just as they are for any other system. 114 valid for the Yocto Project just as they are for any other system.
115 Even though it is impossible to detail every possible potential failure, 115 Even though it is impossible to detail every possible potential failure,
116 this section provides some general tips to aid in debugging. 116 this section provides some general tips to aid in debugging.
117 </para> 117 </para>
118 118
119 <section id='usingpoky-debugging-taskfailures'> 119 <section id='usingpoky-debugging-taskfailures'>
120 <title>Task Failures</title> 120 <title>Task Failures</title>
121 121
122 <para>The log file for shell tasks is available in 122 <para>The log file for shell tasks is available in
123 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 123 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
124 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86 124 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
125 machine (<filename>qemux86</filename>) might be 125 machine (<filename>qemux86</filename>) might be
126 <filename>tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830</filename>. 126 <filename>tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830</filename>.
127 To see what BitBake runs to generate that log, look at the corresponding 127 To see what BitBake runs to generate that log, look at the corresponding
128 <filename>run.do_taskname.pid</filename> file located in the same directory. 128 <filename>run.do_taskname.pid</filename> file located in the same directory.
129 </para> 129 </para>
130 130
@@ -137,17 +137,17 @@
137 <title>Running Specific Tasks</title> 137 <title>Running Specific Tasks</title>
138 138
139 <para> 139 <para>
140 Any given package consists of a set of tasks. 140 Any given package consists of a set of tasks.
141 The standard BitBake behavior in most cases is: <filename>fetch</filename>, 141 The standard BitBake behavior in most cases is: <filename>fetch</filename>,
142 <filename>unpack</filename>, 142 <filename>unpack</filename>,
143 <filename>patch</filename>, <filename>configure</filename>, 143 <filename>patch</filename>, <filename>configure</filename>,
144 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>, 144 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
145 <filename>package_write</filename>, and <filename>build</filename>. 145 <filename>package_write</filename>, and <filename>build</filename>.
146 The default task is <filename>build</filename> and any tasks on which it depends 146 The default task is <filename>build</filename> and any tasks on which it depends
147 build first. 147 build first.
148 Some tasks exist, such as <filename>devshell</filename>, that are not part of the 148 Some tasks exist, such as <filename>devshell</filename>, that are not part of the
149 default build chain. 149 default build chain.
150 If you wish to run a task that is not part of the default build chain, you can use the 150 If you wish to run a task that is not part of the default build chain, you can use the
151 <filename>-c</filename> option in BitBake as follows: 151 <filename>-c</filename> option in BitBake as follows:
152 <literallayout class='monospaced'> 152 <literallayout class='monospaced'>
153 $ bitbake matchbox-desktop -c devshell 153 $ bitbake matchbox-desktop -c devshell
@@ -155,8 +155,8 @@
155 </para> 155 </para>
156 156
157 <para> 157 <para>
158 If you wish to rerun a task, use the <filename>-f</filename> force option. 158 If you wish to rerun a task, use the <filename>-f</filename> force option.
159 For example, the following sequence forces recompilation after changing files in the 159 For example, the following sequence forces recompilation after changing files in the
160 working directory. 160 working directory.
161 <literallayout class='monospaced'> 161 <literallayout class='monospaced'>
162 $ bitbake matchbox-desktop 162 $ bitbake matchbox-desktop
@@ -173,7 +173,7 @@
173 <para> 173 <para>
174 This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it. 174 This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it.
175 The last command reruns all tasks (basically the packaging tasks) after the compile. 175 The last command reruns all tasks (basically the packaging tasks) after the compile.
176 BitBake recognizes that the <filename>compile</filename> task was rerun and therefore 176 BitBake recognizes that the <filename>compile</filename> task was rerun and therefore
177 understands that the other tasks also need to be run again. 177 understands that the other tasks also need to be run again.
178 </para> 178 </para>
179 179
@@ -191,13 +191,13 @@
191 <title>Dependency Graphs</title> 191 <title>Dependency Graphs</title>
192 192
193 <para> 193 <para>
194 Sometimes it can be hard to see why BitBake wants to build some other packages before a given 194 Sometimes it can be hard to see why BitBake wants to build some other packages before a given
195 package you have specified. 195 package you have specified.
196 The <filename>bitbake -g targetname</filename> command creates the 196 The <filename>bitbake -g targetname</filename> command creates the
197 <filename>depends.dot</filename>, <filename>package-depends.dot</filename>, 197 <filename>depends.dot</filename>, <filename>package-depends.dot</filename>,
198 and <filename>task-depends.dot</filename> files in the current directory. 198 and <filename>task-depends.dot</filename> files in the current directory.
199 These files show the package and task dependencies and are useful for debugging problems. 199 These files show the package and task dependencies and are useful for debugging problems.
200 You can use the <filename>bitbake -g -u depexp targetname</filename> command to 200 You can use the <filename>bitbake -g -u depexp targetname</filename> command to
201 display the results in a more human-readable form. 201 display the results in a more human-readable form.
202 </para> 202 </para>
203 </section> 203 </section>
@@ -208,7 +208,7 @@
208 <para> 208 <para>
209 You can see debug output from BitBake by using the <filename>-D</filename> option. 209 You can see debug output from BitBake by using the <filename>-D</filename> option.
210 The debug output gives more information about what BitBake 210 The debug output gives more information about what BitBake
211 is doing and the reason behind it. 211 is doing and the reason behind it.
212 Each <filename>-D</filename> option you use increases the logging level. 212 Each <filename>-D</filename> option you use increases the logging level.
213 The most common usage is <filename>-DDD</filename>. 213 The most common usage is <filename>-DDD</filename>.
214 </para> 214 </para>
@@ -217,7 +217,7 @@
217 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why 217 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
218 BitBake chose a certain version of a package or why BitBake 218 BitBake chose a certain version of a package or why BitBake
219 picked a certain provider. 219 picked a certain provider.
220 This command could also help you in a situation where you think BitBake did something 220 This command could also help you in a situation where you think BitBake did something
221 unexpected. 221 unexpected.
222 </para> 222 </para>
223 </section> 223 </section>
@@ -226,9 +226,9 @@
226 <title>Building with No Dependencies</title> 226 <title>Building with No Dependencies</title>
227 <para> 227 <para>
228 If you really want to build a specific <filename>.bb</filename> file, you can use 228 If you really want to build a specific <filename>.bb</filename> file, you can use
229 the command form <filename>bitbake -b &lt;somepath/somefile.bb&gt;</filename>. 229 the command form <filename>bitbake -b &lt;somepath/somefile.bb&gt;</filename>.
230 This command form does not check for dependencies so you should use it 230 This command form does not check for dependencies so you should use it
231 only when you know its dependencies already exist. 231 only when you know its dependencies already exist.
232 You can also specify fragments of the filename. 232 You can also specify fragments of the filename.
233 In this case, BitBake checks for a unique match. 233 In this case, BitBake checks for a unique match.
234 </para> 234 </para>
@@ -243,31 +243,31 @@
243 to show the environment from parsing a single recipe file only. 243 to show the environment from parsing a single recipe file only.
244 </para> 244 </para>
245 </section> 245 </section>
246 246
247 <section id='recipe-logging-mechanisms'> 247 <section id='recipe-logging-mechanisms'>
248 <title>Recipe Logging Mechanisms</title> 248 <title>Recipe Logging Mechanisms</title>
249 <para> 249 <para>
250 Best practices exist while writing recipes that both log build progress and 250 Best practices exist while writing recipes that both log build progress and
251 act on build conditions such as warnings and errors. 251 act on build conditions such as warnings and errors.
252 Both Python and Bash language bindings exist for the logging mechanism: 252 Both Python and Bash language bindings exist for the logging mechanism:
253 <itemizedlist> 253 <itemizedlist>
254 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake 254 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
255 supports several loglevels: <filename>bb.fatal</filename>, 255 supports several loglevels: <filename>bb.fatal</filename>,
256 <filename>bb.error</filename>, <filename>bb.warn</filename>, 256 <filename>bb.error</filename>, <filename>bb.warn</filename>,
257 <filename>bb.note</filename>, <filename>bb.plain</filename>, 257 <filename>bb.note</filename>, <filename>bb.plain</filename>,
258 and <filename>bb.debug</filename>.</para></listitem> 258 and <filename>bb.debug</filename>.</para></listitem>
259 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set 259 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
260 of loglevels exist and are accessed with a similar syntax: 260 of loglevels exist and are accessed with a similar syntax:
261 <filename>bbfatal</filename>, <filename>bberror</filename>, 261 <filename>bbfatal</filename>, <filename>bberror</filename>,
262 <filename>bbwarn</filename>, <filename>bbnote</filename>, 262 <filename>bbwarn</filename>, <filename>bbnote</filename>,
263 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> 263 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
264 </itemizedlist> 264 </itemizedlist>
265 </para> 265 </para>
266 266
267 <para> 267 <para>
268 For guidance on how logging is handled in both Python and Bash recipes, see the 268 For guidance on how logging is handled in both Python and Bash recipes, see the
269 <filename>logging.bbclass</filename> file in the 269 <filename>logging.bbclass</filename> file in the
270 <filename>meta/classes</filename> folder of the 270 <filename>meta/classes</filename> folder of the
271 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 271 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
272 </para> 272 </para>
273 273
@@ -275,14 +275,14 @@
275 <title>Logging With Python</title> 275 <title>Logging With Python</title>
276 <para> 276 <para>
277 When creating recipes using Python and inserting code that handles build logs 277 When creating recipes using Python and inserting code that handles build logs
278 keep in mind the goal is to have informative logs while keeping the console as 278 keep in mind the goal is to have informative logs while keeping the console as
279 "silent" as possible. 279 "silent" as possible.
280 Also, if you want status messages in the log use the "debug" loglevel. 280 Also, if you want status messages in the log use the "debug" loglevel.
281 </para> 281 </para>
282 282
283 <para> 283 <para>
284 Following is an example written in Python. 284 Following is an example written in Python.
285 The code handles logging for a function that determines the number of tasks 285 The code handles logging for a function that determines the number of tasks
286 needed to be run: 286 needed to be run:
287 <literallayout class='monospaced'> 287 <literallayout class='monospaced'>
288 python do_listtasks() { 288 python do_listtasks() {
@@ -307,8 +307,8 @@
307 <title>Logging With Bash</title> 307 <title>Logging With Bash</title>
308 <para> 308 <para>
309 When creating recipes using Bash and inserting code that handles build 309 When creating recipes using Bash and inserting code that handles build
310 logs you have the same goals - informative with minimal console output. 310 logs you have the same goals - informative with minimal console output.
311 The syntax you use for recipes written in Bash is similar to that of 311 The syntax you use for recipes written in Bash is similar to that of
312 recipes written in Python described in the previous section. 312 recipes written in Python described in the previous section.
313 </para> 313 </para>
314 314
@@ -337,22 +337,22 @@
337 </para> 337 </para>
338 </section> 338 </section>
339 </section> 339 </section>
340 340
341 <section id='usingpoky-debugging-others'> 341 <section id='usingpoky-debugging-others'>
342 <title>Other Tips</title> 342 <title>Other Tips</title>
343 343
344 <para> 344 <para>
345 Here are some other tips that you might find useful: 345 Here are some other tips that you might find useful:
346 <itemizedlist> 346 <itemizedlist>
347 <listitem><para>When adding new packages, it is worth watching for 347 <listitem><para>When adding new packages, it is worth watching for
348 undesirable items making their way into compiler command lines. 348 undesirable items making their way into compiler command lines.
349 For example, you do not want references to local system files like 349 For example, you do not want references to local system files like
350 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. 350 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
351 </para></listitem> 351 </para></listitem>
352 <listitem><para>If you want to remove the psplash boot splashscreen, 352 <listitem><para>If you want to remove the psplash boot splashscreen,
353 add <filename>psplash=false</filename> to the kernel command line. 353 add <filename>psplash=false</filename> to the kernel command line.
354 Doing so prevents psplash from loading and thus allows you to see the console. 354 Doing so prevents psplash from loading and thus allows you to see the console.
355 It is also possible to switch out of the splashscreen by 355 It is also possible to switch out of the splashscreen by
356 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). 356 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
357 </para></listitem> 357 </para></listitem>
358 </itemizedlist> 358 </itemizedlist>
@@ -365,25 +365,25 @@
365 365
366 <para> 366 <para>
367 A build's quality can be influenced by many things. 367 A build's quality can be influenced by many things.
368 For example, if you upgrade a recipe to use a new version of an upstream software 368 For example, if you upgrade a recipe to use a new version of an upstream software
369 package or you experiment with some new configuration options, subtle changes 369 package or you experiment with some new configuration options, subtle changes
370 can occur that you might not detect until later. 370 can occur that you might not detect until later.
371 Consider the case where your recipe is using a newer version of an upstream package. 371 Consider the case where your recipe is using a newer version of an upstream package.
372 In this case, a new version of a piece of software might introduce an optional 372 In this case, a new version of a piece of software might introduce an optional
373 dependency on another library, which is auto-detected. 373 dependency on another library, which is auto-detected.
374 If that library has already been built when the software is building, 374 If that library has already been built when the software is building,
375 then the software will link to the built library and that library will be pulled 375 then the software will link to the built library and that library will be pulled
376 into your image along with the new software even if you did not want the 376 into your image along with the new software even if you did not want the
377 library. 377 library.
378 </para> 378 </para>
379 379
380 <para> 380 <para>
381 The <filename>buildhistory</filename> class exists to help you maintain 381 The <filename>buildhistory</filename> class exists to help you maintain
382 the quality of your build output. 382 the quality of your build output.
383 You can use the class to highlight unexpected and possibly unwanted 383 You can use the class to highlight unexpected and possibly unwanted
384 changes in the build output. 384 changes in the build output.
385 When you enable build history it records information about the contents of 385 When you enable build history it records information about the contents of
386 each package and image and then commits that information to a local Git 386 each package and image and then commits that information to a local Git
387 repository where you can examine the information. 387 repository where you can examine the information.
388 </para> 388 </para>
389 389
@@ -396,7 +396,7 @@
396 </para></listitem> 396 </para></listitem>
397 <listitem><para>How to limit the information used for build history 397 <listitem><para>How to limit the information used for build history
398 </para></listitem> 398 </para></listitem>
399 <listitem><para>How to examine the build history from both a 399 <listitem><para>How to examine the build history from both a
400 command-line and web interface</para></listitem> 400 command-line and web interface</para></listitem>
401 </itemizedlist> 401 </itemizedlist>
402 </para> 402 </para>
@@ -406,41 +406,41 @@
406 406
407 <para> 407 <para>
408 Build history is disabled by default. 408 Build history is disabled by default.
409 To enable it, add the following statements to the end of your 409 To enable it, add the following statements to the end of your
410 <filename>conf/local.conf</filename> file found in the 410 <filename>conf/local.conf</filename> file found in the
411 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: 411 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
412 <literallayout class='monospaced'> 412 <literallayout class='monospaced'>
413 INHERIT += "buildhistory" 413 INHERIT += "buildhistory"
414 BUILDHISTORY_COMMIT = "1" 414 BUILDHISTORY_COMMIT = "1"
415 </literallayout> 415 </literallayout>
416 Enabling build history as previously described 416 Enabling build history as previously described
417 causes the build process to collect build 417 causes the build process to collect build
418 output information and commit it to a local 418 output information and commit it to a local
419 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository. 419 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
420 <note> 420 <note>
421 Enabling build history increases your build times slightly, 421 Enabling build history increases your build times slightly,
422 particularly for images, and increases the amount of disk 422 particularly for images, and increases the amount of disk
423 space used during the build. 423 space used during the build.
424 </note> 424 </note>
425 </para> 425 </para>
426 426
427 <para> 427 <para>
428 You can disable build history by removing the previous statements 428 You can disable build history by removing the previous statements
429 from your <filename>conf/local.conf</filename> file. 429 from your <filename>conf/local.conf</filename> file.
430 However, you should realize that enabling and disabling 430 However, you should realize that enabling and disabling
431 build history in this manner can change the 431 build history in this manner can change the
432 <filename>do_package</filename> task checksums, which if you 432 <filename>do_package</filename> task checksums, which if you
433 are using the OEBasicHash signature generator (the default 433 are using the OEBasicHash signature generator (the default
434 for many current distro configurations including 434 for many current distro configurations including
435 <filename>DISTRO = "poky"</filename> and 435 <filename>DISTRO = "poky"</filename> and
436 <filename>DISTRO = ""</filename>) will result in the packaging 436 <filename>DISTRO = ""</filename>) will result in the packaging
437 tasks being re-run during the subsequent build. 437 tasks being re-run during the subsequent build.
438 </para> 438 </para>
439 439
440 <para> 440 <para>
441 To disable the build history functionality without causing the 441 To disable the build history functionality without causing the
442 packaging tasks to be re-run, add just this statement to your 442 packaging tasks to be re-run, add just this statement to your
443 <filename>conf/local.conf</filename> file: 443 <filename>conf/local.conf</filename> file:
444 <literallayout class='monospaced'> 444 <literallayout class='monospaced'>
445 BUILDHISTORY_FEATURES = "" 445 BUILDHISTORY_FEATURES = ""
446 </literallayout> 446 </literallayout>
@@ -451,19 +451,19 @@
451 <title>Understanding What the Build History Contains</title> 451 <title>Understanding What the Build History Contains</title>
452 452
453 <para> 453 <para>
454 Build history information is kept in 454 Build history information is kept in
455 <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename> 455 <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename>
456 in the Build Directory. 456 in the Build Directory.
457 The following is an example abbreviated listing: 457 The following is an example abbreviated listing:
458 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" /> 458 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
459 </para> 459 </para>
460 460
461 <section id='build-history-package-information'> 461 <section id='build-history-package-information'>
462 <title>Build History Package Information</title> 462 <title>Build History Package Information</title>
463 463
464 <para> 464 <para>
465 The history for each package contains a text file that has 465 The history for each package contains a text file that has
466 name-value pairs with information about the package. 466 name-value pairs with information about the package.
467 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename> 467 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
468 contains the following: 468 contains the following:
469 <literallayout class='monospaced'> 469 <literallayout class='monospaced'>
@@ -474,21 +474,21 @@
474 PKGSIZE = 564701 474 PKGSIZE = 564701
475 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ 475 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
476 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \ 476 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
477 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ 477 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
478 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers 478 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
479 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh 479 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
480 </literallayout> 480 </literallayout>
481 Most of these name-value pairs corresponds to variables used 481 Most of these name-value pairs corresponds to variables used
482 to produce the package. 482 to produce the package.
483 The exceptions are <filename>FILELIST</filename>, which is the 483 The exceptions are <filename>FILELIST</filename>, which is the
484 actual list of files in the package, and 484 actual list of files in the package, and
485 <filename>PKGSIZE</filename>, which is the total size of files 485 <filename>PKGSIZE</filename>, which is the total size of files
486 in the package in bytes. 486 in the package in bytes.
487 </para> 487 </para>
488 488
489 <para> 489 <para>
490 There is also a file corresponding to the recipe from which the 490 There is also a file corresponding to the recipe from which the
491 package came (e.g. 491 package came (e.g.
492 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>): 492 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
493 <literallayout class='monospaced'> 493 <literallayout class='monospaced'>
494 PV = 1.19.3 494 PV = 1.19.3
@@ -509,18 +509,18 @@
509 The files produced for each image are as follows: 509 The files produced for each image are as follows:
510 <itemizedlist> 510 <itemizedlist>
511 <listitem><para><emphasis>build-id:</emphasis> 511 <listitem><para><emphasis>build-id:</emphasis>
512 Human-readable information about the build configuration 512 Human-readable information about the build configuration
513 and metadata source revisions.</para></listitem> 513 and metadata source revisions.</para></listitem>
514 <listitem><para><emphasis>*.dot:</emphasis> 514 <listitem><para><emphasis>*.dot:</emphasis>
515 Dependency graphs for the image that are 515 Dependency graphs for the image that are
516 compatible with <filename>graphviz</filename>. 516 compatible with <filename>graphviz</filename>.
517 </para></listitem> 517 </para></listitem>
518 <listitem><para><emphasis>files-in-image.txt:</emphasis> 518 <listitem><para><emphasis>files-in-image.txt:</emphasis>
519 A list of files in the image with permissions, 519 A list of files in the image with permissions,
520 owner, group, size, and symlink information. 520 owner, group, size, and symlink information.
521 </para></listitem> 521 </para></listitem>
522 <listitem><para><emphasis>image-info.txt:</emphasis> 522 <listitem><para><emphasis>image-info.txt:</emphasis>
523 A text file containing name-value pairs with information 523 A text file containing name-value pairs with information
524 about the image. 524 about the image.
525 See the following listing example for more information. 525 See the following listing example for more information.
526 </para></listitem> 526 </para></listitem>
@@ -535,7 +535,7 @@
535 </itemizedlist> 535 </itemizedlist>
536 <note> 536 <note>
537 Installed package information is able to be gathered and 537 Installed package information is able to be gathered and
538 produced even if package management is disabled for the final 538 produced even if package management is disabled for the final
539 image. 539 image.
540 </note> 540 </note>
541 </para> 541 </para>
@@ -551,15 +551,15 @@
551 package-management ssh-server-dropbear package-management 551 package-management ssh-server-dropbear package-management
552 IMAGE_LINGUAS = en-us en-gb 552 IMAGE_LINGUAS = en-us en-gb
553 IMAGE_INSTALL = task-core-boot task-base-extended 553 IMAGE_INSTALL = task-core-boot task-base-extended
554 BAD_RECOMMENDATIONS = 554 BAD_RECOMMENDATIONS =
555 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; 555 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
556 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; 556 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
557 IMAGESIZE = 171816 557 IMAGESIZE = 171816
558 </literallayout> 558 </literallayout>
559 Other than <filename>IMAGESIZE</filename>, which is the 559 Other than <filename>IMAGESIZE</filename>, which is the
560 total size of the files in the image in Kbytes, the 560 total size of the files in the image in Kbytes, the
561 name-value pairs are variables that may have influenced the 561 name-value pairs are variables that may have influenced the
562 content of the image. 562 content of the image.
563 This information is often useful when you are trying to determine 563 This information is often useful when you are trying to determine
564 why a change in the package or file listings has occurred. 564 why a change in the package or file listings has occurred.
565 </para> 565 </para>
@@ -568,15 +568,15 @@
568 <section id='using-build-history-to-gather-image-information-only'> 568 <section id='using-build-history-to-gather-image-information-only'>
569 <title>Using Build History to Gather Image Information Only</title> 569 <title>Using Build History to Gather Image Information Only</title>
570 570
571 <para> 571 <para>
572 As you can see, build history produces image information, 572 As you can see, build history produces image information,
573 including dependency graphs, so you can see why something 573 including dependency graphs, so you can see why something
574 was pulled into the image. 574 was pulled into the image.
575 If you are just interested in this information and not 575 If you are just interested in this information and not
576 interested in collecting history or any package information, 576 interested in collecting history or any package information,
577 you can enable writing only image information without 577 you can enable writing only image information without
578 any history by adding the following 578 any history by adding the following
579 to your <filename>conf/local.conf</filename> file found in the 579 to your <filename>conf/local.conf</filename> file found in the
580 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: 580 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
581 <literallayout class='monospaced'> 581 <literallayout class='monospaced'>
582 INHERIT += "buildhistory" 582 INHERIT += "buildhistory"
@@ -590,28 +590,28 @@
590 <title>Examining Build History Information</title> 590 <title>Examining Build History Information</title>
591 591
592 <para> 592 <para>
593 You can examine build history output from the command line or 593 You can examine build history output from the command line or
594 from a web interface. 594 from a web interface.
595 </para> 595 </para>
596 596
597 <para> 597 <para>
598 To see any changes that have occurred (assuming you have 598 To see any changes that have occurred (assuming you have
599 <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply 599 <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply
600 use any Git command that allows you to view the history of 600 use any Git command that allows you to view the history of
601 a repository. 601 a repository.
602 Here is one method: 602 Here is one method:
603 <literallayout class='monospaced'> 603 <literallayout class='monospaced'>
604 $ git log -p 604 $ git log -p
605 </literallayout> 605 </literallayout>
606 You need to realize, however, that this method does show 606 You need to realize, however, that this method does show
607 changes that are not significant (e.g. a package's size 607 changes that are not significant (e.g. a package's size
608 changing by a few bytes). 608 changing by a few bytes).
609 </para> 609 </para>
610 610
611 <para> 611 <para>
612 A command-line tool called <filename>buildhistory-diff</filename> 612 A command-line tool called <filename>buildhistory-diff</filename>
613 does exist though that queries the Git repository and prints just 613 does exist though that queries the Git repository and prints just
614 the differences that might be significant in human-readable form. 614 the differences that might be significant in human-readable form.
615 Here is an example: 615 Here is an example:
616 <literallayout class='monospaced'> 616 <literallayout class='monospaced'>
617 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ 617 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
@@ -632,7 +632,7 @@
632 </para> 632 </para>
633 633
634 <para> 634 <para>
635 To see changes to the build history using a web interface, follow 635 To see changes to the build history using a web interface, follow
636 the instruction in the <filename>README</filename> file here. 636 the instruction in the <filename>README</filename> file here.
637 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>. 637 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
638 </para> 638 </para>
@@ -646,6 +646,6 @@
646</section> 646</section>
647 647
648</chapter> 648</chapter>
649<!-- 649<!--
650vim: expandtab tw=80 ts=4 650vim: expandtab tw=80 ts=4
651--> 651-->