diff options
Diffstat (limited to 'documentation/ref-manual/usingpoky.xml')
| -rw-r--r-- | documentation/ref-manual/usingpoky.xml | 651 |
1 files changed, 651 insertions, 0 deletions
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml new file mode 100644 index 0000000000..149490969a --- /dev/null +++ b/documentation/ref-manual/usingpoky.xml | |||
| @@ -0,0 +1,651 @@ | |||
| 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | <chapter id='usingpoky'> | ||
| 6 | <title>Using the Yocto Project</title> | ||
| 7 | |||
| 8 | <para> | ||
| 9 | This chapter describes common usage for the Yocto Project. | ||
| 10 | The information is introductory in nature as other manuals in the Yocto Project | ||
| 11 | documentation set provide more details on how to use the Yocto Project. | ||
| 12 | </para> | ||
| 13 | |||
| 14 | <section id='usingpoky-build'> | ||
| 15 | <title>Running a Build</title> | ||
| 16 | |||
| 17 | <para> | ||
| 18 | This section provides a summary of the build process and provides information | ||
| 19 | for less obvious aspects of the build process. | ||
| 20 | For general information on how to build an image using the OpenEmbedded build | ||
| 21 | system, see the | ||
| 22 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | ||
| 23 | section of the Yocto Project Quick Start. | ||
| 24 | </para> | ||
| 25 | |||
| 26 | <section id='build-overview'> | ||
| 27 | <title>Build Overview</title> | ||
| 28 | |||
| 29 | <para> | ||
| 30 | The first thing you need to do is set up the OpenEmbedded build environment by sourcing | ||
| 31 | the <link linkend='structure-core-script'>environment setup script</link> as follows: | ||
| 32 | <literallayout class='monospaced'> | ||
| 33 | $ source &OE_INIT_FILE; [build_dir] | ||
| 34 | </literallayout> | ||
| 35 | </para> | ||
| 36 | |||
| 37 | <para> | ||
| 38 | The <filename>build_dir</filename> is optional and specifies the directory the | ||
| 39 | OpenEmbedded build system uses for the build - | ||
| 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> | ||
| 42 | in your current working directory. | ||
| 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> | ||
| 45 | target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target. | ||
| 46 | See <link linkend="structure-core-script">&OE_INIT_FILE;</link> | ||
| 47 | for more information on this script. | ||
| 48 | </para> | ||
| 49 | |||
| 50 | <para> | ||
| 51 | Once the build environment is set up, you can build a target using: | ||
| 52 | <literallayout class='monospaced'> | ||
| 53 | $ bitbake <target> | ||
| 54 | </literallayout> | ||
| 55 | </para> | ||
| 56 | |||
| 57 | <para> | ||
| 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>, | ||
| 60 | <filename>/meta/recipes-sato/images</filename>, etc. all found in the | ||
| 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 | ||
| 63 | <application>busybox</application>. | ||
| 64 | For more details about the images the OpenEmbedded build system supports, see the | ||
| 65 | "<link linkend="ref-images">Images</link>" chapter. | ||
| 66 | </para> | ||
| 67 | |||
| 68 | <note> | ||
| 69 | Building an image without GNU General Public License Version 3 (GPLv3) components | ||
| 70 | is only supported for minimal and base images. | ||
| 71 | See the "<link linkend='ref-images'>Images</link>" chapter for more information. | ||
| 72 | </note> | ||
| 73 | </section> | ||
| 74 | |||
| 75 | <section id='building-an-image-using-gpl-components'> | ||
| 76 | <title>Building an Image Using GPL Components</title> | ||
| 77 | |||
| 78 | <para> | ||
| 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 | ||
| 81 | General Public License. | ||
| 82 | If you rebuild using different versions of GPL, dependency errors might occur | ||
| 83 | due to some components not being rebuilt. | ||
| 84 | </para> | ||
| 85 | </section> | ||
| 86 | </section> | ||
| 87 | |||
| 88 | <section id='usingpoky-install'> | ||
| 89 | <title>Installing and Using the Result</title> | ||
| 90 | |||
| 91 | <para> | ||
| 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 | ||
| 94 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in | ||
| 95 | <filename class="directory">tmp/deploy/images</filename>. | ||
| 96 | For information on how to run pre-built images such as <filename>qemux86</filename> | ||
| 97 | and <filename>qemuarm</filename>, see the | ||
| 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. | ||
| 100 | For information about how to install these images, see the documentation for your | ||
| 101 | particular board/machine. | ||
| 102 | </para> | ||
| 103 | </section> | ||
| 104 | |||
| 105 | <section id='usingpoky-debugging'> | ||
| 106 | <title>Debugging Build Failures</title> | ||
| 107 | |||
| 108 | <para> | ||
| 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. | ||
| 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 | ||
| 113 | to identify the one causing the problem are | ||
| 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, | ||
| 116 | this section provides some general tips to aid in debugging. | ||
| 117 | </para> | ||
| 118 | |||
| 119 | <section id='usingpoky-debugging-taskfailures'> | ||
| 120 | <title>Task Failures</title> | ||
| 121 | |||
| 122 | <para>The log file for shell tasks is available in | ||
| 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 | ||
| 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>. | ||
| 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. | ||
| 129 | </para> | ||
| 130 | |||
| 131 | <para> | ||
| 132 | Presently, the output from Python tasks is sent directly to the console. | ||
| 133 | </para> | ||
| 134 | </section> | ||
| 135 | |||
| 136 | <section id='usingpoky-debugging-taskrunning'> | ||
| 137 | <title>Running Specific Tasks</title> | ||
| 138 | |||
| 139 | <para> | ||
| 140 | Any given package consists of a set of tasks. | ||
| 141 | The standard BitBake behavior in most cases is: <filename>fetch</filename>, | ||
| 142 | <filename>unpack</filename>, | ||
| 143 | <filename>patch</filename>, <filename>configure</filename>, | ||
| 144 | <filename>compile</filename>, <filename>install</filename>, <filename>package</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 | ||
| 147 | build first. | ||
| 148 | Some tasks exist, such as <filename>devshell</filename>, that are not part of the | ||
| 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 | ||
| 151 | <filename>-c</filename> option in BitBake as follows: | ||
| 152 | <literallayout class='monospaced'> | ||
| 153 | $ bitbake matchbox-desktop -c devshell | ||
| 154 | </literallayout> | ||
| 155 | </para> | ||
| 156 | |||
| 157 | <para> | ||
| 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 | ||
| 160 | working directory. | ||
| 161 | <literallayout class='monospaced'> | ||
| 162 | $ bitbake matchbox-desktop | ||
| 163 | . | ||
| 164 | . | ||
| 165 | [make some changes to the source code in the working directory] | ||
| 166 | . | ||
| 167 | . | ||
| 168 | $ bitbake matchbox-desktop -c compile -f | ||
| 169 | $ bitbake matchbox-desktop | ||
| 170 | </literallayout> | ||
| 171 | </para> | ||
| 172 | |||
| 173 | <para> | ||
| 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. | ||
| 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. | ||
| 178 | </para> | ||
| 179 | |||
| 180 | <para> | ||
| 181 | You can view a list of tasks in a given package by running the | ||
| 182 | <filename>listtasks</filename> task as follows: | ||
| 183 | <literallayout class='monospaced'> | ||
| 184 | $ bitbake matchbox-desktop -c listtasks | ||
| 185 | </literallayout> | ||
| 186 | The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>. | ||
| 187 | </para> | ||
| 188 | </section> | ||
| 189 | |||
| 190 | <section id='usingpoky-debugging-dependencies'> | ||
| 191 | <title>Dependency Graphs</title> | ||
| 192 | |||
| 193 | <para> | ||
| 194 | Sometimes it can be hard to see why BitBake wants to build some other packages before a given | ||
| 195 | package you have specified. | ||
| 196 | The <filename>bitbake -g targetname</filename> command creates the | ||
| 197 | <filename>depends.dot</filename>, <filename>package-depends.dot</filename>, | ||
| 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. | ||
| 200 | You can use the <filename>bitbake -g -u depexp targetname</filename> command to | ||
| 201 | display the results in a more human-readable form. | ||
| 202 | </para> | ||
| 203 | </section> | ||
| 204 | |||
| 205 | <section id='usingpoky-debugging-bitbake'> | ||
| 206 | <title>General BitBake Problems</title> | ||
| 207 | |||
| 208 | <para> | ||
| 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 | ||
| 211 | is doing and the reason behind it. | ||
| 212 | Each <filename>-D</filename> option you use increases the logging level. | ||
| 213 | The most common usage is <filename>-DDD</filename>. | ||
| 214 | </para> | ||
| 215 | |||
| 216 | <para> | ||
| 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 | ||
| 219 | picked a certain provider. | ||
| 220 | This command could also help you in a situation where you think BitBake did something | ||
| 221 | unexpected. | ||
| 222 | </para> | ||
| 223 | </section> | ||
| 224 | |||
| 225 | <section id='usingpoky-debugging-buildfile'> | ||
| 226 | <title>Building with No Dependencies</title> | ||
| 227 | <para> | ||
| 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>. | ||
| 230 | This command form does not check for dependencies so you should use it | ||
| 231 | only when you know its dependencies already exist. | ||
| 232 | You can also specify fragments of the filename. | ||
| 233 | In this case, BitBake checks for a unique match. | ||
| 234 | </para> | ||
| 235 | </section> | ||
| 236 | |||
| 237 | <section id='usingpoky-debugging-variables'> | ||
| 238 | <title>Variables</title> | ||
| 239 | <para> | ||
| 240 | The <filename>-e</filename> option dumps the resulting environment for | ||
| 241 | either the configuration (no package specified) or for a | ||
| 242 | specific package when specified; or <filename>-b recipename</filename> | ||
| 243 | to show the environment from parsing a single recipe file only. | ||
| 244 | </para> | ||
| 245 | </section> | ||
| 246 | |||
| 247 | <section id='recipe-logging-mechanisms'> | ||
| 248 | <title>Recipe Logging Mechanisms</title> | ||
| 249 | <para> | ||
| 250 | Best practices exist while writing recipes that both log build progress and | ||
| 251 | act on build conditions such as warnings and errors. | ||
| 252 | Both Python and Bash language bindings exist for the logging mechanism: | ||
| 253 | <itemizedlist> | ||
| 254 | <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake | ||
| 255 | supports several loglevels: <filename>bb.fatal</filename>, | ||
| 256 | <filename>bb.error</filename>, <filename>bb.warn</filename>, | ||
| 257 | <filename>bb.note</filename>, <filename>bb.plain</filename>, | ||
| 258 | and <filename>bb.debug</filename>.</para></listitem> | ||
| 259 | <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set | ||
| 260 | of loglevels exist and are accessed with a similar syntax: | ||
| 261 | <filename>bbfatal</filename>, <filename>bberror</filename>, | ||
| 262 | <filename>bbwarn</filename>, <filename>bbnote</filename>, | ||
| 263 | <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> | ||
| 264 | </itemizedlist> | ||
| 265 | </para> | ||
| 266 | |||
| 267 | <para> | ||
| 268 | For guidance on how logging is handled in both Python and Bash recipes, see the | ||
| 269 | <filename>logging.bbclass</filename> file in the | ||
| 270 | <filename>meta/classes</filename> folder of the | ||
| 271 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
| 272 | </para> | ||
| 273 | |||
| 274 | <section id='logging-with-python'> | ||
| 275 | <title>Logging With Python</title> | ||
| 276 | <para> | ||
| 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 | ||
| 279 | "silent" as possible. | ||
| 280 | Also, if you want status messages in the log use the "debug" loglevel. | ||
| 281 | </para> | ||
| 282 | |||
| 283 | <para> | ||
| 284 | Following is an example written in Python. | ||
| 285 | The code handles logging for a function that determines the number of tasks | ||
| 286 | needed to be run: | ||
| 287 | <literallayout class='monospaced'> | ||
| 288 | python do_listtasks() { | ||
| 289 | bb.debug(2, "Starting to figure out the task list") | ||
| 290 | if noteworthy_condition: | ||
| 291 | bb.note("There are 47 tasks to run") | ||
| 292 | bb.debug(2, "Got to point xyz") | ||
| 293 | if warning_trigger: | ||
| 294 | bb.warn("Detected warning_trigger, this might be a problem later.") | ||
| 295 | if recoverable_error: | ||
| 296 | bb.error("Hit recoverable_error, you really need to fix this!") | ||
| 297 | if fatal_error: | ||
| 298 | bb.fatal("fatal_error detected, unable to print the task list") | ||
| 299 | bb.plain("The tasks present are abc") | ||
| 300 | bb.debug(2, "Finished figuring out the tasklist") | ||
| 301 | } | ||
| 302 | </literallayout> | ||
| 303 | </para> | ||
| 304 | </section> | ||
| 305 | |||
| 306 | <section id='logging-with-bash'> | ||
| 307 | <title>Logging With Bash</title> | ||
| 308 | <para> | ||
| 309 | When creating recipes using Bash and inserting code that handles build | ||
| 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 | ||
| 312 | recipes written in Python described in the previous section. | ||
| 313 | </para> | ||
| 314 | |||
| 315 | <para> | ||
| 316 | Following is an example written in Bash. | ||
| 317 | The code logs the progress of the <filename>do_my_function</filename> function. | ||
| 318 | <literallayout class='monospaced'> | ||
| 319 | do_my_function() { | ||
| 320 | bbdebug 2 "Running do_my_function" | ||
| 321 | if [ exceptional_condition ]; then | ||
| 322 | bbnote "Hit exceptional_condition" | ||
| 323 | fi | ||
| 324 | bbdebug 2 "Got to point xyz" | ||
| 325 | if [ warning_trigger ]; then | ||
| 326 | bbwarn "Detected warning_trigger, this might cause a problem later." | ||
| 327 | fi | ||
| 328 | if [ recoverable_error ]; then | ||
| 329 | bberror "Hit recoverable_error, correcting" | ||
| 330 | fi | ||
| 331 | if [ fatal_error ]; then | ||
| 332 | bbfatal "fatal_error detected" | ||
| 333 | fi | ||
| 334 | bbdebug 2 "Completed do_my_function" | ||
| 335 | } | ||
| 336 | </literallayout> | ||
| 337 | </para> | ||
| 338 | </section> | ||
| 339 | </section> | ||
| 340 | |||
| 341 | <section id='usingpoky-debugging-others'> | ||
| 342 | <title>Other Tips</title> | ||
| 343 | |||
| 344 | <para> | ||
| 345 | Here are some other tips that you might find useful: | ||
| 346 | <itemizedlist> | ||
| 347 | <listitem><para>When adding new packages, it is worth watching for | ||
| 348 | undesirable items making their way into compiler command lines. | ||
| 349 | For example, you do not want references to local system files like | ||
| 350 | <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. | ||
| 351 | </para></listitem> | ||
| 352 | <listitem><para>If you want to remove the psplash boot splashscreen, | ||
| 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. | ||
| 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). | ||
| 357 | </para></listitem> | ||
| 358 | </itemizedlist> | ||
| 359 | </para> | ||
| 360 | </section> | ||
| 361 | </section> | ||
| 362 | |||
| 363 | <section id='maintaining-build-output-quality'> | ||
| 364 | <title>Maintaining Build Output Quality</title> | ||
| 365 | |||
| 366 | <para> | ||
| 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 | ||
| 369 | package or you experiment with some new configuration options, subtle changes | ||
| 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. | ||
| 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. | ||
| 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 | ||
| 376 | into your image along with the new software even if you did not want the | ||
| 377 | library. | ||
| 378 | </para> | ||
| 379 | |||
| 380 | <para> | ||
| 381 | The <filename>buildhistory</filename> class exists to help you maintain | ||
| 382 | the quality of your build output. | ||
| 383 | You can use the class to highlight unexpected and possibly unwanted | ||
| 384 | changes in the build output. | ||
| 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 | ||
| 387 | repository where you can examine the information. | ||
| 388 | </para> | ||
| 389 | |||
| 390 | <para> | ||
| 391 | The remainder of this section describes the following: | ||
| 392 | <itemizedlist> | ||
| 393 | <listitem><para>How you can enable and disable | ||
| 394 | build history</para></listitem> | ||
| 395 | <listitem><para>How to understand what the build history contains | ||
| 396 | </para></listitem> | ||
| 397 | <listitem><para>How to limit the information used for build history | ||
| 398 | </para></listitem> | ||
| 399 | <listitem><para>How to examine the build history from both a | ||
| 400 | command-line and web interface</para></listitem> | ||
| 401 | </itemizedlist> | ||
| 402 | </para> | ||
| 403 | |||
| 404 | <section id='enabling-and-disabling-build-history'> | ||
| 405 | <title>Enabling and Disabling Build History</title> | ||
| 406 | |||
| 407 | <para> | ||
| 408 | Build history is disabled by default. | ||
| 409 | To enable it, add the following statements to the end of your | ||
| 410 | <filename>conf/local.conf</filename> file found in the | ||
| 411 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | ||
| 412 | <literallayout class='monospaced'> | ||
| 413 | INHERIT += "buildhistory" | ||
| 414 | BUILDHISTORY_COMMIT = "1" | ||
| 415 | </literallayout> | ||
| 416 | Enabling build history as previously described | ||
| 417 | causes the build process to collect build | ||
| 418 | output information and commit it to a local | ||
| 419 | <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository. | ||
| 420 | <note> | ||
| 421 | Enabling build history increases your build times slightly, | ||
| 422 | particularly for images, and increases the amount of disk | ||
| 423 | space used during the build. | ||
| 424 | </note> | ||
| 425 | </para> | ||
| 426 | |||
| 427 | <para> | ||
| 428 | You can disable build history by removing the previous statements | ||
| 429 | from your <filename>conf/local.conf</filename> file. | ||
| 430 | However, you should realize that enabling and disabling | ||
| 431 | build history in this manner can change the | ||
| 432 | <filename>do_package</filename> task checksums, which if you | ||
| 433 | are using the OEBasicHash signature generator (the default | ||
| 434 | for many current distro configurations including | ||
| 435 | <filename>DISTRO = "poky"</filename> and | ||
| 436 | <filename>DISTRO = ""</filename>) will result in the packaging | ||
| 437 | tasks being re-run during the subsequent build. | ||
| 438 | </para> | ||
| 439 | |||
| 440 | <para> | ||
| 441 | To disable the build history functionality without causing the | ||
| 442 | packaging tasks to be re-run, add just this statement to your | ||
| 443 | <filename>conf/local.conf</filename> file: | ||
| 444 | <literallayout class='monospaced'> | ||
| 445 | BUILDHISTORY_FEATURES = "" | ||
| 446 | </literallayout> | ||
| 447 | </para> | ||
| 448 | </section> | ||
| 449 | |||
| 450 | <section id='understanding-what-the-build-history-contains'> | ||
| 451 | <title>Understanding What the Build History Contains</title> | ||
| 452 | |||
| 453 | <para> | ||
| 454 | Build history information is kept in | ||
| 455 | <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename> | ||
| 456 | in the Build Directory. | ||
| 457 | The following is an example abbreviated listing: | ||
| 458 | <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" /> | ||
| 459 | </para> | ||
| 460 | |||
| 461 | <section id='build-history-package-information'> | ||
| 462 | <title>Build History Package Information</title> | ||
| 463 | |||
| 464 | <para> | ||
| 465 | The history for each package contains a text file that has | ||
| 466 | name-value pairs with information about the package. | ||
| 467 | For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename> | ||
| 468 | contains the following: | ||
| 469 | <literallayout class='monospaced'> | ||
| 470 | PV = 1.19.3 | ||
| 471 | PR = r3 | ||
| 472 | RDEPENDS = update-rc.d eglibc (>= 2.13) | ||
| 473 | RRECOMMENDS = busybox-syslog busybox-udhcpc | ||
| 474 | PKGSIZE = 564701 | ||
| 475 | FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ | ||
| 476 | /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \ | ||
| 477 | /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ | ||
| 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 | ||
| 480 | </literallayout> | ||
| 481 | Most of these name-value pairs corresponds to variables used | ||
| 482 | to produce the package. | ||
| 483 | The exceptions are <filename>FILELIST</filename>, which is the | ||
| 484 | actual list of files in the package, and | ||
| 485 | <filename>PKGSIZE</filename>, which is the total size of files | ||
| 486 | in the package in bytes. | ||
| 487 | </para> | ||
| 488 | |||
| 489 | <para> | ||
| 490 | There is also a file corresponding to the recipe from which the | ||
| 491 | package came (e.g. | ||
| 492 | <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>): | ||
| 493 | <literallayout class='monospaced'> | ||
| 494 | PV = 1.19.3 | ||
| 495 | PR = r3 | ||
| 496 | DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \ | ||
| 497 | virtual/libc update-rc.d-native | ||
| 498 | PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \ | ||
| 499 | busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \ | ||
| 500 | busybox-staticdev busybox-locale | ||
| 501 | </literallayout> | ||
| 502 | </para> | ||
| 503 | </section> | ||
| 504 | |||
| 505 | <section id='build-history-image-information'> | ||
| 506 | <title>Build History Image Information</title> | ||
| 507 | |||
| 508 | <para> | ||
| 509 | The files produced for each image are as follows: | ||
| 510 | <itemizedlist> | ||
| 511 | <listitem><para><emphasis>build-id:</emphasis> | ||
| 512 | Human-readable information about the build configuration | ||
| 513 | and metadata source revisions.</para></listitem> | ||
| 514 | <listitem><para><emphasis>*.dot:</emphasis> | ||
| 515 | Dependency graphs for the image that are | ||
| 516 | compatible with <filename>graphviz</filename>. | ||
| 517 | </para></listitem> | ||
| 518 | <listitem><para><emphasis>files-in-image.txt:</emphasis> | ||
| 519 | A list of files in the image with permissions, | ||
| 520 | owner, group, size, and symlink information. | ||
| 521 | </para></listitem> | ||
| 522 | <listitem><para><emphasis>image-info.txt:</emphasis> | ||
| 523 | A text file containing name-value pairs with information | ||
| 524 | about the image. | ||
| 525 | See the following listing example for more information. | ||
| 526 | </para></listitem> | ||
| 527 | <listitem><para><emphasis>installed-package-names.txt:</emphasis> | ||
| 528 | A list of installed packages by name only.</para></listitem> | ||
| 529 | <listitem><para><emphasis>installed-package-sizes.txt:</emphasis> | ||
| 530 | A list of installed packages ordered by size. | ||
| 531 | </para></listitem> | ||
| 532 | <listitem><para><emphasis>installed-packages.txt:</emphasis> | ||
| 533 | A list of installed packages with fuill package | ||
| 534 | filenames.</para></listitem> | ||
| 535 | </itemizedlist> | ||
| 536 | <note> | ||
| 537 | Installed package information is able to be gathered and | ||
| 538 | produced even if package management is disabled for the final | ||
| 539 | image. | ||
| 540 | </note> | ||
| 541 | </para> | ||
| 542 | |||
| 543 | <para> | ||
| 544 | Here is an example of <filename>image-info.txt</filename>: | ||
| 545 | <literallayout class='monospaced'> | ||
| 546 | DISTRO = poky | ||
| 547 | DISTRO_VERSION = 1.1+snapshot-20120207 | ||
| 548 | USER_CLASSES = image-mklibs image-prelink | ||
| 549 | IMAGE_CLASSES = image_types | ||
| 550 | IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \ | ||
| 551 | package-management ssh-server-dropbear package-management | ||
| 552 | IMAGE_LINGUAS = en-us en-gb | ||
| 553 | IMAGE_INSTALL = task-core-boot task-base-extended | ||
| 554 | BAD_RECOMMENDATIONS = | ||
| 555 | ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; | ||
| 556 | IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; | ||
| 557 | IMAGESIZE = 171816 | ||
| 558 | </literallayout> | ||
| 559 | Other than <filename>IMAGESIZE</filename>, which is the | ||
| 560 | total size of the files in the image in Kbytes, the | ||
| 561 | name-value pairs are variables that may have influenced the | ||
| 562 | content of the image. | ||
| 563 | This information is often useful when you are trying to determine | ||
| 564 | why a change in the package or file listings has occurred. | ||
| 565 | </para> | ||
| 566 | </section> | ||
| 567 | |||
| 568 | <section id='using-build-history-to-gather-image-information-only'> | ||
| 569 | <title>Using Build History to Gather Image Information Only</title> | ||
| 570 | |||
| 571 | <para> | ||
| 572 | As you can see, build history produces image information, | ||
| 573 | including dependency graphs, so you can see why something | ||
| 574 | was pulled into the image. | ||
| 575 | If you are just interested in this information and not | ||
| 576 | interested in collecting history or any package information, | ||
| 577 | you can enable writing only image information without | ||
| 578 | any history by adding the following | ||
| 579 | to your <filename>conf/local.conf</filename> file found in the | ||
| 580 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | ||
| 581 | <literallayout class='monospaced'> | ||
| 582 | INHERIT += "buildhistory" | ||
| 583 | BUILDHISTORY_COMMIT = "0" | ||
| 584 | BUILDHISTORY_FEATURES = "image" | ||
| 585 | </literallayout> | ||
| 586 | </para> | ||
| 587 | </section> | ||
| 588 | |||
| 589 | <section id='examining-build-history-information'> | ||
| 590 | <title>Examining Build History Information</title> | ||
| 591 | |||
| 592 | <para> | ||
| 593 | You can examine build history output from the command line or | ||
| 594 | from a web interface. | ||
| 595 | </para> | ||
| 596 | |||
| 597 | <para> | ||
| 598 | To see any changes that have occurred (assuming you have | ||
| 599 | <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply | ||
| 600 | use any Git command that allows you to view the history of | ||
| 601 | a repository. | ||
| 602 | Here is one method: | ||
| 603 | <literallayout class='monospaced'> | ||
| 604 | $ git log -p | ||
| 605 | </literallayout> | ||
| 606 | You need to realize, however, that this method does show | ||
| 607 | changes that are not significant (e.g. a package's size | ||
| 608 | changing by a few bytes). | ||
| 609 | </para> | ||
| 610 | |||
| 611 | <para> | ||
| 612 | A command-line tool called <filename>buildhistory-diff</filename> | ||
| 613 | does exist though that queries the Git repository and prints just | ||
| 614 | the differences that might be significant in human-readable form. | ||
| 615 | Here is an example: | ||
| 616 | <literallayout class='monospaced'> | ||
| 617 | $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ | ||
| 618 | Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt): | ||
| 619 | /etc/anotherpkg.conf was added | ||
| 620 | /sbin/anotherpkg was added | ||
| 621 | * (installed-package-names.txt): | ||
| 622 | * anotherpkg was added | ||
| 623 | Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt): | ||
| 624 | anotherpkg was added | ||
| 625 | packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras" | ||
| 626 | * PR changed from "r0" to "r1" | ||
| 627 | * PV changed from "0.1.10" to "0.1.12" | ||
| 628 | packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%) | ||
| 629 | * PR changed from "r0" to "r1" | ||
| 630 | * PV changed from "0.1.10" to "0.1.12" | ||
| 631 | </literallayout> | ||
| 632 | </para> | ||
| 633 | |||
| 634 | <para> | ||
| 635 | To see changes to the build history using a web interface, follow | ||
| 636 | the instruction in the <filename>README</filename> file here. | ||
| 637 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>. | ||
| 638 | </para> | ||
| 639 | |||
| 640 | <para> | ||
| 641 | Here is a sample screenshot of the interface: | ||
| 642 | <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" /> | ||
| 643 | </para> | ||
| 644 | </section> | ||
| 645 | </section> | ||
| 646 | </section> | ||
| 647 | |||
| 648 | </chapter> | ||
| 649 | <!-- | ||
| 650 | vim: expandtab tw=80 ts=4 | ||
| 651 | --> | ||
