diff options
Diffstat (limited to 'documentation/poky-ref-manual/usingpoky.xml')
-rw-r--r-- | documentation/poky-ref-manual/usingpoky.xml | 264 |
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 <somepath/somefile.bb></filename>. | 229 | the command form <filename>bitbake -b <somepath/somefile.bb></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 | <!-- |
650 | vim: expandtab tw=80 ts=4 | 650 | vim: expandtab tw=80 ts=4 |
651 | --> | 651 | --> |