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