summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/usingpoky.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/usingpoky.xml')
-rw-r--r--documentation/ref-manual/usingpoky.xml882
1 files changed, 882 insertions, 0 deletions
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
new file mode 100644
index 0000000000..a8a6f3b92a
--- /dev/null
+++ b/documentation/ref-manual/usingpoky.xml
@@ -0,0 +1,882 @@
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
31 environment by sourcing an environment setup script
32 (i.e.
33 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
34 or
35 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
36 Here is an example:
37 <literallayout class='monospaced'>
38 $ source &OE_INIT_FILE; [&lt;build_dir&gt;]
39 </literallayout>
40 </para>
41
42 <para>
43 The <filename>build_dir</filename> argument is optional and specifies the directory the
44 OpenEmbedded build system uses for the build -
45 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
46 If you do not specify a Build Directory, it defaults to a directory
47 named <filename>build</filename> in your current working directory.
48 A common practice is to use a different Build Directory for different targets.
49 For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
50 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
51 </para>
52
53 <para>
54 Once the build environment is set up, you can build a target using:
55 <literallayout class='monospaced'>
56 $ bitbake &lt;target&gt;
57 </literallayout>
58 </para>
59
60 <para>
61 The <filename>target</filename> is the name of the recipe you want to build.
62 Common targets are the images in <filename>meta/recipes-core/images</filename>,
63 <filename>meta/recipes-sato/images</filename>, etc. all found in the
64 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
65 Or, the target can be the name of a recipe for a specific piece of software such as
66 BusyBox.
67 For more details about the images the OpenEmbedded build system supports, see the
68 "<link linkend="ref-images">Images</link>" chapter.
69 </para>
70
71 <note>
72 Building an image without GNU General Public License Version 3 (GPLv3) components
73 is supported for only minimal and base images.
74 See the "<link linkend='ref-images'>Images</link>" chapter for more information.
75 </note>
76 </section>
77
78 <section id='building-an-image-using-gpl-components'>
79 <title>Building an Image Using GPL Components</title>
80
81 <para>
82 When building an image using GPL components, you need to maintain your original
83 settings and not switch back and forth applying different versions of the GNU
84 General Public License.
85 If you rebuild using different versions of GPL, dependency errors might occur
86 due to some components not being rebuilt.
87 </para>
88 </section>
89</section>
90
91<section id='usingpoky-install'>
92 <title>Installing and Using the Result</title>
93
94 <para>
95 Once an image has been built, it often needs to be installed.
96 The images and kernels built by the OpenEmbedded build system are placed in the
97 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
98 <filename class="directory">tmp/deploy/images</filename>.
99 For information on how to run pre-built images such as <filename>qemux86</filename>
100 and <filename>qemuarm</filename>, see the
101 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
102 section in the Yocto Project Quick Start.
103 For information about how to install these images, see the documentation for your
104 particular board or machine.
105 </para>
106</section>
107
108<section id='usingpoky-debugging'>
109 <title>Debugging Build Failures</title>
110
111 <para>
112 The exact method for debugging build failures depends on the nature of
113 the problem and on the system's area from which the bug originates.
114 Standard debugging practices such as comparison against the last
115 known working version with examination of the changes and the
116 re-application of steps to identify the one causing the problem are
117 valid for the Yocto Project just as they are for any other system.
118 Even though it is impossible to detail every possible potential failure,
119 this section provides some general tips to aid in debugging.
120 </para>
121
122 <para>
123 A useful feature for debugging is the error reporting tool.
124 Configuring the Yocto Project to use this tool causes the
125 OpenEmbedded build system to produce error reporting commands as
126 part of the console output.
127 You can enter the commands after the build completes
128 to log error information
129 into a common database, that can help you figure out what might be
130 going wrong.
131 For information on how to enable and use this feature, see the
132 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>Using the Error Reporting Tool</ulink>"
133 section in the Yocto Project Development Manual.
134 </para>
135
136 <para>
137 For discussions on debugging, see the
138 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
139 and
140 "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working within Eclipse</ulink>"
141 sections in the Yocto Project Development Manual.
142 </para>
143
144 <note>
145 The remainder of this section presents many examples of the
146 <filename>bitbake</filename> command.
147 You can learn about BitBake by reading the
148 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
149 </note>
150
151
152 <section id='usingpoky-debugging-taskfailures'>
153 <title>Task Failures</title>
154
155 <para>The log file for shell tasks is available in
156 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
157 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
158 machine (<filename>qemux86</filename>) might be
159 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>.
160 To see what
161 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
162 runs to generate that log, look at the corresponding
163 <filename>run.do_taskname.pid</filename> file located in the same directory.
164 </para>
165
166 <para>
167 Presently, the output from Python tasks is sent directly to the console.
168 </para>
169 </section>
170
171 <section id='usingpoky-debugging-taskrunning'>
172 <title>Running Specific Tasks</title>
173
174 <para>
175 Any given package consists of a set of tasks.
176 The standard BitBake behavior in most cases is: <filename>fetch</filename>,
177 <filename>unpack</filename>,
178 <filename>patch</filename>, <filename>configure</filename>,
179 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
180 <filename>package_write</filename>, and <filename>build</filename>.
181 The default task is <filename>build</filename> and any tasks on which it depends
182 build first.
183 Some tasks, such as <filename>devshell</filename>, are not part of the
184 default build chain.
185 If you wish to run a task that is not part of the default build chain, you can use the
186 <filename>-c</filename> option in BitBake.
187 Here is an example:
188 <literallayout class='monospaced'>
189 $ bitbake matchbox-desktop -c devshell
190 </literallayout>
191 </para>
192
193 <para>
194 If you wish to rerun a task, use the <filename>-f</filename> force
195 option.
196 For example, the following sequence forces recompilation after
197 changing files in the work directory.
198 <literallayout class='monospaced'>
199 $ bitbake matchbox-desktop
200 .
201 .
202 [make some changes to the source code in the work directory]
203 .
204 .
205 $ bitbake matchbox-desktop -c compile -f
206 $ bitbake matchbox-desktop
207 </literallayout>
208 </para>
209
210 <para>
211 This sequence first builds and then recompiles
212 <filename>matchbox-desktop</filename>.
213 The last command reruns all tasks (basically the packaging tasks) after the compile.
214 BitBake recognizes that the <filename>compile</filename> task was rerun and therefore
215 understands that the other tasks also need to be run again.
216 </para>
217
218 <para>
219 You can view a list of tasks in a given package by running the
220 <filename>listtasks</filename> task as follows:
221 <literallayout class='monospaced'>
222 $ bitbake matchbox-desktop -c listtasks
223 </literallayout>
224 The results appear as output to the console and are also in the
225 file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
226 </para>
227 </section>
228
229 <section id='usingpoky-debugging-dependencies'>
230 <title>Dependency Graphs</title>
231
232 <para>
233 Sometimes it can be hard to see why BitBake wants to build
234 other packages before building a given package you have specified.
235 The <filename>bitbake -g &lt;targetname&gt;</filename> command
236 creates the <filename>pn-buildlist</filename>,
237 <filename>pn-depends.dot</filename>,
238 <filename>package-depends.dot</filename>, and
239 <filename>task-depends.dot</filename> files in the current
240 directory.
241 These files show what will be built and the package and task
242 dependencies, which are useful for debugging problems.
243 You can use the
244 <filename>bitbake -g -u depexp &lt;targetname&gt;</filename>
245 command to display the results in a more human-readable form.
246 </para>
247 </section>
248
249 <section id='usingpoky-debugging-bitbake'>
250 <title>General BitBake Problems</title>
251
252 <para>
253 You can see debug output from BitBake by using the <filename>-D</filename> option.
254 The debug output gives more information about what BitBake
255 is doing and the reason behind it.
256 Each <filename>-D</filename> option you use increases the logging level.
257 The most common usage is <filename>-DDD</filename>.
258 </para>
259
260 <para>
261 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
262 BitBake chose a certain version of a package or why BitBake
263 picked a certain provider.
264 This command could also help you in a situation where you think BitBake did something
265 unexpected.
266 </para>
267 </section>
268
269 <section id='development-host-system-issues'>
270 <title>Development Host System Issues</title>
271
272 <para>
273 Sometimes issues on the host development system can cause your
274 build to fail.
275 Following are known, host-specific problems.
276 Be sure to always consult the
277 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
278 for a look at all release-related issues.
279 <itemizedlist>
280 <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>:
281 If your development host system has the unpatched
282 <filename>GNU Make 3.82</filename>,
283 the <filename>do_install</filename> task
284 fails for <filename>eglibc-initial</filename> during the
285 build.</para>
286 <para>Typically, every distribution that ships
287 <filename>GNU Make 3.82</filename> as
288 the default already has the patched version.
289 However, some distributions, such as Debian, have
290 <filename>GNU Make 3.82</filename> as an option, which
291 is unpatched.
292 You will see this error on these types of distributions.
293 Switch to <filename>GNU Make 3.81</filename> or patch
294 your <filename>make</filename> to solve the problem.
295 </para></listitem>
296 </itemizedlist>
297 </para>
298 </section>
299
300 <section id='usingpoky-debugging-buildfile'>
301 <title>Building with No Dependencies</title>
302 <para>
303 To build a specific recipe (<filename>.bb</filename> file),
304 you can use the following command form:
305 <literallayout class='monospaced'>
306 $ bitbake -b &lt;somepath/somerecipe.bb&gt;
307 </literallayout>
308 This command form does not check for dependencies.
309 Consequently, you should use it
310 only when you know existing dependencies have been met.
311 <note>
312 You can also specify fragments of the filename.
313 In this case, BitBake checks for a unique match.
314 </note>
315 </para>
316 </section>
317
318 <section id='usingpoky-debugging-variables'>
319 <title>Variables</title>
320 <para>
321 You can use the <filename>-e</filename> BitBake option to
322 display the parsing environment for a configuration.
323 The following displays the general parsing environment:
324 <literallayout class='monospaced'>
325 $ bitbake -e
326 </literallayout>
327 This next example shows the parsing environment for a specific
328 recipe:
329 <literallayout class='monospaced'>
330 $ bitbake -e &lt;recipename&gt;
331 </literallayout>
332 </para>
333 </section>
334
335 <section id='recipe-logging-mechanisms'>
336 <title>Recipe Logging Mechanisms</title>
337 <para>
338 Best practices exist while writing recipes that both log build progress and
339 act on build conditions such as warnings and errors.
340 Both Python and Bash language bindings exist for the logging mechanism:
341 <itemizedlist>
342 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
343 supports several loglevels: <filename>bb.fatal</filename>,
344 <filename>bb.error</filename>, <filename>bb.warn</filename>,
345 <filename>bb.note</filename>, <filename>bb.plain</filename>,
346 and <filename>bb.debug</filename>.</para></listitem>
347 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
348 of loglevels exist and are accessed with a similar syntax:
349 <filename>bbfatal</filename>, <filename>bberror</filename>,
350 <filename>bbwarn</filename>, <filename>bbnote</filename>,
351 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
352 </itemizedlist>
353 </para>
354
355 <para>
356 For guidance on how logging is handled in both Python and Bash recipes, see the
357 <filename>logging.bbclass</filename> file in the
358 <filename>meta/classes</filename> folder of the
359 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
360 </para>
361
362 <section id='logging-with-python'>
363 <title>Logging With Python</title>
364 <para>
365 When creating recipes using Python and inserting code that handles build logs,
366 keep in mind the goal is to have informative logs while keeping the console as
367 "silent" as possible.
368 Also, if you want status messages in the log, use the "debug" loglevel.
369 </para>
370
371 <para>
372 Following is an example written in Python.
373 The code handles logging for a function that determines the number of tasks
374 needed to be run:
375 <literallayout class='monospaced'>
376 python do_listtasks() {
377 bb.debug(2, "Starting to figure out the task list")
378 if noteworthy_condition:
379 bb.note("There are 47 tasks to run")
380 bb.debug(2, "Got to point xyz")
381 if warning_trigger:
382 bb.warn("Detected warning_trigger, this might be a problem later.")
383 if recoverable_error:
384 bb.error("Hit recoverable_error, you really need to fix this!")
385 if fatal_error:
386 bb.fatal("fatal_error detected, unable to print the task list")
387 bb.plain("The tasks present are abc")
388 bb.debug(2, "Finished figuring out the tasklist")
389 }
390 </literallayout>
391 </para>
392 </section>
393
394 <section id='logging-with-bash'>
395 <title>Logging With Bash</title>
396 <para>
397 When creating recipes using Bash and inserting code that handles build
398 logs, you have the same goals - informative with minimal console output.
399 The syntax you use for recipes written in Bash is similar to that of
400 recipes written in Python described in the previous section.
401 </para>
402
403 <para>
404 Following is an example written in Bash.
405 The code logs the progress of the <filename>do_my_function</filename> function.
406 <literallayout class='monospaced'>
407 do_my_function() {
408 bbdebug 2 "Running do_my_function"
409 if [ exceptional_condition ]; then
410 bbnote "Hit exceptional_condition"
411 fi
412 bbdebug 2 "Got to point xyz"
413 if [ warning_trigger ]; then
414 bbwarn "Detected warning_trigger, this might cause a problem later."
415 fi
416 if [ recoverable_error ]; then
417 bberror "Hit recoverable_error, correcting"
418 fi
419 if [ fatal_error ]; then
420 bbfatal "fatal_error detected"
421 fi
422 bbdebug 2 "Completed do_my_function"
423 }
424 </literallayout>
425 </para>
426 </section>
427 </section>
428
429 <section id='usingpoky-debugging-others'>
430 <title>Other Tips</title>
431
432 <para>
433 Here are some other tips that you might find useful:
434 <itemizedlist>
435 <listitem><para>When adding new packages, it is worth watching for
436 undesirable items making their way into compiler command lines.
437 For example, you do not want references to local system files like
438 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
439 </para></listitem>
440 <listitem><para>If you want to remove the <filename>psplash</filename>
441 boot splashscreen,
442 add <filename>psplash=false</filename> to the kernel command line.
443 Doing so prevents <filename>psplash</filename> from loading
444 and thus allows you to see the console.
445 It is also possible to switch out of the splashscreen by
446 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
447 </para></listitem>
448 </itemizedlist>
449 </para>
450 </section>
451</section>
452
453<section id='maintaining-build-output-quality'>
454 <title>Maintaining Build Output Quality</title>
455
456 <para>
457 Many factors can influence the quality of a build.
458 For example, if you upgrade a recipe to use a new version of an upstream software
459 package or you experiment with some new configuration options, subtle changes
460 can occur that you might not detect until later.
461 Consider the case where your recipe is using a newer version of an upstream package.
462 In this case, a new version of a piece of software might introduce an optional
463 dependency on another library, which is auto-detected.
464 If that library has already been built when the software is building,
465 the software will link to the built library and that library will be pulled
466 into your image along with the new software even if you did not want the
467 library.
468 </para>
469
470 <para>
471 The
472 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
473 class exists to help you maintain
474 the quality of your build output.
475 You can use the class to highlight unexpected and possibly unwanted
476 changes in the build output.
477 When you enable build history, it records information about the contents of
478 each package and image and then commits that information to a local Git
479 repository where you can examine the information.
480 </para>
481
482 <para>
483 The remainder of this section describes the following:
484 <itemizedlist>
485 <listitem><para>How you can enable and disable
486 build history</para></listitem>
487 <listitem><para>How to understand what the build history contains
488 </para></listitem>
489 <listitem><para>How to limit the information used for build history
490 </para></listitem>
491 <listitem><para>How to examine the build history from both a
492 command-line and web interface</para></listitem>
493 </itemizedlist>
494 </para>
495
496 <section id='enabling-and-disabling-build-history'>
497 <title>Enabling and Disabling Build History</title>
498
499 <para>
500 Build history is disabled by default.
501 To enable it, add the following <filename>INHERIT</filename>
502 statement and set the
503 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
504 variable to "1" at the end of your
505 <filename>conf/local.conf</filename> file found in the
506 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
507 <literallayout class='monospaced'>
508 INHERIT += "buildhistory"
509 BUILDHISTORY_COMMIT = "1"
510 </literallayout>
511 Enabling build history as previously described
512 causes the build process to collect build
513 output information and commit it to a local
514 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
515 <note>
516 Enabling build history increases your build times slightly,
517 particularly for images, and increases the amount of disk
518 space used during the build.
519 </note>
520 </para>
521
522 <para>
523 You can disable build history by removing the previous statements
524 from your <filename>conf/local.conf</filename> file.
525 </para>
526 </section>
527
528 <section id='understanding-what-the-build-history-contains'>
529 <title>Understanding What the Build History Contains</title>
530
531 <para>
532 Build history information is kept in
533 <filename>$</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>/buildhistory</filename>
534 in the Build Directory as defined by the
535 <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link>
536 variable.
537 The following is an example abbreviated listing:
538 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
539 </para>
540
541 <para>
542 At the top level, there is a <filename>metadata-revs</filename> file
543 that lists the revisions of the repositories for the layers enabled
544 when the build was produced.
545 The rest of the data splits into separate
546 <filename>packages</filename>, <filename>images</filename> and
547 <filename>sdk</filename> directories, the contents of which are
548 described below.
549 </para>
550
551 <section id='build-history-package-information'>
552 <title>Build History Package Information</title>
553
554 <para>
555 The history for each package contains a text file that has
556 name-value pairs with information about the package.
557 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
558 contains the following:
559 <literallayout class='monospaced'>
560 PV = 1.19.3
561 PR = r3
562 RDEPENDS = update-rc.d eglibc (>= 2.13)
563 RRECOMMENDS = busybox-syslog busybox-udhcpc
564 PKGSIZE = 564701
565 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
566 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
567 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
568 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
569 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
570 </literallayout>
571 Most of these name-value pairs correspond to variables used
572 to produce the package.
573 The exceptions are <filename>FILELIST</filename>, which is the
574 actual list of files in the package, and
575 <filename>PKGSIZE</filename>, which is the total size of files
576 in the package in bytes.
577 </para>
578
579 <para>
580 There is also a file corresponding to the recipe from which the
581 package came (e.g.
582 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
583 <literallayout class='monospaced'>
584 PV = 1.19.3
585 PR = r3
586 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
587 virtual/libc update-rc.d-native
588 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
589 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
590 busybox-staticdev busybox-locale
591 </literallayout>
592 </para>
593
594 <para>
595 Finally, for those recipes fetched from a version control
596 system (e.g., Git), a file exists that lists source revisions
597 that are specified in the recipe and lists the actual revisions
598 used during the build.
599 Listed and actual revisions might differ when
600 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
601 is set to
602 <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>.
603 Here is an example assuming
604 <filename>buildhistory/packages/emenlow-poky-linux/linux-yocto/latest_srcrev</filename>):
605 <literallayout class='monospaced'>
606 # SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
607 SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
608 # SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
609 SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
610 # SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
611 SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
612 </literallayout>
613 You can use the <filename>buildhistory-collect-srcrevs</filename>
614 command to collect the stored <filename>SRCREV</filename> values
615 from build history and report them in a format suitable for use in
616 global configuration (e.g., <filename>local.conf</filename>
617 or a distro include file) to override floating
618 <filename>AUTOREV</filename> values to a fixed set of revisions.
619 Here is some example output from this command:
620 <literallayout class='monospaced'>
621 # emenlow-poky-linux
622 SRCREV_machine_pn-linux-yocto = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
623 SRCREV_emgd_pn-linux-yocto = "caea08c988e0f41103bbe18eafca20348f95da02"
624 SRCREV_meta_pn-linux-yocto = "c2ed0f16fdec628242a682897d5d86df4547cf24"
625 # core2-poky-linux
626 SRCREV_pn-kmod = "62081c0f68905b22f375156d4532fd37fa5c8d33"
627 SRCREV_pn-blktrace = "d6918c8832793b4205ed3bfede78c2f915c23385"
628 SRCREV_pn-opkg = "649"
629 </literallayout>
630 <note>
631 Here are some notes on using the
632 <filename>buildhistory-collect-srcrevs</filename> command:
633 <itemizedlist>
634 <listitem><para>By default, only values where the
635 <filename>SRCREV</filename> was
636 not hardcoded (usually when <filename>AUTOREV</filename>
637 was used) are reported.
638 Use the <filename>-a</filename> option to see all
639 <filename>SRCREV</filename> values.
640 </para></listitem>
641 <listitem><para>The output statements might not have any effect
642 if overrides are applied elsewhere in the build system
643 configuration.
644 Use the <filename>-f</filename> option to add the
645 <filename>forcevariable</filename> override to each output line
646 if you need to work around this restriction.
647 </para></listitem>
648 <listitem><para>The script does apply special handling when
649 building for multiple machines.
650 However, the script does place a
651 comment before each set of values that specifies
652 which triplet to which they belong as shown above
653 (e.g., <filename>emenlow-poky-linux</filename>).
654 </para></listitem>
655 </itemizedlist>
656 </note>
657 </para>
658 </section>
659
660 <section id='build-history-image-information'>
661 <title>Build History Image Information</title>
662
663 <para>
664 The files produced for each image are as follows:
665 <itemizedlist>
666 <listitem><para><filename>image-files:</filename>
667 A directory containing selected files from the root
668 filesystem.
669 The files are defined by
670 <link linkend='var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></link>.
671 </para></listitem>
672 <listitem><para><filename>build-id:</filename>
673 Human-readable information about the build configuration
674 and metadata source revisions.</para></listitem>
675 <listitem><para><filename>*.dot:</filename>
676 Dependency graphs for the image that are
677 compatible with <filename>graphviz</filename>.
678 </para></listitem>
679 <listitem><para><filename>files-in-image.txt:</filename>
680 A list of files in the image with permissions,
681 owner, group, size, and symlink information.
682 </para></listitem>
683 <listitem><para><filename>image-info.txt:</filename>
684 A text file containing name-value pairs with information
685 about the image.
686 See the following listing example for more information.
687 </para></listitem>
688 <listitem><para><filename>installed-package-names.txt:</filename>
689 A list of installed packages by name only.</para></listitem>
690 <listitem><para><filename>installed-package-sizes.txt:</filename>
691 A list of installed packages ordered by size.
692 </para></listitem>
693 <listitem><para><filename>installed-packages.txt:</filename>
694 A list of installed packages with full package
695 filenames.</para></listitem>
696 </itemizedlist>
697 <note>
698 Installed package information is able to be gathered and
699 produced even if package management is disabled for the final
700 image.
701 </note>
702 </para>
703
704 <para>
705 Here is an example of <filename>image-info.txt</filename>:
706 <literallayout class='monospaced'>
707 DISTRO = poky
708 DISTRO_VERSION = 1.1+snapshot-20120207
709 USER_CLASSES = image-mklibs image-prelink
710 IMAGE_CLASSES = image_types
711 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
712 package-management ssh-server-dropbear package-management
713 IMAGE_LINGUAS = en-us en-gb
714 IMAGE_INSTALL = task-core-boot task-base-extended
715 BAD_RECOMMENDATIONS =
716 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
717 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
718 IMAGESIZE = 171816
719 </literallayout>
720 Other than <filename>IMAGESIZE</filename>, which is the
721 total size of the files in the image in Kbytes, the
722 name-value pairs are variables that may have influenced the
723 content of the image.
724 This information is often useful when you are trying to determine
725 why a change in the package or file listings has occurred.
726 </para>
727 </section>
728
729 <section id='using-build-history-to-gather-image-information-only'>
730 <title>Using Build History to Gather Image Information Only</title>
731
732 <para>
733 As you can see, build history produces image information,
734 including dependency graphs, so you can see why something
735 was pulled into the image.
736 If you are just interested in this information and not
737 interested in collecting specific package or SDK information,
738 you can enable writing only image information without
739 any history by adding the following to your
740 <filename>conf/local.conf</filename> file found in the
741 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
742 <literallayout class='monospaced'>
743 INHERIT += "buildhistory"
744 BUILDHISTORY_COMMIT = "0"
745 BUILDHISTORY_FEATURES = "image"
746 </literallayout>
747 Here, you set the
748 <link linkend='var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></link>
749 variable to use the image feature only.
750 </para>
751 </section>
752
753 <section id='build-history-sdk-information'>
754 <title>Build History SDK Information</title>
755 <para>
756 Build history collects similar information on the contents
757 of SDKs (e.g. <filename>meta-toolchain</filename>
758 or <filename>bitbake -c populate_sdk imagename</filename>)
759 as compared to information it collects for images.
760 The following list shows the files produced for each SDK:
761 <itemizedlist>
762 <listitem><para><filename>files-in-sdk.txt:</filename>
763 A list of files in the SDK with permissions,
764 owner, group, size, and symlink information.
765 This list includes both the host and target parts
766 of the SDK.
767 </para></listitem>
768 <listitem><para><filename>sdk-info.txt:</filename>
769 A text file containing name-value pairs with information
770 about the SDK.
771 See the following listing example for more information.
772 </para></listitem>
773 <listitem><para>The following information appears under
774 each of the <filename>host</filename>
775 and <filename>target</filename> directories
776 for the portions of the SDK that run on the host and
777 on the target, respectively:
778 <itemizedlist>
779 <listitem><para><filename>depends.dot:</filename>
780 Dependency graph for the SDK that is
781 compatible with <filename>graphviz</filename>.
782 </para></listitem>
783 <listitem><para><filename>installed-package-names.txt:</filename>
784 A list of installed packages by name only.
785 </para></listitem>
786 <listitem><para><filename>installed-package-sizes.txt:</filename>
787 A list of installed packages ordered by size.
788 </para></listitem>
789 <listitem><para><filename>installed-packages.txt:</filename>
790 A list of installed packages with full package
791 filenames.</para></listitem>
792 </itemizedlist>
793 </para></listitem>
794 </itemizedlist>
795 </para>
796
797 <para>
798 Here is an example of <filename>sdk-info.txt</filename>:
799 <literallayout class='monospaced'>
800 DISTRO = poky
801 DISTRO_VERSION = 1.3+snapshot-20130327
802 SDK_NAME = poky-eglibc-i686-arm
803 SDK_VERSION = 1.3+snapshot
804 SDKMACHINE =
805 SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
806 BAD_RECOMMENDATIONS =
807 SDKSIZE = 352712
808 </literallayout>
809 Other than <filename>SDKSIZE</filename>, which is the
810 total size of the files in the SDK in Kbytes, the
811 name-value pairs are variables that might have influenced the
812 content of the SDK.
813 This information is often useful when you are trying to
814 determine why a change in the package or file listings
815 has occurred.
816 </para>
817 </section>
818
819 <section id='examining-build-history-information'>
820 <title>Examining Build History Information</title>
821
822 <para>
823 You can examine build history output from the command line or
824 from a web interface.
825 </para>
826
827 <para>
828 To see any changes that have occurred (assuming you have
829 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT = "1"</filename></link>),
830 you can simply
831 use any Git command that allows you to view the history of
832 a repository.
833 Here is one method:
834 <literallayout class='monospaced'>
835 $ git log -p
836 </literallayout>
837 You need to realize, however, that this method does show
838 changes that are not significant (e.g. a package's size
839 changing by a few bytes).
840 </para>
841
842 <para>
843 A command-line tool called <filename>buildhistory-diff</filename>
844 does exist, though, that queries the Git repository and prints just
845 the differences that might be significant in human-readable form.
846 Here is an example:
847 <literallayout class='monospaced'>
848 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
849 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
850 /etc/anotherpkg.conf was added
851 /sbin/anotherpkg was added
852 * (installed-package-names.txt):
853 * anotherpkg was added
854 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
855 anotherpkg was added
856 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
857 * PR changed from "r0" to "r1"
858 * PV changed from "0.1.10" to "0.1.12"
859 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
860 * PR changed from "r0" to "r1"
861 * PV changed from "0.1.10" to "0.1.12"
862 </literallayout>
863 </para>
864
865 <para>
866 To see changes to the build history using a web interface, follow
867 the instruction in the <filename>README</filename> file here.
868 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
869 </para>
870
871 <para>
872 Here is a sample screenshot of the interface:
873 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
874 </para>
875 </section>
876 </section>
877</section>
878
879</chapter>
880<!--
881vim: expandtab tw=80 ts=4
882-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-16 13:25:18 +0000