diff options
| author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2012-12-07 17:29:51 -0600 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2012-12-11 16:17:56 +0000 |
| commit | 73ffb8298b545a1a1fb96bc5952b7365c4c43bfd (patch) | |
| tree | 9c6473cb4e3c5dd8370c2d417c304e1a302fa643 /documentation/poky-ref-manual/usingpoky.xml | |
| parent | acb3f72afaa28ba5d23ca6e5cdf9f1162ea656a3 (diff) | |
| download | poky-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.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 | --> |
