summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/TODO11
-rw-r--r--documentation/ref-manual/closer-look.xml1224
-rw-r--r--documentation/ref-manual/examples/hello-autotools/hello_2.3.bb8
-rw-r--r--documentation/ref-manual/examples/hello-single/files/helloworld.c8
-rw-r--r--documentation/ref-manual/examples/hello-single/hello.bb17
-rw-r--r--documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb14
-rw-r--r--documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb15
-rw-r--r--documentation/ref-manual/faq.xml710
-rw-r--r--documentation/ref-manual/figures/analysis-for-package-splitting.pngbin0 -> 63291 bytes
-rw-r--r--documentation/ref-manual/figures/buildhistory-web.pngbin0 -> 49966 bytes
-rw-r--r--documentation/ref-manual/figures/buildhistory.pngbin0 -> 42532 bytes
-rw-r--r--documentation/ref-manual/figures/configuration-compile-autoreconf.pngbin0 -> 46080 bytes
-rw-r--r--documentation/ref-manual/figures/cross-development-toolchains.pngbin0 -> 59275 bytes
-rw-r--r--documentation/ref-manual/figures/image-generation.pngbin0 -> 47713 bytes
-rw-r--r--documentation/ref-manual/figures/images.pngbin0 -> 22926 bytes
-rw-r--r--documentation/ref-manual/figures/layer-input.pngbin0 -> 45856 bytes
-rw-r--r--documentation/ref-manual/figures/package-feeds.pngbin0 -> 27711 bytes
-rw-r--r--documentation/ref-manual/figures/patching.pngbin0 -> 42523 bytes
-rw-r--r--documentation/ref-manual/figures/poky-title.pngbin0 -> 11592 bytes
-rw-r--r--documentation/ref-manual/figures/sdk-generation.pngbin0 -> 45456 bytes
-rw-r--r--documentation/ref-manual/figures/sdk.pngbin0 -> 20074 bytes
-rw-r--r--documentation/ref-manual/figures/source-fetching.pngbin0 -> 38860 bytes
-rw-r--r--documentation/ref-manual/figures/source-input.pngbin0 -> 39872 bytes
-rw-r--r--documentation/ref-manual/figures/user-configuration.pngbin0 -> 23687 bytes
-rw-r--r--documentation/ref-manual/figures/yocto-environment-ref.pngbin0 -> 83206 bytes
-rw-r--r--documentation/ref-manual/introduction.xml444
-rw-r--r--documentation/ref-manual/migration.xml1089
-rw-r--r--documentation/ref-manual/ref-bitbake.xml432
-rw-r--r--documentation/ref-manual/ref-classes.xml1104
-rw-r--r--documentation/ref-manual/ref-features.xml334
-rw-r--r--documentation/ref-manual/ref-images.xml150
-rw-r--r--documentation/ref-manual/ref-manual-customization.xsl11
-rw-r--r--documentation/ref-manual/ref-manual-eclipse-customization.xsl27
-rw-r--r--documentation/ref-manual/ref-manual.xml138
-rw-r--r--documentation/ref-manual/ref-structure.xml953
-rw-r--r--documentation/ref-manual/ref-style.css979
-rw-r--r--documentation/ref-manual/ref-variables.xml5888
-rw-r--r--documentation/ref-manual/ref-varlocality.xml196
-rw-r--r--documentation/ref-manual/resources.xml128
-rw-r--r--documentation/ref-manual/technical-details.xml1335
-rw-r--r--documentation/ref-manual/usingpoky.xml848
41 files changed, 16063 insertions, 0 deletions
diff --git a/documentation/ref-manual/TODO b/documentation/ref-manual/TODO
new file mode 100644
index 0000000000..ee0db977cc
--- /dev/null
+++ b/documentation/ref-manual/TODO
@@ -0,0 +1,11 @@
1Handbook Todo List:
2
3 * Document adding a new IMAGE_FEATURE to the customising images section
4 * Add instructions about using zaurus/openmoko emulation
5 * Add component overview/block diagrams
6 * Software Deevelopment intro should mention its software development for
7 intended target and could be a different arch etc and thus special case.
8 * Expand insane.bbclass documentation to cover tests
9 * Document remaining classes (see list in ref-classes)
10 * Document formfactor
11
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
new file mode 100644
index 0000000000..25c03e0a52
--- /dev/null
+++ b/documentation/ref-manual/closer-look.xml
@@ -0,0 +1,1224 @@
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='closer-look'>
6<title>A Closer Look at the Yocto Project Development Environment</title>
7
8 <para>
9 This chapter takes a more detailed look at the Yocto Project
10 development environment.
11 The following diagram represents the development environment at a
12 high level.
13 The remainder of this chapter expands on the fundamental input, output,
14 process, and
15 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>) blocks
16 in the Yocto Project development environment.
17 </para>
18
19 <para id='general-yocto-environment-figure'>
20 <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
21 </para>
22
23 <para>
24 The generalized Yocto Project Development Environment consists of
25 several functional areas:
26 <itemizedlist>
27 <listitem><para><emphasis>User Configuration:</emphasis>
28 Metadata you can use to control the build process.
29 </para></listitem>
30 <listitem><para><emphasis>Metadata Layers:</emphasis>
31 Various layers that provide software, machine, and
32 distro Metadata.</para></listitem>
33 <listitem><para><emphasis>Source Files:</emphasis>
34 Upstream releases, local projects, and SCMs.</para></listitem>
35 <listitem><para><emphasis>Build System:</emphasis>
36 Processes under the control of BitBake.
37 This block expands on how BitBake fetches source, applies
38 patches, completes compilation, analyzes output for package
39 generation, creates and tests packages, generates images, and
40 generates cross-development tools.</para></listitem>
41 <listitem><para><emphasis>Package Feeds:</emphasis>
42 Directories containing output packages (rpm, deb or ipk),
43 which are subsequently used in the construction of an image or
44 SDK, produced by the build system.
45 These feeds can also be copied and shared using a web server or
46 other means to facilitate extending or updating existing
47 images on devices at runtime if runtime package management is
48 enabled.</para></listitem>
49 <listitem><para><emphasis>Images:</emphasis>
50 Images produced by the development process.
51 Where do they go?
52 Can you mess with them (i.e. freely delete them or move them?).
53 </para></listitem>
54 <listitem><para><emphasis>Application Development SDK:</emphasis>
55 Cross-development tools that are produced along with an image
56 or separately with BitBake.</para></listitem>
57 </itemizedlist>
58 </para>
59
60 <section id="user-configuration">
61 <title>User Configuration</title>
62
63 <para>
64 User configuration helps define the build.
65 Through user configuration, you can tell BitBake the
66 target architecture for which you are building the image,
67 where to store downloaded source, and other build properties.
68 </para>
69
70 <para>
71 The following figure shows an expanded representation of the
72 "User Configuration" box of the
73 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
74 </para>
75
76 <para>
77 <imagedata fileref="figures/user-configuration.png" align="center" width="5.5in" depth="3.5in" />
78 </para>
79
80 <para>
81 BitBake needs some basic configuration files in order to complete
82 a build.
83 These files are <filename>*.conf</filename> files.
84 The minimally necessary ones reside as example files in the
85 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
86 For simplicity, this section refers to the Source Directory as
87 the "Poky Directory."
88 </para>
89
90 <para>
91 When you clone the <filename>poky</filename> Git repository or you
92 download and unpack a Yocto Project release, you can set up the
93 Source Directory to be named anything you want.
94 For this discussion, the cloned repository uses the default
95 name <filename>poky</filename>.
96 <note>
97 The Poky repository is primarily an aggregation of existing
98 repositories.
99 It is not a canonical upstream source.
100 </note>
101 </para>
102
103 <para>
104 The <filename>meta-yocto</filename> layer inside Poky contains
105 a <filename>conf</filename> directory that has example
106 configuration files.
107 These example files are used as a basis for creating actual
108 configuration files when you source the build environment
109 script
110 (i.e.
111 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
112 or
113 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
114 </para>
115
116 <para>
117 Sourcing the build environment script creates a
118 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
119 if one does not already exist.
120 BitBake uses the Build Directory for all its work during builds.
121 The Build Directory has a <filename>conf</filename> directory that
122 contains default versions of your <filename>local.conf</filename>
123 and <filename>bblayers.conf</filename> configuration files.
124 These default configuration files are created only if versions
125 do not already exist in the Build Directory at the time you
126 source the build environment setup script.
127 </para>
128
129 <para>
130 Because the Poky repository is fundamentally an aggregation of
131 existing repositories, some users might be familiar with running
132 the <filename>&OE_INIT_FILE;</filename> or
133 <filename>oe-init-build-env-memres</filename> script in the context
134 of separate OpenEmbedded-Core and BitBake repositories rather than a
135 single Poky repository.
136 This discussion assumes the script is executed from within a cloned
137 or unpacked version of Poky.
138 </para>
139
140 <para>
141 Depending on where the script is sourced, different sub-scripts
142 are called to set up the Build Directory (Yocto or OpenEmbedded).
143 Specifically, the script
144 <filename>scripts/oe-setup-builddir</filename> inside the
145 poky directory sets up the Build Directory and seeds the directory
146 (if necessary) with configuration files appropriate for the
147 Yocto Project development environment.
148 <note>
149 The <filename>scripts/oe-setup-builddir</filename> script
150 uses the <filename>$TEMPLATECONF</filename> variable to
151 determine which sample configuration files to locate.
152 </note>
153 </para>
154
155 <para>
156 The <filename>local.conf</filename> file provides many
157 basic variables that define a build environment.
158 Here is a list of a few.
159 To see the default configurations in a <filename>local.conf</filename>
160 file created by the build environment script, see the
161 <filename>local.conf.sample</filename> in the
162 <filename>meta-yocto</filename> layer:
163 <itemizedlist>
164 <listitem><para><emphasis>Parallelism Options:</emphasis>
165 Controlled by the
166 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
167 and
168 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
169 variables.</para></listitem>
170 <listitem><para><emphasis>Target Machine Selection:</emphasis>
171 Controlled by the
172 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
173 variable.</para></listitem>
174 <listitem><para><emphasis>Download Directory:</emphasis>
175 Controlled by the
176 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
177 variable.</para></listitem>
178 <listitem><para><emphasis>Shared State Directory:</emphasis>
179 Controlled by the
180 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
181 variable.</para></listitem>
182 <listitem><para><emphasis>Build Output:</emphasis>
183 Controlled by the
184 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
185 variable.</para></listitem>
186 </itemizedlist>
187 <note>
188 Configurations set in the <filename>conf/local.conf</filename>
189 file can also be set in the
190 <filename>conf/site.conf</filename> and
191 <filename>conf/auto.conf</filename> configuration files.
192 </note>
193 </para>
194
195 <para>
196 The <filename>bblayers.conf</filename> file tells BitBake what
197 layers you want considered during the build.
198 By default, the layers listed in this file include layers
199 minimally needed by the build system.
200 However, you must manually add any custom layers you have created.
201 You can find more information on working with the
202 <filename>bblayers.conf</filename> file in the
203 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
204 section in the Yocto Project Development Manual.
205 </para>
206
207 <para>
208 The files <filename>site.conf</filename> and
209 <filename>auto.conf</filename> are not created by the environment
210 initialization script.
211 If you want these configuration files, you must create them
212 yourself:
213 <itemizedlist>
214 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
215 You can use the <filename>conf/site.conf</filename>
216 configuration file to configure multiple build directories.
217 For example, suppose you had several build environments and
218 they shared some common features.
219 You can set these default build properties here.
220 A good example is perhaps the level of parallelism you want
221 to use through the
222 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
223 and
224 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
225 variables.</para>
226 <para>One useful scenario for using the
227 <filename>conf/site.conf</filename> file is to extend your
228 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
229 variable to include the path to a
230 <filename>conf/site.conf</filename>.
231 Then, when BitBake looks for Metadata using
232 <filename>BBPATH</filename>, it finds the
233 <filename>conf/site.conf</filename> file and applies your
234 common configurations found in the file.
235 To override configurations in a particular build directory,
236 alter the similar configurations within that build
237 directory's <filename>conf/local.conf</filename> file.
238 </para></listitem>
239 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
240 This file is not hand-created.
241 Rather, the file is usually created and written to by
242 an autobuilder.
243 The settings put into the file are typically the same as
244 you would find in the <filename>conf/local.conf</filename>
245 or the <filename>conf/site.conf</filename> files.
246 </para></listitem>
247 </itemizedlist>
248 </para>
249
250 <para>
251 You can edit all configuration files to further define
252 any particular build environment.
253 This process is represented by the "User Configuration Edits"
254 box in the figure.
255 </para>
256
257 <para>
258 When you launch your build with the
259 <filename>bitbake &lt;target&gt;</filename> command, BitBake
260 sorts out the configurations to ultimately define your build
261 environment.
262 </para>
263 </section>
264
265 <section id="metadata-machine-configuration-and-policy-configuration">
266 <title>Metadata, Machine Configuration, and Policy Configuration</title>
267
268 <para>
269 The previous section described the user configurations that
270 define the BitBake's global behavior.
271 This section takes a closer look at the layers the build system
272 uses to further control the build.
273 These layers provide Metadata for the software, machine, and
274 policy.
275 </para>
276
277 <para>
278 In general, three types of layer input exist:
279 <itemizedlist>
280 <listitem><para><emphasis>Policy Configuration:</emphasis>
281 Distribution Layers provide top-level or general
282 policies for the image or SDK being built.
283 For example, this layer would dictate whether BitBake
284 produces RPM or IPK packages.</para></listitem>
285 <listitem><para><emphasis>Machine Configuration:</emphasis>
286 Board Support Package (BSP) layers provide machine
287 configurations.
288 This type of information is specific to a particular
289 target architecture.</para></listitem>
290 <listitem><para><emphasis>Metadata:</emphasis>
291 Software layers contain user-supplied recipe files,
292 patches, and append files.
293 </para></listitem>
294 </itemizedlist>
295 </para>
296
297 <para>
298 The following figure shows an expanded representation of the
299 Metadata, Machine Configuration, and Policy Configuration input
300 (layers) boxes of the
301 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
302 </para>
303
304 <para>
305 <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
306 </para>
307
308 <para>
309 In general, all layers have a similar structure.
310 They all contain a licensing file
311 (e.g. <filename>COPYING</filename>) if the layer is to be
312 distributed, a <filename>README</filename> file as good practice
313 and especially if the layer is to be distributed, a
314 configuration directory, and recipe directories.
315 </para>
316
317 <para>
318 The Yocto Project has many layers that can be used.
319 You can see a web-interface listing of them on the
320 <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
321 page.
322 The layers are shown at the bottom categorized under
323 "Yocto Metadata Layers."
324 These layers are fundamentally a subset of the
325 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
326 which lists all layers provided by the OpenEmbedded community.
327 <note>
328 Layers exist in the Yocto Project Source Repositories that
329 cannot be found in the OpenEmbedded Metadata Index.
330 These layers are either deprecated or experimental in nature.
331 </note>
332 </para>
333
334 <para>
335 BitBake uses the <filename>conf/bblayers.conf</filename> file,
336 which is part of the user configuration, to find what layers it
337 should be using as part of the build.
338 </para>
339
340 <para>
341 For more information on layers, see the
342 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
343 section in the Yocto Project Development Manual.
344 </para>
345
346 <section id="distro-layer">
347 <title>Distro Layer</title>
348
349 <para>
350 The distribution layer provides policy configurations for your
351 distribution.
352 Best practices dictate that you isolate these types of
353 configurations into their own layer.
354 Settings you provide in
355 <filename>conf/&lt;distro&gt;.conf</filename> override similar
356 settings that BitBake finds in your
357 <filename>conf/local.conf</filename> file in the Build
358 Directory.
359 </para>
360
361 <para>
362 The following list provides some explanation and references
363 for what you typically find in the distribution layer:
364 <itemizedlist>
365 <listitem><para><emphasis>classes:</emphasis>
366 Class files (<filename>.bbclass</filename>) holds
367 common functionality that can be shared among
368 recipes in the distribution.
369 When your recipes inherit a class, they take on the
370 settings and functions for that class.
371 You can read more about class files in the
372 "<link linkend='ref-classes'>Classes</link>" section.
373 </para></listitem>
374 <listitem><para><emphasis>conf:</emphasis>
375 This area holds configuration files for the
376 layer (<filename>conf/layer.conf</filename>),
377 the distribution
378 (<filename>conf/distro/&lt;distro&gt;.conf</filename>),
379 and any distribution-wide include files.
380 </para></listitem>
381 <listitem><para><emphasis>recipes-*:</emphasis>
382 Recipes and append files that affect common
383 functionality across the distribution.
384 This area could include recipes and append files to
385 to add distribution-specific configuration,
386 initialization scripts, custom image recipes,
387 and so forth.</para></listitem>
388 </itemizedlist>
389 </para>
390 </section>
391
392 <section id="bsp-layer">
393 <title>BSP Layer</title>
394
395 <para>
396 The BSP Layer provides machine configurations.
397 Everything in this layer is specific to the machine for which
398 you are building the image or the SDK.
399 A common structure or form is defined for BSP layers.
400 You can learn more about this structure in the
401 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
402 <note>
403 In order for a BSP layer to be considered compliant with the
404 Yocto Project, it must meet some structural requirements.
405 </note>
406 </para>
407
408 <para>
409 The BSP Layer's configuration directory contains
410 configuration files for the machine
411 (<filename>conf/machine/&lt;machine&gt;.conf</filename>) and,
412 of course, the layer (<filename>conf/layer.conf</filename>).
413 </para>
414
415 <para>
416 The remainder of the layer is dedicated to specific recipes
417 by function: <filename>recipes-bsp</filename>,
418 <filename>recipes-core</filename>,
419 <filename>recipes-graphics</filename>, and
420 <filename>recipes-kernel</filename>.
421 Metadata can exist for multiple formfactors, graphics
422 support systems, and so forth.
423 <note>
424 While the figure shows several <filename>recipe-*</filename>
425 directories, not all these directories appear in all
426 BSP layers.
427 </note>
428 </para>
429 </section>
430
431 <section id="software-layer">
432 <title>Software Layer</title>
433
434 <para>
435 The software layer provides the Metadata for additional
436 software packages used during the build.
437 This layer does not include Metadata that is specific to the
438 distribution or the machine, which are found in their
439 respective layers.
440 </para>
441
442 <para>
443 This layer contains any new recipes that your project needs
444 in the form of recipe files.
445 </para>
446 </section>
447 </section>
448
449 <section id="sources-dev-environment">
450 <title>Sources</title>
451
452 <para>
453 In order for the OpenEmbedded build system to create an image or
454 any target, it must be able to access source files.
455 The
456 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
457 represents source files using the "Upstream Project Releases",
458 "Local Projects", and "SCMs (optional)" boxes.
459 The figure represents mirrors, which also play a role in locating
460 source files, with the "Source Mirror(s)" box.
461 </para>
462
463 <para>
464 The method by which source files are ultimately organized is
465 a function of the project.
466 For example, for released software, projects tend to use tarballs
467 or other archived files that can capture the state of a release
468 guaranteeing that it is statically represented.
469 On the other hand, for a project that is more dynamic or
470 experimental in nature, a project might keep source files in a
471 repository controlled by a Source Control Manager (SCM) such as
472 Git.
473 Pulling source from a repository allows you to control
474 the point in the repository (the revision) from which you want to
475 build software.
476 Finally, a combination of the two might exist, which would give the
477 consumer a choice when deciding where to get source files.
478 </para>
479
480 <para>
481 BitBake uses the
482 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
483 variable to point to source files regardless of their location.
484 Each recipe must have a <filename>SRC_URI</filename> variable
485 that points to the source.
486 </para>
487
488 <para>
489 Another area that plays a significant role in where source files
490 comes from is pointed to by the
491 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
492 variable.
493 This area is a cache that can hold previously downloaded source.
494 You can also instruct the OpenEmbedded build system to create
495 tarballs from Git repositories, which is not the default behavior,
496 and store them in the <filename>DL_DIR</filename> by using the
497 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
498 variable.
499 </para>
500
501 <para>
502 Judicious use of a <filename>DL_DIR</filename> directory can
503 save the build system a trip across the Internet when looking
504 for files.
505 A good method for using a download directory is to have
506 <filename>DL_DIR</filename> point to an area outside of your
507 Build Directory.
508 Doing so allows you to safely delete the Build Directory
509 if needed without fear of removing any downloaded source file.
510 </para>
511
512 <para>
513 The remainder of this section provides a deeper look into the
514 source files and the mirrors.
515 Here is a more detailed look at the source file area of the
516 base figure:
517 <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
518 </para>
519
520 <section id='upstream-project-releases'>
521 <title>Upstream Project Releases</title>
522
523 <para>
524 Upstream project releases exist anywhere in the form of an
525 archived file (e.g. tarball or zip file).
526 These files correspond to individual recipes.
527 For example, the figure uses specific releases each for
528 BusyBox, Qt, and Dbus.
529 An archive file can be for any released product that can be
530 built using a recipe.
531 </para>
532 </section>
533
534 <section id='local-projects'>
535 <title>Local Projects</title>
536
537 <para>
538 Local projects are custom bits of software the user provides.
539 These bits reside somewhere local to a project - perhaps
540 a directory into which the user checks in items (e.g.
541 a local directory containing a development source tree
542 used by the group).
543 </para>
544
545 <para>
546 The canonical method through which to include a local project
547 is to use the
548 <link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>
549 class to include local project.
550 You use either the <filename>local.conf</filename> or a
551 recipe's append file to override or set the
552 recipe to point to the local directory on your disk to pull
553 in the whole source tree.
554 </para>
555
556 <para>
557 For information on how to use the
558 <filename>externalsrc.bbclass</filename>, see the
559 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
560 section.
561 </para>
562 </section>
563
564 <section id='scms'>
565 <title>Source Control Managers (Optional)</title>
566
567 <para>
568 Another place the build system can get source files from is
569 through an SCM such as Git or Subversion.
570 In this case, a repository is cloned or checked out.
571 The <filename>do_fetch</filename> task inside BitBake uses
572 the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
573 variable and the argument's prefix to determine the correct
574 fetcher module.
575 </para>
576
577 <note>
578 For information on how to have the OpenEmbedded build system
579 generate tarballs for Git repositories and place them in the
580 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
581 directory, see the
582 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
583 variable.
584 </note>
585
586 <para>
587 When fetching a repository, BitBake uses the
588 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
589 variable to determine the specific revision from which to
590 build.
591 </para>
592 </section>
593
594 <section id='source-mirrors'>
595 <title>Source Mirror(s)</title>
596
597 <para>
598 Two kinds of mirrors exist: pre-mirrors and regular mirrors.
599 The <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
600 and
601 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
602 variables point to these, respectively.
603 BitBake checks pre-mirrors before looking upstream for any
604 source files.
605 Pre-mirrors are appropriate when you have a shared directory
606 that is not a directory defined by the
607 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
608 variable.
609 A Pre-mirror typically points to a shared directory that is
610 local to your organization.
611 </para>
612
613 <para>
614 Regular mirrors can be any site across the Internet that is
615 used as an alternative location for source code should the
616 primary site not be functioning for some reason or another.
617 </para>
618 </section>
619 </section>
620
621 <section id="package-feeds-dev-environment">
622 <title>Package Feeds</title>
623
624 <para>
625 When the OpenEmbedded build system generates an image or an SDK,
626 it gets the packages from a package feed area located in the
627 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
628 The
629 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
630 shows this package feeds area in the upper-right corner.
631 </para>
632
633 <para>
634 This section looks a little closer into the package feeds area used
635 by the build system.
636 Here is a more detailed look at the area:
637 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
638 </para>
639
640 <para>
641 Package feeds are an intermediary step in the build process.
642 BitBake generates packages whose type is defined by the
643 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
644 variable.
645 Before placing the packages into package feeds,
646 the build process validates them with generated output quality
647 assurance checks through the
648 <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>
649 class.
650 </para>
651
652 <para>
653 The package feed area resides in
654 <filename>tmp/deploy</filename> of the Build Directory.
655 Folders are created that correspond to the package type
656 (IPK, DEB, or RPM) created.
657 Further organization is derived through the value of the
658 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
659 variable for each package.
660 For example, packages can exist for the i586 or qemux86
661 architectures.
662 The package files themselves reside within the appropriate
663 architecture folder.
664 </para>
665
666 <para>
667 BitBake uses the <filename>do_package_write_*</filename> task to
668 place generated packages into the package holding area (e.g.
669 <filename>do_package_write_ipk</filename> for IPK packages).
670 </para>
671 </section>
672
673 <section id='bitbake-dev-environment'>
674 <title>BitBake</title>
675
676 <para>
677 The OpenEmbedded build system uses BitBake to produce images.
678 You can see from the
679 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
680 the BitBake area consists of several functional areas.
681 This section takes a closer look at each of those areas.
682 </para>
683
684 <section id='source-fetching-dev-environment'>
685 <title>Source Fetching</title>
686
687 <para>
688 The first stages of building a recipe are to fetch and unpack
689 the source code:
690 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
691 </para>
692
693 <para>
694 The <filename>do_fetch</filename> and
695 <filename>do_unpack</filename> tasks fetch the source files
696 and unpack them into a working directory.
697 By default, everything is accomplished in the
698 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
699 which has a defined structure.
700 For additional general information on the Build Directory,
701 see the
702 "<link linkend='structure-core-build'><filename>build/</filename></link>"
703 section.
704 </para>
705
706 <para>
707 Unpacked source source files are pointed to by the
708 <link linkend='var-S'><filename>S</filename></link> variable.
709 Each recipe has an area in the Build Directory where the
710 unpacked source code resides.
711 The name of directory for any given recipe is defined from
712 several different variables.
713 You can see the variables that define these directories
714 by looking at the figure:
715 <itemizedlist>
716 <listitem><para><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
717 </para></listitem>
718 <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
719 </para></listitem>
720 <listitem><para><link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
721 </para></listitem>
722 <listitem><para><link linkend='var-PN'><filename>PN</filename></link>
723 </para></listitem>
724 <listitem><para><link linkend='var-PV'><filename>PV</filename></link>
725 </para></listitem>
726 <listitem><para><link linkend='var-PR'><filename>PR</filename></link>
727 </para></listitem>
728 <listitem><para><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
729 </para></listitem>
730 <listitem><para><link linkend='var-S'><filename>S</filename></link>
731 </para></listitem>
732 </itemizedlist>
733 </para>
734
735 <para>
736 Briefly, the <filename>S</filename> directory contains the
737 unpacked source files for a recipe.
738 The <filename>WORKDIR</filename> directory is where all the
739 building goes on for a given recipe.
740 </para>
741 </section>
742
743 <section id='patching-dev-environment'>
744 <title>Patching</title>
745
746 <para>
747 Once source code is fetched and unpacked, BitBake locates
748 patch files and applies them to the source files:
749 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
750 </para>
751
752 <para>
753 The <filename>do_patch</filename> task processes recipes by
754 using the
755 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
756 variable to locate applicable patch files, which by default
757 are <filename>*.patch</filename> or
758 <filename>*.diff</filename> files, or any file if
759 "apply=yes" is specified for the file in
760 <filename>SRC_URI</filename>.
761 </para>
762
763 <para>
764 BitBake finds and applies multiple patches for a single recipe
765 in the order in which it finds the patches.
766 Patches are applied to the recipe's source files located in the
767 <link linkend='var-S'><filename>S</filename></link> directory.
768 </para>
769
770 <para>
771 For more information on how the source directories are
772 created, see the
773 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
774 section.
775 </para>
776 </section>
777
778 <section id='configuration-and-compilation-dev-environment'>
779 <title>Configuration and Compilation</title>
780
781 <para>
782 After source code is patched, BitBake executes tasks that
783 configure and compile the source code:
784 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
785 </para>
786
787 <para>
788 This step in the build process consists of three tasks:
789 <itemizedlist>
790 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
791 This task configures the source by enabling and
792 disabling any build-time and configuration options for
793 the software being built.
794 Configurations can come from the recipe itself as well
795 as from an inherited class.
796 Additionally, the software itself might configure itself
797 depending on the target for which it is being built.
798 </para>
799
800 <para>The configurations handled by the
801 <filename>do_configure</filename> task are specific
802 to source code configuration for the source code
803 being built by the recipe.</para>
804
805 <para>If you are using
806 <link linkend='ref-classes-autotools'><filename>autotools.bbclass</filename></link>,
807 you can add additional configuration options by using
808 the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
809 variable.
810 For information on how this variable works within
811 that class, see the
812 <filename>meta/classes/autotools.bbclass</filename>.
813 </para></listitem>
814 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
815 Once a configuration task has been satisfied, BitBake
816 compiles the source using the
817 <filename>do_compile</filename> task.
818 Compilation occurs in the directory pointed to by the
819 <link linkend='var-B'><filename>B</filename></link>
820 variable.
821 Realize that the <filename>B</filename> directory, by
822 default, is the same as the
823 <link linkend='var-S'><filename>S</filename></link>
824 directory.</para></listitem>
825 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
826 Once compilation is done, BitBake executes the
827 <filename>do_install</filename> task.
828 This task copies files from the <filename>B</filename>
829 directory and places them in a holding area pointed to
830 by the
831 <link linkend='var-D'><filename>D</filename></link>
832 variable.</para></listitem>
833 </itemizedlist>
834 </para>
835 </section>
836
837 <section id='package-splitting-dev-environment'>
838 <title>Package Splitting</title>
839
840 <para>
841 After source code is configured and compiled, the
842 OpenEmbedded build system analyzes
843 the results and splits the output into packages:
844 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
845 </para>
846
847 <para>
848 The <filename>do_package</filename> and
849 <filename>do_packagedata</filename> tasks combine to analyze
850 the files found in the
851 <link linkend='var-D'><filename>D</filename></link> directory
852 and split them into subsets based on available packages and
853 files.
854 The analyzing process involves the following as well as other
855 items: splitting out debugging symbols,
856 looking at shared library dependencies between packages,
857 and looking at package relationships.
858 The <filename>do_packagedata</filename> task creates package
859 metadata based on the analysis such that the
860 OpenEmbedded build system can generate the final packages.
861 Working, staged, and intermediate results of the analysis
862 and package splitting process use these areas:
863 <itemizedlist>
864 <listitem><para><link linkend='var-PKGD'><filename>PKGD</filename></link>
865 </para></listitem>
866 <listitem><para><link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
867 </para></listitem>
868 <listitem><para><link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
869 </para></listitem>
870 <listitem><para><link linkend='var-PKGDEST'><filename>PKGDEST</filename></link>
871 </para></listitem>
872 </itemizedlist>
873 The <link linkend='var-FILES'><filename>FILES</filename></link>
874 variable defines the files that go into each package in
875 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
876 If you want details on how this is accomplished, you can
877 look at
878 <link linkend='ref-classes-package'><filename>package.bbclass</filename></link>.
879 </para>
880
881 <para>
882 Depending on the type of packages being created (RPM, DEB, or
883 IPK), the <filename>do_package_write_*</filename> task
884 creates the actual packages and places them in the
885 Package Feed area, which is
886 <filename>${TMPDIR}/deploy</filename>.
887 You can see the
888 "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
889 section for more detail on that part of the build process.
890 <note>
891 Support for creating feeds directly from the
892 <filename>deploy/*</filename> directories does not exist.
893 Creating such feeds usually requires some kind of feed
894 maintenance mechanism that would upload the new packages
895 into an official package feed (e.g. the
896 Ångström distribution).
897 This functionality is highly distribution-specific
898 and thus is not provided out of the box.
899 </note>
900 </para>
901 </section>
902
903 <section id='image-generation-dev-environment'>
904 <title>Image Generation</title>
905
906 <para>
907 Once packages are split and stored in the Package Feeds area,
908 the OpenEmbedded build system uses BitBake to generate the
909 root filesystem image:
910 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
911 </para>
912
913 <para>
914 The image generation process consists of several stages and
915 depends on many variables.
916 The <filename>do_rootfs</filename> task uses these key variables
917 to help create the list of packages to actually install:
918 <itemizedlist>
919 <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
920 Lists out the base set of packages to install from
921 the Package Feeds area.</para></listitem>
922 <listitem><para><link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>:
923 Specifies packages that should not be installed.
924 </para></listitem>
925 <listitem><para><link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
926 Specifies features to include in the image.
927 Most of these features map to additional packages for
928 installation.</para></listitem>
929 <listitem><para><link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>:
930 Specifies the package backend to use and consequently
931 helps determine where to locate packages within the
932 Package Feeds area.</para></listitem>
933 <listitem><para><link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>:
934 Determines the language(s) for which additional
935 language support packages are installed.
936 </para></listitem>
937 </itemizedlist>
938 </para>
939
940 <para>
941 Package installation is under control of the package manager
942 (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
943 not package management is enabled for the target.
944 At the end of the process, if package management is not
945 enabled for the target, the package manager's data files
946 are deleted from the root filesystem.
947 </para>
948
949 <para>
950 During image generation, the build system attempts to run
951 all post installation scripts.
952 Any that fail to run on the build host are run on the
953 target when the target system is first booted.
954 If you are using a
955 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
956 all the post installation scripts must succeed during the
957 package installation phase since the root filesystem cannot be
958 written into.
959 </para>
960
961 <para>
962 During Optimization, optimizing processes are run across
963 the image.
964 These processes include <filename>mklibs</filename> and
965 <filename>prelink</filename>.
966 The <filename>mklibs</filename> process optimizes the size
967 of the libraries.
968 A <filename>prelink</filename> process optimizes the dynamic
969 linking of shared libraries to reduce start up time of
970 executables.
971 </para>
972
973 <para>
974 Part of the image generation process includes compressing the
975 root filesystem image.
976 Compression is accomplished through several optimization
977 routines designed to reduce the overall size of the image.
978 </para>
979
980 <para>
981 After the root filesystem has been constructed, the image
982 generation process turns everything into an image file or
983 a set of image files.
984 The formats used for the root filesystem depend on the
985 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
986 variable.
987 </para>
988
989 <note>
990 The entire image generation process is run under Pseudo.
991 Running under Pseudo ensures that the files in the root
992 filesystem have correct ownership.
993 </note>
994 </section>
995
996 <section id='sdk-generation-dev-environment'>
997 <title>SDK Generation</title>
998
999 <para>
1000 The OpenEmbedded build system uses BitBake to generate the
1001 Software Development Kit (SDK) installer script:
1002 <imagedata fileref="figures/sdk-generation.png" align="center" width="6in" depth="7in" />
1003 </para>
1004
1005 <note>
1006 For more information on the cross-development toolchain
1007 generation, see the
1008 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1009 section.
1010 </note>
1011
1012 <para>
1013 Like image generation, the SDK script process consists of
1014 several stages and depends on many variables.
1015 The <filename>do_populate_sdk</filename> task uses these
1016 key variables to help create the list of packages to actually
1017 install.
1018 For information on the variables listed in the figure, see the
1019 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1020 section.
1021 </para>
1022
1023 <para>
1024 The <filename>do_populate_sdk</filename> task handles two
1025 parts: a target part and a host part.
1026 The target part is the part built for the target hardware and
1027 includes libraries and headers.
1028 The host part is the part of the SDK that runs on the
1029 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
1030 </para>
1031
1032 <para>
1033 Once both parts are constructed, the
1034 <filename>do_populate_sdk</filename> task performs some cleanup
1035 on both parts.
1036 After the cleanup, the task creates a cross-development
1037 environment setup script and any configuration files that
1038 might be needed.
1039 </para>
1040
1041 <para>
1042 The final output of the task is the Cross-development
1043 toolchain installation script (<filename>.sh</filename> file),
1044 which includes the environment setup script.
1045 </para>
1046 </section>
1047 </section>
1048
1049 <section id='images-dev-environment'>
1050 <title>Images</title>
1051
1052 <para>
1053 The images produced by the OpenEmbedded build system
1054 are compressed forms of the
1055 root filesystems that are ready to boot on a target device.
1056 You can see from the
1057 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1058 that BitBake output in part consists of images.
1059 This section is going to look more closely at this output:
1060 <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
1061 </para>
1062
1063 <para>
1064 For a list of example images that the Yocto Project provides,
1065 the
1066 "<link linkend='ref-images'>Images</link>" chapter.
1067 </para>
1068
1069 <para>
1070 Images are written out to the
1071 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1072 inside the <filename>deploy/images/&lt;machine&gt;/</filename>
1073 folder as shown in the figure.
1074 This folder contains any files expected to be loaded on the
1075 target device.
1076 The
1077 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
1078 variable points to the <filename>deploy</filename> directory,
1079 while the
1080 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
1081 variable points to the appropriate directory containing images for
1082 the current configuration.
1083 <itemizedlist>
1084 <listitem><para><filename>&lt;kernel-image&gt;</filename>:
1085 A kernel binary file.
1086 The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
1087 variable setting determines the naming scheme for the
1088 kernel image file.
1089 Depending on that variable, the file could begin with
1090 a variety of naming strings.
1091 The <filename>deploy/images/&lt;machine&gt;</filename>
1092 directory can contain multiple image files for the
1093 machine.</para></listitem>
1094 <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
1095 Root filesystems for the target device (e.g.
1096 <filename>*.ext3</filename> or <filename>*.bz2</filename>
1097 files).
1098 The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1099 variable setting determines the root filesystem image
1100 type.
1101 The <filename>deploy/images/&lt;machine&gt;</filename>
1102 directory can contain multiple root filesystems for the
1103 machine.</para></listitem>
1104 <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
1105 Tarballs that contain all the modules built for the kernel.
1106 Kernel module tarballs exist for legacy purposes and
1107 can be suppressed by setting the
1108 <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
1109 variable to "0".
1110 The <filename>deploy/images/&lt;machine&gt;</filename>
1111 directory can contain multiple kernel module tarballs
1112 for the machine.</para></listitem>
1113 <listitem><para><filename>&lt;bootloaders&gt;</filename>:
1114 Bootloaders supporting the image, if applicable to the
1115 target machine.
1116 The <filename>deploy/images/&lt;machine&gt;</filename>
1117 directory can contain multiple bootloaders for the
1118 machine.</para></listitem>
1119 <listitem><para><filename>&lt;symlinks&gt;</filename>:
1120 The <filename>deploy/images/&lt;machine&gt;</filename>
1121 folder contains
1122 a symbolic link that points to the most recently built file
1123 for each machine.
1124 These links might be useful for external scripts that
1125 need to obtain the latest version of each file.
1126 </para></listitem>
1127 </itemizedlist>
1128 </para>
1129 </section>
1130
1131 <section id='sdk-dev-environment'>
1132 <title>Application Development SDK</title>
1133
1134 <para>
1135 In the
1136 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
1137 the output labeled "Application Development SDK" represents an
1138 SDK.
1139 This section is going to take a closer look at this output:
1140 <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
1141 </para>
1142
1143 <para>
1144 The specific form of this output is a self-extracting
1145 SDK installer (<filename>*.sh</filename>) that, when run,
1146 installs the SDK, which consists of a cross-development
1147 toolchain, a set of libraries and headers, and an SDK
1148 environment setup script.
1149 Running this installer essentially sets up your
1150 cross-development environment.
1151 You can think of the cross-toolchain as the "host"
1152 part because it runs on the SDK machine.
1153 You can think of the libraries and headers as the "target"
1154 part because they are built for the target hardware.
1155 The setup script is added so that you can initialize the
1156 environment before using the tools.
1157 </para>
1158
1159 <note>
1160 <para>
1161 The Yocto Project supports several methods by which you can
1162 set up this cross-development environment.
1163 These methods include downloading pre-built SDK installers,
1164 building and installing your own SDK installer, or running
1165 an Application Development Toolkit (ADT) installer to
1166 install not just cross-development toolchains
1167 but also additional tools to help in this type of
1168 development.
1169 </para>
1170
1171 <para>
1172 For background information on cross-development toolchains
1173 in the Yocto Project development environment, see the
1174 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1175 section.
1176 For information on setting up a cross-development
1177 environment, see the
1178 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
1179 section in the Yocto Project Application Developer's Guide.
1180 </para>
1181 </note>
1182
1183 <para>
1184 Once built, the SDK installers are written out to the
1185 <filename>deploy/sdk</filename> folder inside the
1186 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1187 as shown in the figure at the beginning of this section.
1188 Several variables exist that help configure these files:
1189 <itemizedlist>
1190 <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
1191 Points to the <filename>deploy</filename>
1192 directory.</para></listitem>
1193 <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
1194 Specifies the architecture of the machine
1195 on which the cross-development tools are run to
1196 create packages for the target hardware.
1197 </para></listitem>
1198 <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
1199 Lists the features to include in the "target" part
1200 of the SDK.
1201 </para></listitem>
1202 <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
1203 Lists packages that make up the host
1204 part of the SDK (i.e. the part that runs on
1205 the <filename>SDKMACHINE</filename>).
1206 When you use
1207 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
1208 to create the SDK, a set of default packages
1209 apply.
1210 This variable allows you to add more packages.
1211 </para></listitem>
1212 <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
1213 Lists packages that make up the target part
1214 of the SDK (i.e. the part built for the
1215 target hardware).
1216 </para></listitem>
1217 </itemizedlist>
1218 </para>
1219 </section>
1220
1221</chapter>
1222<!--
1223vim: expandtab tw=80 ts=4
1224-->
diff --git a/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb
new file mode 100644
index 0000000000..5dfb0b30cf
--- /dev/null
+++ b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb
@@ -0,0 +1,8 @@
1DESCRIPTION = "GNU Helloworld application"
2SECTION = "examples"
3LICENSE = "GPLv3"
4LIC_FILES_CHKSUM = "file://COPYING;md5=adefda309052235aa5d1e99ce7557010"
5
6SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
7
8inherit autotools
diff --git a/documentation/ref-manual/examples/hello-single/files/helloworld.c b/documentation/ref-manual/examples/hello-single/files/helloworld.c
new file mode 100644
index 0000000000..fc7169b7b8
--- /dev/null
+++ b/documentation/ref-manual/examples/hello-single/files/helloworld.c
@@ -0,0 +1,8 @@
1#include <stdio.h>
2
3int main(void)
4{
5 printf("Hello world!\n");
6
7 return 0;
8}
diff --git a/documentation/ref-manual/examples/hello-single/hello.bb b/documentation/ref-manual/examples/hello-single/hello.bb
new file mode 100644
index 0000000000..0812743e39
--- /dev/null
+++ b/documentation/ref-manual/examples/hello-single/hello.bb
@@ -0,0 +1,17 @@
1DESCRIPTION = "Simple helloworld application"
2SECTION = "examples"
3LICENSE = "MIT"
4LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
5
6SRC_URI = "file://helloworld.c"
7
8S = "${WORKDIR}"
9
10do_compile() {
11 ${CC} helloworld.c -o helloworld
12}
13
14do_install() {
15 install -d ${D}${bindir}
16 install -m 0755 helloworld ${D}${bindir}
17}
diff --git a/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb
new file mode 100644
index 0000000000..b58d4d7bd1
--- /dev/null
+++ b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb
@@ -0,0 +1,14 @@
1require xorg-lib-common.inc
2
3DESCRIPTION = "X11 Pixmap library"
4LICENSE = "X-BSD"
5LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
6DEPENDS += "libxext"
7PR = "r2"
8PE = "1"
9
10XORG_PN = "libXpm"
11
12PACKAGES =+ "sxpm cxpm"
13FILES_cxpm = "${bindir}/cxpm"
14FILES_sxpm = "${bindir}/sxpm"
diff --git a/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb
new file mode 100644
index 0000000000..5d05a437a4
--- /dev/null
+++ b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb
@@ -0,0 +1,15 @@
1DESCRIPTION = "Tools for managing memory technology devices."
2SECTION = "base"
3DEPENDS = "zlib"
4HOMEPAGE = "http://www.linux-mtd.infradead.org/"
5LICENSE = "GPLv2"
6LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
7 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
8
9SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
10
11CFLAGS_prepend = "-I ${S}/include "
12
13do_install() {
14 oe_runmake install DESTDIR=${D}
15}
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
new file mode 100644
index 0000000000..69b679bbf7
--- /dev/null
+++ b/documentation/ref-manual/faq.xml
@@ -0,0 +1,710 @@
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='faq'>
6<title>FAQ</title>
7<qandaset>
8 <qandaentry>
9 <question>
10 <para>
11 How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
12 </para>
13 </question>
14 <answer>
15 <para>
16 The term "<ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>"
17 refers to the specific reference build system that
18 the Yocto Project provides.
19 Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
20 and <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
21 Thus, the generic term used here for the build system is
22 the "OpenEmbedded build system."
23 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
24 changes always being merged to OE-Core or BitBake first before being pulled back
25 into Poky.
26 This practice benefits both projects immediately.
27 </para>
28 </answer>
29 </qandaentry>
30
31 <qandaentry>
32 <question>
33 <para>
34 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
35 Can I still use the Yocto Project?
36 </para>
37 </question>
38 <answer>
39 <para>
40 You can use a stand-alone tarball to provide Python 2.6.
41 You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
42 <itemizedlist>
43 <listitem><para><ulink url='&YOCTO_PYTHON-i686_DL_URL;'>32-bit tarball</ulink></para></listitem>
44 <listitem><para><ulink url='&YOCTO_PYTHON-x86_64_DL_URL;'>64-bit tarball</ulink></para></listitem>
45 </itemizedlist>
46 </para>
47 <para>
48 These tarballs are self-contained with all required libraries and should work
49 on most Linux systems.
50 To use the tarballs extract them into the root
51 directory and run the appropriate command:
52 <literallayout class='monospaced'>
53 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
54 $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
55 </literallayout>
56 </para>
57 <para>
58 Once you run the command, BitBake uses Python 2.6.
59 </para>
60 </answer>
61 </qandaentry>
62
63 <qandaentry>
64 <question>
65 <para>
66 How can you claim Poky / OpenEmbedded-Core is stable?
67 </para>
68 </question>
69 <answer>
70 <para>
71 There are three areas that help with stability;
72 <itemizedlist>
73 <listitem><para>The Yocto Project team keeps
74 <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small
75 and focused, containing around 830 recipes as opposed to the thousands
76 available in other OpenEmbedded community layers.
77 Keeping it small makes it easy to test and maintain.</para></listitem>
78 <listitem><para>The Yocto Project team runs manual and automated tests
79 using a small, fixed set of reference hardware as well as emulated
80 targets.</para></listitem>
81 <listitem><para>The Yocto Project uses an autobuilder,
82 which provides continuous build and integration tests.</para></listitem>
83 </itemizedlist>
84 </para>
85 </answer>
86 </qandaentry>
87
88 <qandaentry>
89 <question>
90 <para>
91 How do I get support for my board added to the Yocto Project?
92 </para>
93 </question>
94 <answer>
95 <para>
96 Support for an additional board is added by creating a
97 Board Support Package (BSP) layer for it.
98 For more information on how to create a BSP layer, see the
99 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
100 section in the Yocto Project Development Manual and the
101 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
102 </para>
103 <para>
104 Usually, if the board is not completely exotic, adding support in
105 the Yocto Project is fairly straightforward.
106 </para>
107 </answer>
108 </qandaentry>
109
110 <qandaentry>
111 <question>
112 <para>
113 Are there any products built using the OpenEmbedded build system?
114 </para>
115 </question>
116 <answer>
117 <para>
118 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
119 is built using the OpenEmbedded build system.
120 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
121 website for more information.
122 There are a number of pre-production devices using the OpenEmbedded build system
123 and the Yocto Project team
124 announces them as soon as they are released.
125 </para>
126 </answer>
127 </qandaentry>
128
129 <qandaentry>
130 <question>
131 <para>
132 What does the OpenEmbedded build system produce as output?
133 </para>
134 </question>
135 <answer>
136 <para>
137 Because you can use the same set of recipes to create output of
138 various formats, the output of an OpenEmbedded build depends on
139 how you start it.
140 Usually, the output is a flashable image ready for the target
141 device.
142 </para>
143 </answer>
144 </qandaentry>
145
146 <qandaentry>
147 <question>
148 <para>
149 How do I add my package to the Yocto Project?
150 </para>
151 </question>
152 <answer>
153 <para>
154 To add a package, you need to create a BitBake recipe.
155 For information on how to add a package, see the section
156 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Writing a Recipe to Add a Package to Your Image</ulink>"
157 in the Yocto Project Development Manual.
158 </para>
159 </answer>
160 </qandaentry>
161
162 <qandaentry>
163 <question>
164 <para>
165 Do I have to reflash my entire board with a new Yocto Project image when recompiling
166 a package?
167 </para>
168 </question>
169 <answer>
170 <para>
171 The OpenEmbedded build system can build packages in various
172 formats such as IPK for OPKG, Debian package
173 (<filename>.deb</filename>), or RPM.
174 You can then upgrade the packages using the package tools on
175 the device, much like on a desktop distribution such as
176 Ubuntu or Fedora.
177 However, package management on the target is entirely optional.
178 </para>
179 </answer>
180 </qandaentry>
181
182 <qandaentry>
183 <question>
184 <para>
185 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
186 </para>
187 </question>
188 <answer>
189 <para>
190 GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
191 platform targeted at mobile and embedded devices.
192 The main difference between GNOME Mobile and standard GNOME is that
193 desktop-orientated libraries have been removed, along with deprecated libraries,
194 creating a much smaller footprint.
195 </para>
196 </answer>
197 </qandaentry>
198
199 <qandaentry>
200 <question>
201 <para>
202 I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
203 What is wrong?
204 </para>
205 </question>
206 <answer>
207 <para>
208 You are probably running the build on an NTFS filesystem.
209 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
210 </para>
211 </answer>
212 </qandaentry>
213
214 <qandaentry>
215 <question>
216 <para>
217 How do I make the Yocto Project work in RHEL/CentOS?
218 </para>
219 </question>
220 <answer>
221 <para>
222 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
223 install some required packages.
224 The standard CentOS packages needed are:
225 <itemizedlist>
226 <listitem><para>"Development tools" (selected during installation)</para></listitem>
227 <listitem><para><filename>texi2html</filename></para></listitem>
228 <listitem><para><filename>compat-gcc-34</filename></para></listitem>
229 </itemizedlist>
230 On top of these, you need the following external packages:
231 <itemizedlist>
232 <listitem><para><filename>python-sqlite2</filename> from
233 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
234 </para></listitem>
235 <listitem><para><filename>help2man</filename> from
236 <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem>
237 </itemizedlist>
238 </para>
239
240 <para>
241 Once these packages are installed, the OpenEmbedded build system will be able
242 to build standard images.
243 However, there might be a problem with the QEMU emulator segfaulting.
244 You can either disable the generation of binary locales by setting
245 <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
246 </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
247 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
248 </para>
249
250 <note>
251 <para>For information on distributions that the Yocto Project
252 uses during validation, see the
253 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>
254 Wiki page.</para>
255 <para>For notes about using the Yocto Project on a RHEL 4-based
256 host, see the
257 <ulink url='&YOCTO_WIKI_URL;/wiki/BuildingOnRHEL4'>Building on RHEL4</ulink>
258 Wiki page.</para>
259 </note>
260 </answer>
261 </qandaentry>
262
263 <qandaentry>
264 <question>
265 <para>
266 I see lots of 404 responses for files on
267 <filename>&YOCTO_HOME_URL;/sources/*</filename>. Is something wrong?
268 </para>
269 </question>
270 <answer>
271 <para>
272 Nothing is wrong.
273 The OpenEmbedded build system checks any configured source mirrors before downloading
274 from the upstream sources.
275 The build system does this searching for both source archives and
276 pre-checked out versions of SCM-managed software.
277 These checks help in large installations because it can reduce load on the SCM servers
278 themselves.
279 The address above is one of the default mirrors configured into the
280 build system.
281 Consequently, if an upstream source disappears, the team
282 can place sources there so builds continue to work.
283 </para>
284 </answer>
285 </qandaentry>
286
287 <qandaentry>
288 <question>
289 <para>
290 I have machine-specific data in a package for one machine only but the package is
291 being marked as machine-specific in all cases, how do I prevent this?
292 </para>
293 </question>
294 <answer>
295 <para>
296 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
297 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
298 manually marked as
299 machine-specific for the case that needs it.
300 The code that handles
301 <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in
302 the <filename>meta/classes/base.bbclass</filename> file.
303 </para>
304 </answer>
305 </qandaentry>
306
307 <qandaentry>
308 <question>
309 <para>
310 I'm behind a firewall and need to use a proxy server. How do I do that?
311 </para>
312 </question>
313 <answer>
314 <para>
315 Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename>
316 and you therefore need to specify the proxy settings in a
317 <filename>.wgetrc</filename> file in your home directory.
318 Here are some example settings:
319 <literallayout class='monospaced'>
320 http_proxy = http://proxy.yoyodyne.com:18023/
321 ftp_proxy = http://proxy.yoyodyne.com:18023/
322 </literallayout>
323 The Yocto Project also includes a
324 <filename>site.conf.sample</filename> file that shows how to
325 configure CVS and Git proxy servers if needed.
326 </para>
327 </answer>
328 </qandaentry>
329
330 <qandaentry>
331 <question>
332 <para>
333 What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>?
334 </para>
335 </question>
336 <answer>
337 <para>
338 The <filename>*-native</filename> targets are designed to run on the system
339 being used for the build.
340 These are usually tools that are needed to assist the build in some way such as
341 <filename>quilt-native</filename>, which is used to apply patches.
342 The non-native version is the one that runs on the target device.
343 </para>
344 </answer>
345 </qandaentry>
346
347 <qandaentry>
348 <question>
349 <para>
350 I'm seeing random build failures. Help?!
351 </para>
352 </question>
353 <answer>
354 <para>
355 If the same build is failing in totally different and random
356 ways, the most likely explanation is:
357 <itemizedlist>
358 <listitem><para>The hardware you are running the build on
359 has some problem.</para></listitem>
360 <listitem><para>You are running the build under
361 virtualization, in which case the virtualization
362 probably has bugs.</para></listitem>
363 </itemizedlist>
364 The OpenEmbedded build system processes a massive amount of
365 data that causes lots of network, disk and CPU activity and
366 is sensitive to even single-bit failures in any of these areas.
367 True random failures have always been traced back to hardware
368 or virtualization issues.
369 </para>
370 </answer>
371 </qandaentry>
372
373 <qandaentry>
374 <question>
375 <para>
376 What do we need to ship for license compliance?
377 </para>
378 </question>
379 <answer>
380 <para>
381 This is a difficult question and you need to consult your lawyer
382 for the answer for your specific case.
383 It is worth bearing in mind that for GPL compliance, there needs
384 to be enough information shipped to allow someone else to
385 rebuild and produce the same end result you are shipping.
386 This means sharing the source code, any patches applied to it,
387 and also any configuration information about how that package
388 was configured and built.
389 </para>
390
391 <para>
392 You can find more information on licensing in the
393 "<ulink url='&YOCTO_DOCS_DEV_URL;#licensing'>Licensing</ulink>"
394 and "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
395 sections, both of which are in the Yocto Project Development
396 Manual.
397 </para>
398 </answer>
399 </qandaentry>
400
401 <qandaentry>
402 <question>
403 <para>
404 How do I disable the cursor on my touchscreen device?
405 </para>
406 </question>
407 <answer>
408 <para>
409 You need to create a form factor file as described in the
410 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
411 section in the Yocto Project Board Support Packages (BSP)
412 Developer's Guide.
413 Set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to
414 one as follows:
415 <literallayout class='monospaced'>
416 HAVE_TOUCHSCREEN=1
417 </literallayout>
418 </para>
419 </answer>
420 </qandaentry>
421
422 <qandaentry>
423 <question>
424 <para>
425 How do I make sure connected network interfaces are brought up by default?
426 </para>
427 </question>
428 <answer>
429 <para>
430 The default interfaces file provided by the netbase recipe does not
431 automatically bring up network interfaces.
432 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
433 file.
434 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
435 section in the Yocto Project Board Support Packages (BSP)
436 Developer's Guide for information on creating these types of
437 miscellaneous recipe files.
438 </para>
439 <para>
440 For example, add the following files to your layer:
441 <literallayout class='monospaced'>
442 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
443 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
444 </literallayout>
445 </para>
446 </answer>
447 </qandaentry>
448
449 <qandaentry>
450 <question>
451 <para>
452 How do I create images with more free space?
453 </para>
454 </question>
455 <answer>
456 <para>
457 By default, the OpenEmbedded build system creates images
458 that are 1.3 times the size of the populated root filesystem.
459 To affect the image size, you need to set various
460 configurations:
461 <itemizedlist>
462 <listitem><para><emphasis>Image Size:</emphasis>
463 The OpenEmbedded build system uses the
464 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
465 variable to define the size of the image in Kbytes.
466 The build system determines the size by taking into
467 account the initial root filesystem size before any
468 modifications such as requested size for the image and
469 any requested additional free disk space to be
470 added to the image.</para></listitem>
471 <listitem><para><emphasis>Overhead:</emphasis>
472 Use the
473 <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
474 variable to define the multiplier that the build system
475 applies to the initial image size, which is 1.3 by
476 default.</para></listitem>
477 <listitem><para><emphasis>Additional Free Space:</emphasis>
478 Use the
479 <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
480 variable to add additional free space to the image.
481 The build system adds this space to the image after
482 it determines its
483 <filename>IMAGE_ROOTFS_SIZE</filename>.
484 </para></listitem>
485 </itemizedlist>
486 </para>
487 </answer>
488 </qandaentry>
489
490 <qandaentry>
491 <question>
492 <para>
493 Why don't you support directories with spaces in the pathnames?
494 </para>
495 </question>
496 <answer>
497 <para>
498 The Yocto Project team has tried to do this before but too
499 many of the tools the OpenEmbedded build system depends on,
500 such as <filename>autoconf</filename>, break when they find
501 spaces in pathnames.
502 Until that situation changes, the team will not support spaces
503 in pathnames.
504 </para>
505 </answer>
506 </qandaentry>
507
508 <qandaentry>
509 <question>
510 <para>
511 How do I use an external toolchain?
512 </para>
513 </question>
514 <answer>
515 <para>
516 The toolchain configuration is very flexible and customizable.
517 It is primarily controlled with the
518 <filename><link linkend='var-TCMODE'>TCMODE</link></filename>
519 variable.
520 This variable controls which <filename>tcmode-*.inc</filename>
521 file to include from the
522 <filename>meta/conf/distro/include</filename> directory within
523 the
524 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
525 </para>
526
527 <para>
528 The default value of <filename>TCMODE</filename> is "default"
529 (i.e. <filename>tcmode-default.inc</filename>).
530 However, other patterns are accepted.
531 In particular, "external-*" refers to external toolchains of
532 which there are some basic examples included in the
533 OpenEmbedded Core (<filename>meta</filename>).
534 You can use your own custom toolchain definition in your own
535 layer (or as defined in the <filename>local.conf</filename>
536 file) at the location
537 <filename>conf/distro/include/tcmode-*.inc</filename>.
538 </para>
539
540 <para>
541 In addition to the toolchain configuration, you also need a
542 corresponding toolchain recipe file.
543 This recipe file needs to package up any pre-built objects in
544 the toolchain such as <filename>libgcc</filename>,
545 <filename>libstdcc++</filename>, any locales, and
546 <filename>libc</filename>.
547 An example is the
548 <filename>external-sourcery-toolchain.bb</filename>, which is
549 located in <filename>meta/recipes-core/meta/</filename> within
550 the Source Directory.
551 </para>
552
553 <para>
554 For information on installing and using cross-development
555 toolchains, see the
556 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
557 section in the Yocto Project Application Developer's Guide.
558 For general information on cross-development toolchains, see
559 the
560 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
561 section.
562 </para>
563 </answer>
564 </qandaentry>
565
566 <qandaentry>
567 <question>
568 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
569 How does the OpenEmbedded build system obtain source code and
570 will it work behind my firewall or proxy server?
571 </para>
572 </question>
573 <answer>
574 <para>
575 The way the build system obtains source code is highly
576 configurable.
577 You can setup the build system to get source code in most
578 environments if HTTP transport is available.
579 </para>
580 <para>
581 When the build system searches for source code, it first
582 tries the local download directory.
583 If that location fails, Poky tries
584 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
585 the upstream source, and then
586 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
587 in that order.
588 </para>
589 <para>
590 Assuming your distribution is "poky", the OpenEmbedded build
591 system uses the Yocto Project source
592 <filename>PREMIRRORS</filename> by default for SCM-based
593 sources, upstreams for normal tarballs, and then falls back
594 to a number of other mirrors including the Yocto Project
595 source mirror if those fail.
596 </para>
597 <para>
598 As an example, you could add a specific server for the
599 build system to attempt before any others by adding something
600 like the following to the <filename>local.conf</filename>
601 configuration file:
602 <literallayout class='monospaced'>
603 PREMIRRORS_prepend = "\
604 git://.*/.* http://www.yoctoproject.org/sources/ \n \
605 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
606 http://.*/.* http://www.yoctoproject.org/sources/ \n \
607 https://.*/.* http://www.yoctoproject.org/sources/ \n"
608 </literallayout>
609 </para>
610 <para>
611 These changes cause the build system to intercept Git, FTP,
612 HTTP, and HTTPS requests and direct them to the
613 <filename>http://</filename> sources mirror.
614 You can use <filename>file://</filename> URLs to point to
615 local directories or network shares as well.
616 </para>
617 <para>
618 Aside from the previous technique, these options also exist:
619 <literallayout class='monospaced'>
620 BB_NO_NETWORK = "1"
621 </literallayout>
622 This statement tells BitBake to issue an error instead of
623 trying to access the Internet.
624 This technique is useful if you want to ensure code builds
625 only from local sources.
626 </para>
627 <para>
628 Here is another technique:
629 <literallayout class='monospaced'>
630 BB_FETCH_PREMIRRORONLY = "1"
631 </literallayout>
632 This statement limits the build system to pulling source
633 from the <filename>PREMIRRORS</filename> only.
634 Again, this technique is useful for reproducing builds.
635 </para>
636 <para>
637 Here is another technique:
638 <literallayout class='monospaced'>
639 BB_GENERATE_MIRROR_TARBALLS = "1"
640 </literallayout>
641 This statement tells the build system to generate mirror
642 tarballs.
643 This technique is useful if you want to create a mirror server.
644 If not, however, the technique can simply waste time during
645 the build.
646 </para>
647 <para>
648 Finally, consider an example where you are behind an
649 HTTP-only firewall.
650 You could make the following changes to the
651 <filename>local.conf</filename> configuration file as long as
652 the <filename>PREMIRRORS</filename> server is current:
653 <literallayout class='monospaced'>
654 PREMIRRORS_prepend = "\
655 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
656 http://.*/.* http://www.yoctoproject.org/sources/ \n \
657 https://.*/.* http://www.yoctoproject.org/sources/ \n"
658 BB_FETCH_PREMIRRORONLY = "1"
659 </literallayout>
660 These changes would cause the build system to successfully
661 fetch source over HTTP and any network accesses to anything
662 other than the <filename>PREMIRRORS</filename> would fail.
663 </para>
664 <para>
665 The build system also honors the standard shell environment
666 variables <filename>http_proxy</filename>,
667 <filename>ftp_proxy</filename>,
668 <filename>https_proxy</filename>, and
669 <filename>all_proxy</filename> to redirect requests through
670 proxy servers.
671 </para>
672 </answer>
673 </qandaentry>
674
675 <qandaentry>
676 <question>
677 <para>
678 Can I get rid of build output so I can start over?
679 </para>
680 </question>
681 <answer>
682 <para>
683 Yes - you can easily do this.
684 When you use BitBake to build an image, all the build output
685 goes into the directory created when you run the
686 build environment setup script (i.e.
687 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
688 or
689 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
690 By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
691 is named <filename>build</filename> but can be named
692 anything you want.
693 </para>
694
695 <para>
696 Within the Build Directory, is the <filename>tmp</filename>
697 directory.
698 To remove all the build output yet preserve any source code or
699 downloaded files from previous builds, simply remove the
700 <filename>tmp</filename> directory.
701 </para>
702 </answer>
703 </qandaentry>
704
705
706</qandaset>
707</chapter>
708<!--
709vim: expandtab tw=80 ts=4
710-->
diff --git a/documentation/ref-manual/figures/analysis-for-package-splitting.png b/documentation/ref-manual/figures/analysis-for-package-splitting.png
new file mode 100644
index 0000000000..04f2794ea9
--- /dev/null
+++ b/documentation/ref-manual/figures/analysis-for-package-splitting.png
Binary files differ
diff --git a/documentation/ref-manual/figures/buildhistory-web.png b/documentation/ref-manual/figures/buildhistory-web.png
new file mode 100644
index 0000000000..f6db86c977
--- /dev/null
+++ b/documentation/ref-manual/figures/buildhistory-web.png
Binary files differ
diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/ref-manual/figures/buildhistory.png
new file mode 100644
index 0000000000..edf98d95cf
--- /dev/null
+++ b/documentation/ref-manual/figures/buildhistory.png
Binary files differ
diff --git a/documentation/ref-manual/figures/configuration-compile-autoreconf.png b/documentation/ref-manual/figures/configuration-compile-autoreconf.png
new file mode 100644
index 0000000000..a07464f04c
--- /dev/null
+++ b/documentation/ref-manual/figures/configuration-compile-autoreconf.png
Binary files differ
diff --git a/documentation/ref-manual/figures/cross-development-toolchains.png b/documentation/ref-manual/figures/cross-development-toolchains.png
new file mode 100644
index 0000000000..d36670a198
--- /dev/null
+++ b/documentation/ref-manual/figures/cross-development-toolchains.png
Binary files differ
diff --git a/documentation/ref-manual/figures/image-generation.png b/documentation/ref-manual/figures/image-generation.png
new file mode 100644
index 0000000000..5594658200
--- /dev/null
+++ b/documentation/ref-manual/figures/image-generation.png
Binary files differ
diff --git a/documentation/ref-manual/figures/images.png b/documentation/ref-manual/figures/images.png
new file mode 100644
index 0000000000..d99eac1fbf
--- /dev/null
+++ b/documentation/ref-manual/figures/images.png
Binary files differ
diff --git a/documentation/ref-manual/figures/layer-input.png b/documentation/ref-manual/figures/layer-input.png
new file mode 100644
index 0000000000..0a4f2e74f3
--- /dev/null
+++ b/documentation/ref-manual/figures/layer-input.png
Binary files differ
diff --git a/documentation/ref-manual/figures/package-feeds.png b/documentation/ref-manual/figures/package-feeds.png
new file mode 100644
index 0000000000..4bc311f3d6
--- /dev/null
+++ b/documentation/ref-manual/figures/package-feeds.png
Binary files differ
diff --git a/documentation/ref-manual/figures/patching.png b/documentation/ref-manual/figures/patching.png
new file mode 100644
index 0000000000..8ecd018502
--- /dev/null
+++ b/documentation/ref-manual/figures/patching.png
Binary files differ
diff --git a/documentation/ref-manual/figures/poky-title.png b/documentation/ref-manual/figures/poky-title.png
new file mode 100644
index 0000000000..2893d84620
--- /dev/null
+++ b/documentation/ref-manual/figures/poky-title.png
Binary files differ
diff --git a/documentation/ref-manual/figures/sdk-generation.png b/documentation/ref-manual/figures/sdk-generation.png
new file mode 100644
index 0000000000..c37e2748ca
--- /dev/null
+++ b/documentation/ref-manual/figures/sdk-generation.png
Binary files differ
diff --git a/documentation/ref-manual/figures/sdk.png b/documentation/ref-manual/figures/sdk.png
new file mode 100644
index 0000000000..a539cc52f0
--- /dev/null
+++ b/documentation/ref-manual/figures/sdk.png
Binary files differ
diff --git a/documentation/ref-manual/figures/source-fetching.png b/documentation/ref-manual/figures/source-fetching.png
new file mode 100644
index 0000000000..26aefb50c2
--- /dev/null
+++ b/documentation/ref-manual/figures/source-fetching.png
Binary files differ
diff --git a/documentation/ref-manual/figures/source-input.png b/documentation/ref-manual/figures/source-input.png
new file mode 100644
index 0000000000..f7515058ef
--- /dev/null
+++ b/documentation/ref-manual/figures/source-input.png
Binary files differ
diff --git a/documentation/ref-manual/figures/user-configuration.png b/documentation/ref-manual/figures/user-configuration.png
new file mode 100644
index 0000000000..f2b3f8e7fe
--- /dev/null
+++ b/documentation/ref-manual/figures/user-configuration.png
Binary files differ
diff --git a/documentation/ref-manual/figures/yocto-environment-ref.png b/documentation/ref-manual/figures/yocto-environment-ref.png
new file mode 100644
index 0000000000..650c6c8030
--- /dev/null
+++ b/documentation/ref-manual/figures/yocto-environment-ref.png
Binary files differ
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
new file mode 100644
index 0000000000..b1a5c0e175
--- /dev/null
+++ b/documentation/ref-manual/introduction.xml
@@ -0,0 +1,444 @@
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='intro'>
6<title>Introduction</title>
7
8<section id='intro-welcome'>
9 <title>Introduction</title>
10
11 <para>
12 This manual provides reference information for the current release of the Yocto Project.
13 The Yocto Project is an open-source collaboration project focused on embedded Linux
14 developers.
15 Amongst other things, the Yocto Project uses the OpenEmbedded build system, which
16 is based on the Poky project, to construct complete Linux images.
17 You can find complete introductory and getting started information on the Yocto Project
18 by reading the
19 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
20 For task-based information using the Yocto Project, see the
21 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>
22 and the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
23 For Board Support Package (BSP) structure information, see the
24 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
25 You can also find lots of Yocto Project information on the
26 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
27 </para>
28</section>
29
30<section id='intro-manualoverview'>
31 <title>Documentation Overview</title>
32 <para>
33 This reference manual consists of the following:
34 <itemizedlist>
35 <listitem><para><emphasis>
36 <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis>
37 Provides an overview of the components that make up the Yocto Project
38 followed by information about debugging images created in the Yocto Project.
39 </para></listitem>
40 <listitem><para><emphasis>
41 <link linkend='technical-details'>Technical Details</link>:</emphasis>
42 Describes fundamental Yocto Project components as well as an explanation
43 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
44 </para></listitem>
45 <listitem><para><emphasis>
46 <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
47 Describes the
48 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> created
49 either by unpacking a released Yocto Project tarball on your host development system,
50 or by cloning the upstream
51 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
52 </para></listitem>
53 <listitem><para><emphasis>
54 <link linkend='ref-bitbake'>BitBake</link>:</emphasis>
55 Provides an overview of the BitBake tool and its role within
56 the Yocto Project.</para></listitem>
57 <listitem><para><emphasis>
58 <link linkend='ref-classes'>Classes</link>:</emphasis>
59 Describes the classes used in the Yocto Project.</para></listitem>
60 <listitem><para><emphasis>
61 <link linkend='ref-images'>Images</link>:</emphasis>
62 Describes the standard images that the Yocto Project supports.
63 </para></listitem>
64 <listitem><para><emphasis>
65 <link linkend='ref-features'>Features</link>:</emphasis>
66 Describes mechanisms for creating distribution, machine, and image
67 features during the build process using the OpenEmbedded build system.</para></listitem>
68 <listitem><para><emphasis>
69 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
70 Presents most variables used by the OpenEmbedded build system, which
71 uses BitBake.
72 Entries describe the function of the variable and how to apply them.
73 </para></listitem>
74 <listitem><para><emphasis>
75 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
76 Provides variable locality or context.</para></listitem>
77 <listitem><para><emphasis>
78 <link linkend='faq'>FAQ</link>:</emphasis>
79 Provides answers for commonly asked questions in the Yocto Project
80 development environment.</para></listitem>
81 <listitem><para><emphasis>
82 <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
83 Provides guidance on how you can contribute back to the Yocto
84 Project.</para></listitem>
85 </itemizedlist>
86 </para>
87</section>
88
89
90<section id='intro-requirements'>
91<title>System Requirements</title>
92 <para>
93 For general Yocto Project system requirements, see the
94 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
95 in the Yocto Project Quick Start.
96 The remainder of this section provides details on system requirements
97 not covered in the Yocto Project Quick Start.
98 </para>
99
100 <section id='detailed-supported-distros'>
101 <title>Supported Linux Distributions</title>
102
103 <para>
104 Currently, the Yocto Project is supported on the following
105 distributions:
106 <note>
107 <para>
108 Yocto Project releases are tested against the stable Linux
109 distributions in the following list.
110 The Yocto Project should work on other distributions but
111 validation is not performed against them.
112 </para>
113
114 <para>
115 In particular, the Yocto Project does not support
116 and currently has no plans to support
117 rolling-releases or development distributions due to their
118 constantly changing nature.
119 We welcome patches and bug reports, but keep in mind that
120 our priority is on the supported platforms listed below.
121 </para>
122
123 <para>
124 Refer to
125 <ulink url='&OE_HOME_URL;/index.php?title=OEandYourDistro'>OE and Your Distro</ulink> and
126 <ulink url='&OE_HOME_URL;/index.php?title=Required_software'>Required Software</ulink>
127 for information for information about dependencies and
128 requirements.
129 If you encounter problems, please go to
130 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
131 and submit a bug.
132 We are interested in hearing about your experience.
133 </para>
134 </note>
135 <itemizedlist>
136<!-- <listitem><para>Ubuntu 10.04</para></listitem>
137 <listitem><para>Ubuntu 11.10</para></listitem> -->
138 <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
139 <listitem><para>Ubuntu 12.10</para></listitem>
140 <listitem><para>Ubuntu 13.04</para></listitem>
141<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
142 <listitem><para>Fedora 17 (Spherical)</para></listitem> -->
143 <listitem><para>Fedora release 18 (Spherical Cow)</para></listitem>
144 <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
145<!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem>
146 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
147 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
148 <listitem><para>CentOS release 6.3 (Final)</para></listitem> -->
149 <listitem><para>CentOS release 6.4</para></listitem>
150<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> -->
151 <listitem><para>Debian GNU/Linux 6.0.7 (Squeeze)</para></listitem>
152 <listitem><para>Debian GNU/Linux 7.0 (Wheezy)</para></listitem>
153 <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
154<!-- <listitem><para>openSUSE 11.4</para></listitem>
155 <listitem><para>openSUSE 12.1</para></listitem> -->
156 <listitem><para>openSUSE 12.2</para></listitem>
157 <listitem><para>openSUSE 12.3</para></listitem>
158 </itemizedlist>
159 </para>
160
161 <note>
162 While the Yocto Project Team attempts to ensure all Yocto Project
163 releases are one hundred percent compatible with each officially
164 supported Linux distribution, instances might exist where you
165 encounter a problem while using the Yocto Project on a specific
166 distribution.
167 For example, the CentOS 6.4 distribution does not include the
168 Gtk+ 2.20.0 and PyGtk 2.21.0 (or higher) packages, which are
169 required to run
170 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
171 </note>
172 </section>
173
174 <section id='required-packages-for-the-host-development-system'>
175 <title>Required Packages for the Host Development System</title>
176
177 <para>
178 The list of packages you need on the host development system can
179 be large when covering all build scenarios using the Yocto Project.
180 This section provides required packages according to
181 Linux distribution and function.
182 </para>
183
184 <section id='ubuntu-packages'>
185 <title>Ubuntu and Debian</title>
186
187 <para>
188 The following list shows the required packages by function
189 given a supported Ubuntu or Debian Linux distribution:
190 <itemizedlist>
191 <listitem><para><emphasis>Essentials:</emphasis>
192 Packages needed to build an image on a headless
193 system:
194 <literallayout class='monospaced'>
195 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
196 </literallayout></para></listitem>
197 <listitem><para><emphasis>Graphical Extras:</emphasis>
198 Packages recommended if the host system has graphics support:
199 <literallayout class='monospaced'>
200 $ sudo apt-get install libsdl1.2-dev xterm
201 </literallayout></para></listitem>
202 <listitem><para><emphasis>Documentation:</emphasis>
203 Packages needed if you are going to build out the
204 Yocto Project documentation manuals:
205 <literallayout class='monospaced'>
206 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
207 </literallayout></para></listitem>
208 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
209 Packages needed if you are going to be using the
210 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
211 <literallayout class='monospaced'>
212 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
213 </literallayout></para></listitem>
214 </itemizedlist>
215 </para>
216 </section>
217
218 <section id='fedora-packages'>
219 <title>Fedora Packages</title>
220
221 <para>
222 The following list shows the required packages by function
223 given a supported Fedora Linux distribution:
224 <itemizedlist>
225 <listitem><para><emphasis>Essentials:</emphasis>
226 Packages needed to build an image for a headless
227 system:
228 <literallayout class='monospaced'>
229 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
230 </literallayout></para></listitem>
231 <listitem><para><emphasis>Graphical Extras:</emphasis>
232 Packages recommended if the host system has graphics support:
233 <literallayout class='monospaced'>
234 $ sudo yum install SDL-devel xterm
235 </literallayout></para></listitem>
236 <listitem><para><emphasis>Documentation:</emphasis>
237 Packages needed if you are going to build out the
238 Yocto Project documentation manuals:
239 <literallayout class='monospaced'>
240 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
241 docbook-dtds docbook-utils fop libxslt dblatex xmlto
242 </literallayout></para></listitem>
243 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
244 Packages needed if you are going to be using the
245 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
246 <literallayout class='monospaced'>
247 $ sudo yum install autoconf automake libtool glib2-devel
248 </literallayout></para></listitem>
249 </itemizedlist>
250 </para>
251 </section>
252
253 <section id='opensuse-packages'>
254 <title>OpenSUSE Packages</title>
255
256 <para>
257 The following list shows the required packages by function
258 given a supported OpenSUSE Linux distribution:
259 <itemizedlist>
260 <listitem><para><emphasis>Essentials:</emphasis>
261 Packages needed to build an image for a headless
262 system:
263 <literallayout class='monospaced'>
264 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
265 </literallayout></para></listitem>
266 <listitem><para><emphasis>Graphical Extras:</emphasis>
267 Packages recommended if the host system has graphics support:
268 <literallayout class='monospaced'>
269 $ sudo zypper install libSDL-devel xterm
270 </literallayout></para></listitem>
271 <listitem><para><emphasis>Documentation:</emphasis>
272 Packages needed if you are going to build out the
273 Yocto Project documentation manuals:
274 <literallayout class='monospaced'>
275 $ sudo zypper install make fop xsltproc dblatex xmlto
276 </literallayout></para></listitem>
277 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
278 Packages needed if you are going to be using the
279 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
280 <literallayout class='monospaced'>
281 $ sudo zypper install autoconf automake libtool glib2-devel
282 </literallayout></para></listitem>
283 </itemizedlist>
284 </para>
285 </section>
286
287 <section id='centos-packages'>
288 <title>CentOS Packages</title>
289
290 <para>
291 The following list shows the required packages by function
292 given a supported CentOS Linux distribution:
293 <note>Depending on the CentOS version you are using, other requirements
294 and dependencies might exist.
295 For details, you should look at the CentOS sections on the
296 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
297 wiki page.
298 </note>
299 <itemizedlist>
300 <listitem><para><emphasis>Essentials:</emphasis>
301 Packages needed to build an image for a headless
302 system:
303 <literallayout class='monospaced'>
304 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;
305 </literallayout></para></listitem>
306 <listitem><para><emphasis>Graphical Extras:</emphasis>
307 Packages recommended if the host system has graphics support:
308 <literallayout class='monospaced'>
309 $ sudo yum install SDL-devel xterm
310 </literallayout></para></listitem>
311 <listitem><para><emphasis>Documentation:</emphasis>
312 Packages needed if you are going to build out the
313 Yocto Project documentation manuals:
314 <literallayout class='monospaced'>
315 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
316 docbook-dtds docbook-utils fop libxslt dblatex xmlto
317 </literallayout></para></listitem>
318 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
319 Packages needed if you are going to be using the
320 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
321 <literallayout class='monospaced'>
322 $ sudo yum install autoconf automake libtool glib2-devel
323 </literallayout></para></listitem>
324 </itemizedlist>
325 </para>
326 </section>
327 </section>
328
329 <section id='required-git-tar-and-python-versions'>
330 <title>Required Git, tar, and Python Versions</title>
331
332 <para>
333 In order to use the build system, your host development system
334 must meet the following version requirements for Git, tar, and
335 Python:
336 <itemizedlist>
337 <listitem><para>Git 1.7.5 or greater</para></listitem>
338 <listitem><para>tar 1.24 or greater</para></listitem>
339 <listitem><para>Python 2.7.3 or greater not including
340 Python 3.x, which is not supported.</para></listitem>
341 </itemizedlist>
342 </para>
343
344 <para>
345 If your host development system does not meet all these requirements,
346 you can resolve this by either downloading a pre-built tarball
347 containing these tools, or building such a tarball on another
348 system.
349 Regardless of the method, once you have the tarball you simply
350 install it somewhere on you system, such as a directory in your
351 home directory, and then source the environment script provided,
352 which adds the tools into <filename>PATH</filename> and sets
353 any other environment variables required to run the tools.
354 Doing so gives you working versions of Git, tar, Python and
355 <filename>chrpath</filename>.
356 </para>
357
358 <para>
359 If downloading a pre-built tarball, locate the
360 <filename>*.sh</filename> at
361 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-1.5/buildtools/'></ulink>.
362 </para>
363
364 <para>
365 If building your own tarball, do so using this command:
366 <literallayout class='monospaced'>
367 $ bitbake buildtools-tarball
368 </literallayout>
369 <note>
370 The <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
371 variable determines whether you build tools for a 32-bit
372 or 64-bit system.
373 </note>
374 Once the build completes, you can find the file that installs the
375 the tools in the <filename>tmp/deploy/sdk</filename> subdirectory
376 of the
377 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
378 The file used to install the tarball has the string "buildtools"
379 in the name.
380 </para>
381
382 <para>
383 After you have either built the tarball or downloaded it, you need
384 to install it.
385 Install the tools by executing the <filename>*.sh</filename> file.
386 During execution, a prompt appears that allows you to choose the
387 installation directory.
388 For example, you could choose the following:
389 <literallayout class='monospaced'>
390 /home/your-username/sdk
391 </literallayout>
392 </para>
393
394 <para>
395 The final step before you can actually use the tools is to source
396 the tools environment with a command like the following:
397 <literallayout class='monospaced'>
398 $ source /home/your-username/sdk/environment-setup-i586-poky-linux
399 </literallayout>
400 Of course, you need to supply your installation directory and be
401 sure to use the right file (i.e. i585 or x86-64).
402 </para>
403 </section>
404</section>
405
406<section id='intro-getit'>
407 <title>Obtaining the Yocto Project</title>
408 <para>
409 The Yocto Project development team makes the Yocto Project available through a number
410 of methods:
411 <itemizedlist>
412 <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through
413 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
414 <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at
415 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
416 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
417 experimental builds.</para></listitem>
418 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases
419 of the Yocto Project and supported BSPs at the
420 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
421 Along with these downloads, you can find lots of other information at this site.
422 </para></listitem>
423 </itemizedlist>
424 </para>
425</section>
426
427<section id='intro-getit-dev'>
428 <title>Development Checkouts</title>
429 <para>
430 Development using the Yocto Project requires a local
431 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
432 You can set up the Source Directory by downloading a Yocto Project release tarball and unpacking it,
433 or by cloning a copy of the upstream
434 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
435 For information on both these methods, see the
436 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
437 section in the Yocto Project Development Manual.
438 </para>
439</section>
440
441</chapter>
442<!--
443vim: expandtab tw=80 ts=4
444-->
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
new file mode 100644
index 0000000000..bb6203998b
--- /dev/null
+++ b/documentation/ref-manual/migration.xml
@@ -0,0 +1,1089 @@
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='migration'>
6<title>Migrating to a Newer Yocto Project Release</title>
7
8 <para>
9 This chapter provides information you can use to migrate work to a
10 newer Yocto Project release. You can find the same information in the
11 release notes for a given release.
12 </para>
13
14<section id='moving-to-the-yocto-project-1.3-release'>
15 <title>Moving to the Yocto Project 1.3 Release</title>
16
17 <para>
18 This section provides migration information for moving to the
19 Yocto Project 1.3 Release from the prior release.
20 </para>
21
22 <section id='1.3-local-configuration'>
23 <title>Local Configuration</title>
24
25 <para>
26 Differences include changes for
27 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
28 and <filename>bblayers.conf</filename>.
29 </para>
30
31 <section id='migration-1.3-sstate-mirrors'>
32 <title>SSTATE_MIRRORS</title>
33
34 <para>
35 The shared state cache (sstate-cache), as pointed to by
36 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, by default
37 now has two-character subdirectories to prevent issues rising
38 from too many files in the same directory.
39 Also, native sstate-cache packages will go into a subdirectory named using
40 the distro ID string.
41 If you copy the newly structured sstate-cache to a mirror location
42 (either local or remote) and then point to it in
43 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
44 you need to append "PATH" to the end of the mirror URL so that
45 the path used by BitBake before the mirror substitution is
46 appended to the path used to access the mirror.
47 Here is an example:
48 <literallayout class='monospaced'>
49 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
50 </literallayout>
51 </para>
52 </section>
53
54 <section id='migration-1.3-bblayers-conf'>
55 <title>bblayers.conf</title>
56
57 <para>
58 The <filename>meta-yocto</filename> layer consists of two parts
59 that correspond to the Poky reference distribution and the
60 reference hardware Board Support Packages (BSPs), respectively:
61 <filename>meta-yocto</filename> and
62 <filename>meta-yocto-bsp</filename>.
63 When running BitBake or Hob for the first time after upgrading,
64 your <filename>conf/bblayers.conf</filename> file will be
65 updated to handle this change and you will be asked to
66 re-run or restart for the changes to take effect.
67 </para>
68 </section>
69 </section>
70
71 <section id='1.3-recipes'>
72 <title>Recipes</title>
73
74 <para>
75 Differences include changes for the following:
76 <itemizedlist>
77 <listitem><para>Python function whitespace</para></listitem>
78 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
79 <listitem><para><filename>nativesdk</filename></para></listitem>
80 <listitem><para>Task recipes</para></listitem>
81 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
82 <listitem><para>Removed recipes</para></listitem>
83 </itemizedlist>
84 </para>
85
86 <section id='migration-1.3-python-function-whitespace'>
87 <title>Python Function Whitespace</title>
88
89 <para>
90 All Python functions must now use four spaces for indentation.
91 Previously, an inconsistent mix of spaces and tabs existed,
92 which made extending these functions using
93 <filename>_append</filename> or <filename>_prepend</filename>
94 complicated given that Python treats whitespace as
95 syntactically significant.
96 If you are defining or extending any Python functions (e.g.
97 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
98 <filename>do_patch</filename> and so forth) in custom recipes
99 or classes, you need to ensure you are using consistent
100 four-space indentation.
101 </para>
102 </section>
103
104 <section id='migration-1.3-proto=-in-src-uri'>
105 <title>proto= in SRC_URI</title>
106
107 <para>
108 Any use of <filename>proto=</filename> in
109 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
110 needs to be changed to <filename>protocol=</filename>.
111 In particular, this applies to the following URIs:
112 <itemizedlist>
113 <listitem><para><filename>svn://</filename></para></listitem>
114 <listitem><para><filename>bzr://</filename></para></listitem>
115 <listitem><para><filename>hg://</filename></para></listitem>
116 <listitem><para><filename>osc://</filename></para></listitem>
117 </itemizedlist>
118 Other URIs were already using <filename>protocol=</filename>.
119 This change improves consistency.
120 </para>
121 </section>
122
123 <section id='migration-1.3-nativesdk'>
124 <title>nativesdk</title>
125
126 <para>
127 The suffix <filename>nativesdk</filename> is now implemented
128 as a prefix, which simplifies a lot of the packaging code for
129 <filename>nativesdk</filename> recipes.
130 All custom <filename>nativesdk</filename> recipes and any
131 references need to be updated to use
132 <filename>nativesdk-*</filename> instead of
133 <filename>*-nativesdk</filename>.
134 </para>
135 </section>
136
137 <section id='migration-1.3-task-recipes'>
138 <title>Task Recipes</title>
139
140 <para>
141 "Task" recipes are now known as "Package groups" and have
142 been renamed from <filename>task-*.bb</filename> to
143 <filename>packagegroup-*.bb</filename>.
144 Existing references to the previous <filename>task-*</filename>
145 names should work in most cases as there is an automatic
146 upgrade path for most packages.
147 However, you should update references in your own recipes and
148 configurations as they could be removed in future releases.
149 You should also rename any custom <filename>task-*</filename>
150 recipes to <filename>packagegroup-*</filename>, and change
151 them to inherit <filename>packagegroup</filename> instead of
152 <filename>task</filename>, as well as taking the opportunity
153 to remove anything now handled by
154 <filename>packagegroup.bbclass</filename>, such as providing
155 <filename>-dev</filename> and <filename>-dbg</filename>
156 packages, setting
157 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
158 and so forth.
159 See the
160 "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>"
161 section for further details.
162 </para>
163 </section>
164
165 <section id='migration-1.3-image-features'>
166 <title>IMAGE_FEATURES</title>
167
168 <para>
169 Image recipes that previously included "apps-console-core"
170 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
171 should now include "splash" instead to enable the boot-up
172 splash screen.
173 Retaining "apps-console-core" will still include the splash
174 screen but generates a warning.
175 The "apps-x11-core" and "apps-x11-games"
176 <filename>IMAGE_FEATURES</filename> features have been removed.
177 </para>
178 </section>
179
180 <section id='migration-1.3-removed-recipes'>
181 <title>Removed Recipes</title>
182
183 <para>
184 The following recipes have been removed.
185 For most of them, it is unlikely that you would have any
186 references to them in your own
187 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>.
188 However, you should check your metadata against this list to be sure:
189 <itemizedlist>
190 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
191 Replaced by <filename>libx11</filename>, which has a negligible
192 size difference with modern Xorg.</para></listitem>
193 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
194 Use <filename>xserver-xorg</filename>, which has a negligible
195 size difference when DRI and GLX modules are not installed.</para></listitem>
196 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
197 Effectively unmaintained for many years.</para></listitem>
198 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
199 No longer serves any purpose.</para></listitem>
200 <listitem><para><emphasis><filename>galago</filename></emphasis>:
201 Replaced by telepathy.</para></listitem>
202 <listitem><para><emphasis><filename>gail</filename></emphasis>:
203 Functionality was integrated into GTK+ 2.13.</para></listitem>
204 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
205 No longer needed.</para></listitem>
206 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
207 The build has been restructured to avoid the need for
208 this step.</para></listitem>
209 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
210 Unmaintained for many years.
211 Functionality now provided by
212 <filename>ofono</filename> instead.</para></listitem>
213 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
214 Largely unmaintained PIM application suite.
215 It has been moved to <filename>meta-gnome</filename>
216 in <filename>meta-openembedded</filename>.</para></listitem>
217 </itemizedlist>
218 In addition to the previously listed changes, the
219 <filename>meta-demoapps</filename> directory has also been removed
220 because the recipes in it were not being maintained and many
221 had become obsolete or broken.
222 Additionally, these recipes were not parsed in the default configuration.
223 Many of these recipes are already provided in an updated and
224 maintained form within the OpenEmbedded community layers such as
225 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
226 For the remainder, you can now find them in the
227 <filename>meta-extras</filename> repository, which is in the
228 Yocto Project
229 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>.
230 </para>
231 </section>
232 </section>
233
234 <section id='1.3-linux-kernel-naming'>
235 <title>Linux Kernel Naming</title>
236
237 <para>
238 The naming scheme for kernel output binaries has been changed to
239 now include
240 <link linkend='var-PE'><filename>PE</filename></link> as part of the
241 filename:
242 <literallayout class='monospaced'>
243 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
244 </literallayout>
245 </para>
246
247 <para>
248 Because the <filename>PE</filename> variable is not set by default,
249 these binary files could result with names that include two dash
250 characters.
251 Here is an example:
252 <literallayout class='monospaced'>
253 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
254 </literallayout>
255 </para>
256 </section>
257</section>
258
259<section id='moving-to-the-yocto-project-1.4-release'>
260 <title>Moving to the Yocto Project 1.4 Release</title>
261
262 <para>
263 This section provides migration information for moving to the
264 Yocto Project 1.4 Release from the prior release.
265 </para>
266
267 <section id='migration-1.4-bitbake'>
268 <title>BitBake</title>
269
270 <para>
271 Differences include the following:
272 <itemizedlist>
273 <listitem><para><emphasis>Comment Continuation:</emphasis>
274 If a comment ends with a line continuation (\) character,
275 then the next line must also be a comment.
276 Any instance where this is not the case, now triggers
277 a warning.
278 You must either remove the continuation character, or be
279 sure the next line is a comment.
280 </para></listitem>
281 <listitem><para><emphasis>Package Name Overrides:</emphasis>
282 The runtime package specific variables
283 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
284 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
285 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
286 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
287 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
288 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
289 <link linkend='var-FILES'><filename>FILES</filename></link>,
290 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
291 and the pre, post, install, and uninstall script functions
292 <filename>pkg_preinst</filename>,
293 <filename>pkg_postinst</filename>,
294 <filename>pkg_prerm</filename>, and
295 <filename>pkg_postrm</filename> should always have a
296 package name override.
297 For example, use <filename>RDEPENDS_${PN}</filename> for
298 the main package instead of <filename>RDEPENDS</filename>.
299 BitBake uses more strict checks when it parses recipes.
300 </para></listitem>
301 </itemizedlist>
302 </para>
303 </section>
304
305 <section id='migration-1.4-build-behavior'>
306 <title>Build Behavior</title>
307
308 <para>
309 Differences include the following:
310 <itemizedlist>
311 <listitem><para><emphasis>Shared State Code:</emphasis>
312 The shared state code has been optimized to avoid running
313 unnecessary tasks.
314 For example,
315 <filename>bitbake -c rootfs some-image</filename> from
316 shared state no longer populates the target sysroot
317 since that is not necessary.
318 Instead, the system just needs to extract the output
319 package contents, re-create the packages, and construct
320 the root filesystem.
321 This change is unlikely to cause any problems unless
322 you have missing declared dependencies.
323 </para></listitem>
324 <listitem><para><emphasis>Scanning Directory Names:</emphasis>
325 When scanning for files in
326 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
327 the build system now uses
328 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
329 instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
330 for the directory names.
331 In general, the values previously in
332 <filename>OVERRIDES</filename> are now in
333 <filename>FILESOVERRIDES</filename> as well.
334 However, if you relied upon an additional value
335 you previously added to <filename>OVERRIDES</filename>,
336 you might now need to add it to
337 <filename>FILESOVERRIDES</filename> unless you are already
338 adding it through the
339 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>
340 or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
341 variables, as appropriate.
342 For more related changes, see the
343 "<link linkend='migration-1.4-variables'>Variables</link>"
344 section.
345 </para></listitem>
346 </itemizedlist>
347 </para>
348 </section>
349
350
351 <section id='migration-1.4-proxies-and-fetching-source'>
352 <title>Proxies and Fetching Source</title>
353
354 <para>
355 A new <filename>oe-git-proxy</filename> script has been added to
356 replace previous methods of handling proxies and fetching source
357 from Git.
358 See the <filename>meta-yocto/conf/site.conf.sample</filename> file
359 for information on how to use this script.
360 </para>
361 </section>
362
363 <section id='migration-1.4-custom-interfaces-file-netbase-change'>
364 <title>Custom Interfaces File (netbase change)</title>
365
366 <para>
367 If you have created your own custom
368 <filename>etc/network/interfaces</filename> file by creating
369 an append file for the <filename>netbase</filename> recipe,
370 you now need to create an append file for the
371 <filename>init-ifupdown</filename> recipe instead, which you can
372 find in the
373 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
374 at <filename>meta/recipes-core/init-ifupdown</filename>.
375 For information on how to use append files, see the
376 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
377 in the Yocto Project Development Manual.
378 </para>
379 </section>
380
381 <section id='migration-1.4-remote-debugging'>
382 <title>Remote Debugging</title>
383
384 <para>
385 Support for remote debugging with the Eclipse IDE is now
386 separated into an image feature
387 (<filename>eclipse-debug</filename>) that corresponds to the
388 <filename>packagegroup-core-eclipse-debug</filename> package group.
389 Previously, the debugging feature was included through the
390 <filename>tools-debug</filename> image feature, which corresponds
391 to the <filename>packagegroup-core-tools-debug</filename>
392 package group.
393 </para>
394 </section>
395
396 <section id='migration-1.4-variables'>
397 <title>Variables</title>
398
399 <para>
400 The following variables have changed:
401 <itemizedlist>
402 <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
403 This variable now uses a distribution ID, which is composed
404 of the host distributor ID followed by the release.
405 Previously,
406 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
407 was composed of the description field.
408 For example, "Ubuntu 12.10" becomes "Ubuntu-12.10".
409 You do not need to worry about this change if you are not
410 specifically setting this variable, or if you are
411 specifically setting it to "".
412 </para></listitem>
413 <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
414 The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>,
415 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>,
416 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>,
417 and <filename>FILE_DIRNAME</filename> directories have been
418 dropped from the default value of the
419 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
420 variable, which is used as the search path for finding files
421 referred to in
422 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
423 If you have a recipe that relied upon these directories,
424 which would be unusual, then you will need to add the
425 appropriate paths within the recipe or, alternatively,
426 rearrange the files.
427 The most common locations are still covered by
428 <filename>${BP}</filename>, <filename>${BPN}</filename>,
429 and "files", which all remain in the default value of
430 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
431 </para></listitem>
432 </itemizedlist>
433 </para>
434 </section>
435
436 <section id='migration-target-package-management-with-rpm'>
437 <title>Target Package Management with RPM</title>
438
439 <para>
440 If runtime package management is enabled and the RPM backend
441 is selected, Smart is now installed for package download, dependency
442 resolution, and upgrades instead of Zypper.
443 For more information on how to use Smart, run the following command
444 on the target:
445 <literallayout class='monospaced'>
446 smart --help
447 </literallayout>
448 </para>
449 </section>
450
451 <section id='migration-1.4-recipes-moved'>
452 <title>Recipes Moved</title>
453
454 <para>
455 The following recipes were moved from their previous locations
456 because they are no longer used by anything in
457 the OpenEmbedded-Core:
458 <itemizedlist>
459 <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis>
460 Now resides in the <filename>meta-oe</filename> layer.
461 </para></listitem>
462 <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis>
463 Now resides in the <filename>meta-gnome</filename> layer.
464 </para></listitem>
465 <listitem><para><emphasis><filename>gthumb</filename>:</emphasis>
466 Now resides in the <filename>meta-gnome</filename> layer.
467 </para></listitem>
468 <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis>
469 Now resides in the <filename>meta-oe</filename> layer.
470 </para></listitem>
471 <listitem><para><emphasis><filename>gupnp</filename>:</emphasis>
472 Now resides in the <filename>meta-multimedia</filename> layer.
473 </para></listitem>
474 <listitem><para><emphasis><filename>gypsy</filename>:</emphasis>
475 Now resides in the <filename>meta-oe</filename> layer.
476 </para></listitem>
477 <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis>
478 Now resides in the <filename>meta-gnome</filename> layer.
479 </para></listitem>
480 <listitem><para><emphasis><filename>libgdata</filename>:</emphasis>
481 Now resides in the <filename>meta-gnome</filename> layer.
482 </para></listitem>
483 <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis>
484 Now resides in the <filename>meta-multimedia</filename> layer.
485 </para></listitem>
486 <listitem><para><emphasis><filename>metacity</filename>:</emphasis>
487 Now resides in the <filename>meta-gnome</filename> layer.
488 </para></listitem>
489 <listitem><para><emphasis><filename>polkit</filename>:</emphasis>
490 Now resides in the <filename>meta-oe</filename> layer.
491 </para></listitem>
492 <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis>
493 Now resides in the <filename>meta-networking</filename> layer.
494 </para></listitem>
495 </itemizedlist>
496 </para>
497 </section>
498
499 <section id='migration-1.4-removals-and-renames'>
500 <title>Removals and Renames</title>
501
502 <para>
503 The following list shows what has been removed or renamed:
504 <itemizedlist>
505 <listitem><para><emphasis><filename>evieext</filename>:</emphasis>
506 Removed because it has been removed from
507 <filename>xserver</filename> since 2008.
508 </para></listitem>
509 <listitem><para><emphasis>Gtk+ DirectFB:</emphasis>
510 Removed support because upstream Gtk+ no longer supports it
511 as of version 2.18.
512 </para></listitem>
513 <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis>
514 Removed because they were removed from the Xorg server in 2008.
515 </para></listitem>
516 <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis>
517 Removed because the XPrint server was removed from
518 Xorg in 2008.
519 </para></listitem>
520 <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis>
521 Removed because their functionality was broken upstream.
522 </para></listitem>
523 <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis>
524 Removed with linux-yocto 3.8 kernel being added.
525 The linux-yocto 3.2 and linux-yocto 3.4 kernels remain
526 as part of the release.
527 </para></listitem>
528 <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis>
529 Removed with functionality now provided by
530 <filename>lsbtest</filename>.
531 </para></listitem>
532 <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis>
533 Removed because it was never more than a proof-of-concept.
534 </para></listitem>
535 <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis>
536 Removed because they are not maintained.
537 However, <filename>matchbox-wm</filename> and
538 <filename>matchbox-theme-sato</filename> are still
539 provided.
540 </para></listitem>
541 <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis>
542 Renamed to <filename>mesa</filename>.
543 </para></listitem>
544 <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis>
545 Removed because it was no longer useful.
546 </para></listitem>
547 <listitem><para><emphasis><filename>mutter</filename>:</emphasis>
548 Removed because nothing ever uses it and the recipe is
549 very old.
550 </para></listitem>
551 <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis>
552 Removed because it has become obsolete.
553 </para></listitem>
554 <listitem><para><emphasis><filename>update-modules</filename>:</emphasis>
555 Removed because it is no longer used.
556 The kernel module <filename>postinstall</filename> and
557 <filename>postrm</filename> scripts can now do the same
558 task without the use of this script.
559 </para></listitem>
560 <listitem><para><emphasis><filename>web</filename>:</emphasis>
561 Removed because it is not maintained. Superseded by
562 <filename>web-webkit</filename>.
563 </para></listitem>
564 <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis>
565 Removed because upstream it has been disabled by default
566 since 2007.
567 Nothing uses <filename>xf86bigfontproto</filename>.
568 </para></listitem>
569 <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis>
570 Removed because its dependency in
571 <filename>xserver</filename> was spurious and it was
572 removed in 2005.
573 </para></listitem>
574 <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis>
575 Removed and been functionally replaced with Smart
576 (<filename>python-smartpm</filename>) when RPM packaging
577 is used and package management is enabled on the target.
578 </para></listitem>
579 </itemizedlist>
580 </para>
581 </section>
582</section>
583
584<section id='moving-to-the-yocto-project-1.5-release'>
585 <title>Moving to the Yocto Project 1.5 Release</title>
586
587 <para>
588 This section provides migration information for moving to the
589 Yocto Project 1.5 Release from the prior release.
590 </para>
591
592 <section id='migration-1.5-host-dependency-changes'>
593 <title>Host Dependency Changes</title>
594
595 <para>
596 The OpenEmbedded build system now has some additional requirements
597 on the host system:
598 <itemizedlist>
599 <listitem><para>Python 2.7.3+</para></listitem>
600 <listitem><para>Tar 1.24+</para></listitem>
601 <listitem><para>Git 1.7.5+</para></listitem>
602 <listitem><para>Patched version of Make if you are using
603 3.82.
604 Most distributions that provide Make 3.82 use the patched
605 version.</para></listitem>
606 </itemizedlist>
607 If the Linux distribution you are using on your build host
608 does not provide packages for these, you can install and use
609 the Buildtools tarball, which provides an SDK-like environment
610 containing them.
611 </para>
612
613 <para>
614 For more information on this requirement, see the
615 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
616 section.
617 </para>
618 </section>
619
620 <section id='migration-1.5-atom-pc-bsp'>
621 <title><filename>atom-pc</filename> Board Support Package (BSP)</title>
622
623 <para>
624 The <filename>atom-pc</filename> hardware reference BSP has been
625 replaced by a <filename>genericx86</filename> BSP.
626 This BSP is not necessarily guaranteed to work on all x86
627 hardware, but it will run on a wider range of systems than the
628 <filename>atom-pc</filename> did.
629 <note>
630 Additionally, a <filename>genericx86-64</filename> BSP has been
631 added for 64-bit systems.
632 </note>
633 </para>
634 </section>
635
636 <section id='migration-1.5-bitbake'>
637 <title>BitBake</title>
638
639 <para>
640 The following changes have been made that relate to BitBake:
641 <itemizedlist>
642 <listitem><para>
643 BitBake now supports a <filename>_remove</filename>
644 operator.
645 The addition of this operator means you will have to
646 rename any items in recipe space (functions, variables)
647 whose names currently contain
648 <filename>_remove_</filename> or end with
649 <filename>_remove</filename> to avoid unexpected behavior.
650 </para></listitem>
651 <listitem><para>
652 BitBake's global method pool has been removed.
653 This method is not particularly useful and led to clashes
654 between recipes containing functions that had the
655 same name.</para></listitem>
656 <listitem><para>
657 The "none" server backend has been removed.
658 The "process" server backend has been serving well as the
659 default for a long time now.</para></listitem>
660 <listitem><para>
661 The <filename>bitbake-runtask</filename> script has been
662 removed.</para></listitem>
663 <listitem><para>
664 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
665 and
666 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
667 are no longer added to
668 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
669 by default in <filename>bitbake.conf</filename>.
670 These version-specific <filename>PROVIDES</filename>
671 items were seldom used.
672 Attempting to use them could result in two versions being
673 built simultaneously rather than just one version due to
674 the way BitBake resolves dependencies.</para></listitem>
675 </itemizedlist>
676 </para>
677 </section>
678
679 <section id='migration-1.5-qa-warnings'>
680 <title>QA Warnings</title>
681
682 <para>
683 The following changes have been made to the package QA checks:
684 <itemizedlist>
685 <listitem><para>
686 If you have customized
687 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
688 or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>
689 values in your configuration, check that they contain all of
690 the issues that you wish to be reported.
691 Previous Yocto Project versions contained a bug that meant
692 that any item not mentioned in <filename>ERROR_QA</filename>
693 or <filename>WARN_QA</filename> would be treated as a
694 warning.
695 Consequently, several important items were not already in
696 the default value of <filename>WARN_QA</filename>.
697 All of the possible QA checks are now documented in the
698 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
699 section.</para></listitem>
700 <listitem><para>
701 An additional QA check has been added to check if
702 <filename>/usr/share/info/dir</filename> is being installed.
703 Your recipe should delete this file within
704 <filename>do_install</filename> if "make install" is
705 installing it.</para></listitem>
706 <listitem><para>
707 If you are using the buildhistory class, the check for the
708 package version going backwards is now controlled using a
709 standard QA check.
710 Thus, if you have customized your
711 <filename>ERROR_QA</filename> or
712 <filename>WARN_QA</filename> values and still wish to have
713 this check performed, you should add
714 "version-going-backwards" to your value for one or the
715 other variables depending on how you wish it to be handled.
716 See the documented QA checks in the
717 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
718 section.
719 </para></listitem>
720 </itemizedlist>
721 </para>
722 </section>
723
724 <section id='migration-1.5-directory-layout-changes'>
725 <title>Directory Layout Changes</title>
726
727 <para>
728 The following directory changes exist:
729 <itemizedlist>
730 <listitem><para>
731 Output SDK installer files are now named to include the
732 image name and tuning architecture through the
733 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
734 variable.</para></listitem>
735 <listitem><para>
736 Images and related files are now installed into a directory
737 that is specific to the machine, instead of a parent
738 directory containing output files for multiple machines.
739 The
740 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
741 variable continues to point to the directory containing
742 images for the current
743 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
744 and should be used anywhere there is a need to refer to
745 this directory.
746 The <filename>runqemu</filename> script now uses this
747 variable to find images and kernel binaries and will use
748 BitBake to determine the directory.
749 Alternatively, you can set the
750 <filename>DEPLOY_DIR_IMAGE</filename> variable in the
751 external environment.</para></listitem>
752 <listitem><para>
753 When buildhistory is enabled, its output is now written
754 under the
755 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
756 rather than
757 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>.
758 Doing so makes it a easier to delete
759 <filename>TMPDIR</filename> and preserve the build history.
760 Additionally, data for produced SDKs is now split by
761 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>.
762 </para></listitem>
763 <listitem><para>
764 The <filename>pkgdata</filename> directory produced as
765 part of the packaging process has been collapsed into a
766 single machine-specific directory.
767 This directory is located under
768 <filename>sysroots</filename> and uses a machine-specific
769 name (i.e.
770 <filename>tmp/sysroots/&lt;machine&gt;/pkgdata</filename>).
771 </para></listitem>
772 </itemizedlist>
773 </para>
774 </section>
775
776 <section id='migration-1.5-shortened-git-srcrev-values'>
777 <title>Shortened Git <filename>SRCREV</filename> Values</title>
778
779 <para>
780 BitBake will now shorten revisions from Git repositories from the
781 normal 40 characters down to 10 characters within
782 <link linkend='var-SRCPV'><filename>SRCPV</filename></link>
783 for improved usability in path and file names.
784 This change should be safe within contexts where these revisions
785 are used because the chances of spatially close collisions
786 is very low.
787 Distant collisions are not a major issue in the way
788 the values are used.
789 </para>
790 </section>
791
792 <section id='migration-1.5-image-features'>
793 <title><filename>IMAGE_FEATURES</filename></title>
794
795 <para>
796 The following changes have been made that relate to
797 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
798 <itemizedlist>
799 <listitem><para>
800 The value of
801 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
802 is now validated to ensure invalid feature items are not
803 added.
804 Some users mistakenly add package names to this variable
805 instead of using
806 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
807 in order to have the package added to the image, which does
808 not work.
809 This change is intended to catch those kinds of situations.
810 Valid <filename>IMAGE_FEATURES</filename> are drawn from
811 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
812 definitions,
813 <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
814 and a new "validitems" varflag on
815 <filename>IMAGE_FEATURES</filename>.
816 The "validitems" varflag change allows additional features
817 to be added if they are not provided using the previous
818 two mechanisms.
819 </para></listitem>
820 <listitem><para>
821 The previously deprecated "apps-console-core"
822 <filename>IMAGE_FEATURES</filename> item is no longer
823 supported.
824 Add "splash" to <filename>IMAGE_FEATURES</filename> if you
825 wish to have the splash screen enabled, since this is
826 all that apps-console-core was doing.</para></listitem>
827 </itemizedlist>
828 </para>
829 </section>
830
831 <section id='migration-1.5-run'>
832 <title><filename>/run</filename></title>
833
834 <para>
835 The <filename>/run</filename> directory from the Filesystem
836 Hierarchy Standard 3.0 has been introduced.
837 You can find some of the implications for this change
838 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
839 The change also means that recipes that install files to
840 <filename>/var/run</filename> must be changed.
841 You can find a guide on how to make these changes
842 <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
843 </para>
844 </section>
845
846 <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
847 <title>Removal of Package Manager Database Within Image Recipes</title>
848
849 <para>
850 The image <filename>core-image-minimal</filename> no longer adds
851 <filename>remove_packaging_data_files</filename> to
852 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
853 This addition is now handled automatically when "package-management"
854 is not in
855 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
856 If you have custom image recipes that make this addition,
857 you should remove the lines, as they are not needed and might
858 interfere with correct operation of postinstall scripts.
859 </para>
860 </section>
861
862 <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
863 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
864
865 <para>
866 The <filename>do_rootfs</filename> and other related image
867 construction tasks are no longer marked as "nostamp".
868 Consequently, they will only be re-executed when their inputs have
869 changed.
870 Previous versions of the OpenEmbedded build system always rebuilt
871 the image when requested rather when necessary.
872 </para>
873 </section>
874
875 <section id='migration-1.5-task-recipes'>
876 <title>Task Recipes</title>
877
878 <para>
879 The previously deprecated <filename>task.bbclass</filename> has
880 now been dropped.
881 For recipes that previously inherited from this task, you should
882 rename them from <filename>task-*</filename> to
883 <filename>packagegroup-*</filename> and inherit packagegroup
884 instead.
885 </para>
886
887 <para>
888 For more information, see the
889 "<link linkend='ref-classes-packagegroup'>Package Groups - <filename>packagegroup.bbclass</filename></link>"
890 section.
891 </para>
892 </section>
893
894 <section id='migration-1.5-busybox'>
895 <title>BusyBox</title>
896
897 <para>
898 By default, we now split BusyBox into two binaries:
899 one that is suid root for those components that need it, and
900 another for the rest of the components.
901 Splitting BusyBox allows for optimization that eliminates the
902 <filename>tinylogin</filename> recipe as recommended by upstream.
903 You can disable this split by setting
904 <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
905 to "0".
906 </para>
907 </section>
908
909 <section id='migration-1.5-automated-image-testing'>
910 <title>Automated Image Testing</title>
911
912 <para>
913 A new automated image testing framework has been added
914 through the
915 <link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link>
916 class.
917 This framework replaces the older
918 <filename>imagetest-qemu</filename> framework.
919 </para>
920
921 <para>
922 You can learn more about performing automated image tests in the
923 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
924 section.
925 </para>
926 </section>
927
928 <section id='migration-1.5-build-history'>
929 <title>Build History</title>
930
931 <para>
932 Following are changes to Build History:
933 <itemizedlist>
934 <listitem><para>
935 Installed package sizes:
936 <filename>installed-package-sizes.txt</filename> for an
937 image now records the size of the files installed by each
938 package instead of the size of each compressed package
939 archive file.</para></listitem>
940 <listitem><para>
941 The dependency graphs (<filename>depends*.dot</filename>)
942 now use the actual package names instead of replacing
943 dashes, dots and plus signs with underscores.
944 </para></listitem>
945 <listitem><para>
946 The <filename>buildhistory-diff</filename> and
947 <filename>buildhistory-collect-srcrevs</filename>
948 utilities have improved command-line handling.
949 Use the <filename>&dash;&dash;help</filename> option for
950 each utility for more information on the new syntax.
951 </para></listitem>
952 </itemizedlist>
953 For more information on Build History, see the
954 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
955 section.
956 </para>
957 </section>
958
959 <section id='migration-1.5-udev'>
960 <title><filename>udev</filename></title>
961
962 <para>
963 Following are changes to <filename>udev</filename>:
964 <itemizedlist>
965 <listitem><para>
966 <filename>udev</filename> no longer brings in
967 <filename>udev-extraconf</filename> automatically
968 through
969 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
970 since this was originally intended to be optional.
971 If you need the extra rules, then add
972 <filename>udev-extraconf</filename> to your image.
973 </para></listitem>
974 <listitem><para>
975 <filename>udev</filename> no longer brings in
976 <filename>pciutils-ids</filename> or
977 <filename>usbutils-ids</filename> through
978 <filename>RRECOMMENDS</filename>.
979 These are not needed by <filename>udev</filename> itself
980 and removing them saves around 350KB.
981 </para></listitem>
982 </itemizedlist>
983 </para>
984 </section>
985
986 <section id='removed-renamed-recipes'>
987 <title>Removed and Renamed Recipes</title>
988
989 <itemizedlist>
990 <listitem><para>
991 The <filename>linux-yocto</filename> 3.2 kernel has been
992 removed.</para></listitem>
993 <listitem><para>
994 <filename>libtool-nativesdk</filename> has been renamed to
995 <filename>nativesdk-libtool</filename>.</para></listitem>
996 <listitem><para>
997 <filename>tinylogin</filename> has been removed.
998 It has been replaced by a suid portion of Busybox.
999 See the
1000 "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
1001 for more information.</para></listitem>
1002 <listitem><para>
1003 <filename>external-python-tarball</filename> has been renamed
1004 to <filename>buildtools-tarball</filename>.
1005 </para></listitem>
1006 <listitem><para>
1007 <filename>web-webkit</filename> has been removed.
1008 It has been functionally replaced by
1009 <filename>midori</filename>.</para></listitem>
1010 <listitem><para>
1011 <filename>imake</filename> has been removed.
1012 It is no longer needed by any other recipe.
1013 </para></listitem>
1014 <listitem><para>
1015 <filename>transfig-native</filename> has been removed.
1016 It is no longer needed by any other recipe.
1017 </para></listitem>
1018 <listitem><para>
1019 <filename>anjuta-remote-run</filename> has been removed.
1020 Anjuta IDE integration has not been officially supported for
1021 several releases.</para></listitem>
1022 </itemizedlist>
1023 </section>
1024
1025 <section id='migration-1.5-other-changes'>
1026 <title>Other Changes</title>
1027
1028 <para>
1029 Following is a list of short entries describing other changes:
1030 <itemizedlist>
1031 <listitem><para>
1032 <filename>run-postinsts</filename>: Make this generic.
1033 </para></listitem>
1034 <listitem><para>
1035 <filename>base-files</filename>: Remove the unnecessary
1036 <filename>/media/xxx</filename> directories.
1037 </para></listitem>
1038 <listitem><para>
1039 <filename>alsa-state</filename>: Provide an empty
1040 <filename>asound.conf</filename> by default.
1041 </para></listitem>
1042 <listitem><para>
1043 <filename>classes/image</filename>: Ensure
1044 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1045 supports pre-renamed package names.</para></listitem>
1046 <listitem><para>
1047 <filename>classes/rootfs_rpm</filename>: Implement
1048 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1049 for RPM.</para></listitem>
1050 <listitem><para>
1051 <filename>systemd</filename>: Remove
1052 <filename>systemd_unitdir</filename> if
1053 <filename>systemd</filename> is not in
1054 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1055 </para></listitem>
1056 <listitem><para>
1057 <filename>systemd</filename>: Remove
1058 <filename>init.d</filename> dir if
1059 <filename>systemd</filename> unit file is present and
1060 <filename>sysvinit</filename> is not a distro feature.
1061 </para></listitem>
1062 <listitem><para>
1063 <filename>libpam</filename>: Deny all services for the
1064 <filename>OTHER</filename> entries.
1065 </para></listitem>
1066 <listitem><para>
1067 <filename>image.bbclass</filename>: Move
1068 <filename>runtime_mapping_rename</filename> to avoid
1069 conflict with <filename>multilib</filename>.
1070 See
1071 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
1072 in Bugzilla for more information.
1073 </para></listitem>
1074 <listitem><para>
1075 <filename>linux-dtb</filename>: Use kernel build system
1076 to generate the <filename>dtb</filename> files.
1077 </para></listitem>
1078 <listitem><para>
1079 <filename>kern-tools</filename>: Switch from guilt to
1080 new <filename>kgit-s2q</filename> tool.
1081 </para></listitem>
1082 </itemizedlist>
1083 </para>
1084 </section>
1085</section>
1086</chapter>
1087<!--
1088vim: expandtab tw=80 ts=4
1089-->
diff --git a/documentation/ref-manual/ref-bitbake.xml b/documentation/ref-manual/ref-bitbake.xml
new file mode 100644
index 0000000000..b587d46caa
--- /dev/null
+++ b/documentation/ref-manual/ref-bitbake.xml
@@ -0,0 +1,432 @@
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='ref-bitbake'>
6
7 <title>BitBake</title>
8
9 <para>
10 BitBake is a program written in Python that interprets the
11 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> used by
12 the OpenEmbedded build system.
13 At some point, developers wonder what actually happens when you enter:
14 <literallayout class='monospaced'>
15 $ bitbake core-image-sato
16 </literallayout>
17 </para>
18
19 <para>
20 This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
21 </para>
22
23 <note>
24 BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships.
25 As such, it has no real knowledge of what the tasks being executed actually do.
26 BitBake just considers a list of tasks with dependencies and handles
27 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
28 consisting of variables in a certain format that get passed to the tasks.
29 </note>
30
31 <section id='ref-bitbake-parsing'>
32 <title>Parsing</title>
33
34 <para>
35 BitBake parses configuration files, classes, and <filename>.bb</filename> files.
36 </para>
37
38 <para>
39 The first thing BitBake does is look for the <filename>bitbake.conf</filename> file.
40 This file resides in the
41 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
42 within the <filename>meta/conf/</filename> directory.
43 BitBake finds it by examining its
44 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment
45 variable and looking for the <filename>meta/conf/</filename>
46 directory.
47 </para>
48
49 <para>
50 The <filename>bitbake.conf</filename> file lists other configuration
51 files to include from a <filename>conf/</filename>
52 directory below the directories listed in <filename>BBPATH</filename>.
53 In general, the most important configuration file from a user's perspective
54 is <filename>local.conf</filename>, which contains a user's customized
55 settings for the OpenEmbedded build environment.
56 Other notable configuration files are the distribution
57 configuration file (set by the
58 <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable)
59 and the machine configuration file
60 (set by the
61 <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable).
62 The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment
63 variables are both usually set in
64 the <filename>local.conf</filename> file.
65 Valid distribution
66 configuration files are available in the <filename>meta/conf/distro/</filename> directory
67 and valid machine configuration
68 files in the <filename>meta/conf/machine/</filename> directory.
69 Within the <filename>meta/conf/machine/include/</filename>
70 directory are various <filename>tune-*.inc</filename> configuration files that provide common
71 "tuning" settings specific to and shared between particular architectures and machines.
72 </para>
73
74 <para>
75 After the parsing of the configuration files, some standard classes are included.
76 The <filename>base.bbclass</filename> file is always included.
77 Other classes that are specified in the configuration using the
78 <filename><link linkend='var-INHERIT'>INHERIT</link></filename>
79 variable are also included.
80 Class files are searched for in a <filename>classes</filename> subdirectory
81 under the paths in <filename>BBPATH</filename> in the same way as
82 configuration files.
83 </para>
84
85 <para>
86 After classes are included, the variable
87 <filename><link linkend='var-BBFILES'>BBFILES</link></filename>
88 is set, usually in
89 <filename>local.conf</filename>, and defines the list of places to search for
90 <filename>.bb</filename> files.
91 By default, the <filename>BBFILES</filename> variable specifies the
92 <filename>meta/recipes-*/</filename> directory within Poky.
93 Adding extra content to <filename>BBFILES</filename> is best achieved through the use of
94 BitBake layers as described in the
95 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
96 Creating Layers</ulink>" section of the Yocto Project Development Manual.
97 </para>
98
99 <para>
100 BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and
101 stores the values of various variables.
102 In summary, for each <filename>.bb</filename>
103 file the configuration plus the base class of variables are set, followed
104 by the data in the <filename>.bb</filename> file
105 itself, followed by any inherit commands that
106 <filename>.bb</filename> file might contain.
107 </para>
108
109 <para>
110 Because parsing <filename>.bb</filename> files is a time
111 consuming process, a cache is kept to speed up subsequent parsing.
112 This cache is invalid if the timestamp of the <filename>.bb</filename>
113 file itself changes, or if the timestamps of any of the include,
114 configuration files or class files on which the
115 <filename>.bb</filename> file depends change.
116 </para>
117 </section>
118
119 <section id='ref-bitbake-providers'>
120 <title>Preferences and Providers</title>
121
122 <para>
123 Once all the <filename>.bb</filename> files have been
124 parsed, BitBake starts to build the target (<filename>core-image-sato</filename>
125 in the previous section's example) and looks for providers of that target.
126 Once a provider is selected, BitBake resolves all the dependencies for
127 the target.
128 In the case of <filename>core-image-sato</filename>, it would lead to
129 <filename>packagegroup-core-x11-sato</filename>,
130 which in turn leads to recipes like <filename>matchbox-terminal</filename>,
131 <filename>pcmanfm</filename> and <filename>gthumb</filename>.
132 These recipes in turn depend on <filename>eglibc</filename> and the toolchain.
133 </para>
134
135 <para>
136 Sometimes a target might have multiple providers.
137 A common example is "virtual/kernel", which is provided by each kernel package.
138 Each machine often selects the best kernel provider by using a line similar to the
139 following in the machine configuration file:
140 </para>
141
142 <literallayout class='monospaced'>
143 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
144 </literallayout>
145
146 <para>
147 The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename>
148 is the provider with the same name as the target.
149 </para>
150
151 <para>
152 Understanding how providers are chosen is made complicated by the fact
153 that multiple versions might exist.
154 BitBake defaults to the highest version of a provider.
155 Version comparisons are made using the same method as Debian.
156 You can use the
157 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
158 variable to specify a particular version (usually in the distro configuration).
159 You can influence the order by using the
160 <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename>
161 variable.
162 By default, files have a preference of "0".
163 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
164 package unlikely to be used unless it is explicitly referenced.
165 Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used.
166 <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
167 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package
168 versions until they have undergone sufficient testing to be considered stable.
169 </para>
170
171 <para>
172 In summary, BitBake has created a list of providers, which is prioritized, for each target.
173 </para>
174 </section>
175
176 <section id='ref-bitbake-dependencies'>
177 <title>Dependencies</title>
178
179 <para>
180 Each target BitBake builds consists of multiple tasks such as
181 <filename>fetch</filename>, <filename>unpack</filename>,
182 <filename>patch</filename>, <filename>configure</filename>,
183 and <filename>compile</filename>.
184 For best performance on multi-core systems, BitBake considers each task as an independent
185 entity with its own set of dependencies.
186 </para>
187
188 <para>
189 Dependencies are defined through several variables.
190 You can find information about variables BitBake uses in the BitBake documentation,
191 which is found in the <filename>bitbake/doc/manual</filename> directory within the
192 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
193 At a basic level, it is sufficient to know that BitBake uses the
194 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and
195 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when
196 calculating dependencies.
197 </para>
198 </section>
199
200 <section id='ref-bitbake-tasklist'>
201 <title>The Task List</title>
202
203 <para>
204 Based on the generated list of providers and the dependency information,
205 BitBake can now calculate exactly what tasks it needs to run and in what
206 order it needs to run them.
207 The build now starts with BitBake forking off threads up to the limit set in the
208 <filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></filename> variable.
209 BitBake continues to fork threads as long as there are tasks ready to run,
210 those tasks have all their dependencies met, and the thread threshold has not been
211 exceeded.
212 </para>
213
214 <para>
215 It is worth noting that you can greatly speed up the build time by properly setting
216 the <filename>BB_NUMBER_THREADS</filename> variable.
217 See the
218 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
219 section in the Yocto Project Quick Start for more information.
220 </para>
221
222 <para>
223 As each task completes, a timestamp is written to the directory specified by the
224 <filename><link linkend='var-STAMP'>STAMP</link></filename> variable.
225 On subsequent runs, BitBake looks within the <filename>/build/tmp/stamps</filename>
226 directory and does not rerun
227 tasks that are already completed unless a timestamp is found to be invalid.
228 Currently, invalid timestamps are only considered on a per
229 <filename>.bb</filename> file basis.
230 So, for example, if the configure stamp has a timestamp greater than the
231 compile timestamp for a given target, then the compile task would rerun.
232 Running the compile task again, however, has no effect on other providers
233 that depend on that target.
234 This behavior could change or become configurable in future versions of BitBake.
235 </para>
236
237 <note>
238 Some tasks are marked as "nostamp" tasks.
239 No timestamp file is created when these tasks are run.
240 Consequently, "nostamp" tasks are always rerun.
241 </note>
242 </section>
243
244 <section id='ref-bitbake-runtask'>
245 <title>Running a Task</title>
246
247 <para>
248 Tasks can either be a shell task or a Python task.
249 For shell tasks, BitBake writes a shell script to
250 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script.
251 The generated shell script contains all the exported variables, and the shell functions
252 with all variables expanded.
253 Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
254 Looking at the expanded shell functions in the run file and the output in the log files
255 is a useful debugging technique.
256 </para>
257
258 <para>
259 For Python tasks, BitBake executes the task internally and logs information to the
260 controlling terminal.
261 Future versions of BitBake will write the functions to files similar to the way
262 shell tasks are handled.
263 Logging will be handled in a way similar to shell tasks as well.
264 </para>
265
266 <para>
267 Once all the tasks have been completed BitBake exits.
268 </para>
269
270 <para>
271 When running a task, BitBake tightly controls the execution environment
272 of the build tasks to make sure unwanted contamination from the build machine
273 cannot influence the build.
274 Consequently, if you do want something to get passed into the build
275 task's environment, you must take a few steps:
276 <orderedlist>
277 <listitem><para>Tell BitBake to load what you want from the environment
278 into the data store.
279 You can do so through the <filename>BB_ENV_EXTRAWHITE</filename>
280 variable.
281 For example, assume you want to prevent the build system from
282 accessing your <filename>$HOME/.ccache</filename> directory.
283 The following command tells BitBake to load
284 <filename>CCACHE_DIR</filename> from the environment into the data
285 store:
286 <literallayout class='monospaced'>
287 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
288 </literallayout></para></listitem>
289 <listitem><para>Tell BitBake to export what you have loaded into the
290 environment store to the task environment of every running task.
291 Loading something from the environment into the data store
292 (previous step) only makes it available in the datastore.
293 To export it to the task environment of every running task,
294 use a command similar to the following in your
295 <filename>local.conf</filename> or distro configuration file:
296 <literallayout class='monospaced'>
297 export CCACHE_DIR
298 </literallayout></para></listitem>
299 </orderedlist>
300 </para>
301
302 <note>
303 A side effect of the previous steps is that BitBake records the variable
304 as a dependency of the build process in things like the shared state
305 checksums.
306 If doing so results in unnecessary rebuilds of tasks, you can whitelist the
307 variable so that the shared state code ignores the dependency when it creates
308 checksums.
309 For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename>
310 example in the "<link linkend='checksums'>Checksums (Signatures)</link>" section.
311 </note>
312 </section>
313
314 <section id='ref-bitbake-commandline'>
315 <title>BitBake Command Line</title>
316
317 <para>
318 Following is the BitBake help output:
319 </para>
320
321 <screen>
322$ bitbake --help
323Usage: bitbake [options] [recipename/target ...]
324
325 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
326 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
327 will provide the layer, BBFILES and other configuration information.
328
329Options:
330 --version show program's version number and exit
331 -h, --help show this help message and exit
332 -b BUILDFILE, --buildfile=BUILDFILE
333 Execute tasks from a specific .bb recipe directly.
334 WARNING: Does not handle any dependencies from other
335 recipes.
336 -k, --continue Continue as much as possible after an error. While the
337 target that failed and anything depending on it cannot
338 be built, as much as possible will be built before
339 stopping.
340 -a, --tryaltconfigs Continue with builds by trying to use alternative
341 providers where possible.
342 -f, --force Force the specified targets/task to run (invalidating
343 any existing stamp file).
344 -c CMD, --cmd=CMD Specify the task to execute. The exact options
345 available depend on the metadata. Some examples might
346 be 'compile' or 'populate_sysroot' or 'listtasks' may
347 give a list of the tasks available.
348 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
349 Invalidate the stamp for the specified task such as
350 'compile' and then run the default task for the
351 specified target(s).
352 -r PREFILE, --read=PREFILE
353 Read the specified file before bitbake.conf.
354 -R POSTFILE, --postread=POSTFILE
355 Read the specified file after bitbake.conf.
356 -v, --verbose Output more log message data to the terminal.
357 -D, --debug Increase the debug level. You can specify this more
358 than once.
359 -n, --dry-run Don't execute, just go through the motions.
360 -S, --dump-signatures
361 Don't execute, just dump out the signature
362 construction information.
363 -p, --parse-only Quit after parsing the BB recipes.
364 -s, --show-versions Show current and preferred versions of all recipes.
365 -e, --environment Show the global or per-package environment complete
366 with information about where variables were
367 set/changed.
368 -g, --graphviz Save dependency tree information for the specified
369 targets in the dot syntax.
370 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
371 Assume these dependencies don't exist and are already
372 provided (equivalent to ASSUME_PROVIDED). Useful to
373 make dependency graphs more appealing
374 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
375 Show debug logging for the specified logging domains
376 -P, --profile Profile the command and save reports.
377 -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp).
378 -t SERVERTYPE, --servertype=SERVERTYPE
379 Choose which server to use, process or xmlrpc.
380 --revisions-changed Set the exit code depending on whether upstream
381 floating revisions have changed or not.
382 --server-only Run bitbake without a UI, only starting a server
383 (cooker) process.
384 -B BIND, --bind=BIND The name/address for the bitbake server to bind to.
385 --no-setscene Do not run any setscene tasks. sstate will be ignored
386 and everything needed, built.
387 --remote-server=REMOTE_SERVER
388 Connect to the specified server.
389 -m, --kill-server Terminate the remote server.
390 --observe-only Connect to a server as an observing-only client.
391 </screen>
392 </section>
393
394 <section id='ref-bitbake-fetchers'>
395 <title>Fetchers</title>
396
397 <para>
398 BitBake also contains a set of "fetcher" modules that allow
399 retrieval of source code from various types of sources.
400 For example, BitBake can get source code from a disk with the metadata, from websites,
401 from remote shell accounts, or from Source Code Management (SCM) systems
402 like <filename>cvs/subversion/git</filename>.
403 </para>
404
405 <para>
406 Fetchers are usually triggered by entries in
407 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
408 You can find information about the options and formats of entries for specific
409 fetchers in the BitBake manual located in the
410 <filename>bitbake/doc/manual</filename> directory of the
411 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
412 </para>
413
414 <para>
415 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
416 "auto-update" when the upstream SCM changes version.
417 Since this ability requires certain functionality from the SCM, not all
418 systems support it.
419 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
420 This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
421 variable.
422 See the
423 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section
424 in the Yocto Project Development Manual for more information.
425 </para>
426
427 </section>
428
429</chapter>
430<!--
431vim: expandtab tw=80 ts=4 spell spelllang=en_gb
432-->
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
new file mode 100644
index 0000000000..27edfde33d
--- /dev/null
+++ b/documentation/ref-manual/ref-classes.xml
@@ -0,0 +1,1104 @@
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='ref-classes'>
6<title>Classes</title>
7
8<para>
9 Class files are used to abstract common functionality and share it amongst multiple
10 <filename>.bb</filename> files.
11 Any <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> usually
12 found in a <filename>.bb</filename> file can also be placed in a class
13 file.
14 Class files are identified by the extension <filename>.bbclass</filename> and are usually placed
15 in a <filename>classes/</filename> directory beneath the
16 <filename>meta*/</filename> directory found in the
17 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
18 Class files can also be pointed to by
19 <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link>
20 (e.g. <filename>build/</filename>) in the same way as
21 <filename>.conf</filename> files in the <filename>conf</filename> directory.
22 Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
23 using the same method by which <filename>.conf</filename> files are searched.
24</para>
25
26<para>
27 In most cases inheriting the class is enough to enable its features, although
28 for some classes you might need to set variables or override some of the
29 default behavior.
30</para>
31
32<para>
33 This chapter discusses only the most useful and important classes.
34 Other classes do exist within the <filename>meta/classes</filename>
35 directory in the
36 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
37 You can reference the <filename>.bbclass</filename> files directly
38 for more information.
39</para>
40
41<section id='ref-classes-base'>
42 <title>The base Class - <filename>base.bbclass</filename></title>
43
44 <para>
45 The base class is special in that every <filename>.bb</filename>
46 file inherits it automatically.
47 This class contains definitions for standard basic
48 tasks such as fetching, unpacking, configuring (empty by default), compiling
49 (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging
50 (empty by default).
51 These classes are often overridden or extended by other classes
52 such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>.
53 The class also contains some commonly used functions such as <filename>oe_runmake</filename>.
54 </para>
55</section>
56
57<section id='ref-classes-autotools'>
58 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
59
60 <para>
61 Autotools (<filename>autoconf</filename>, <filename>automake</filename>,
62 and <filename>libtool</filename>) bring standardization.
63 This class defines a set of tasks (configure, compile etc.) that
64 work for all Autotooled packages.
65 It should usually be enough to define a few standard variables
66 and then simply <filename>inherit autotools</filename>.
67 This class can also work with software that emulates Autotools.
68 For more information, see the
69 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>"
70 section in the Yocto Project Development Manual.
71 </para>
72
73 <para>
74 It's useful to have some idea of how the tasks defined by this class work
75 and what they do behind the scenes.
76 <itemizedlist>
77 <listitem><para><filename>do_configure</filename> &dash; Regenerates the
78 configure script (using <filename>autoreconf</filename>) and then launches it
79 with a standard set of arguments used during cross-compilation.
80 You can pass additional parameters to <filename>configure</filename> through the
81 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
82 </para></listitem>
83 <listitem><para><filename>do_compile</filename> &dash; Runs <filename>make</filename> with
84 arguments that specify the compiler and linker.
85 You can pass additional arguments through
86 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
87 </para></listitem>
88 <listitem><para><filename>do_install</filename> &dash; Runs <filename>make install</filename>
89 and passes in
90 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
91 as <filename>DESTDIR</filename>.
92 </para></listitem>
93 </itemizedlist>
94 </para>
95</section>
96
97<section id='ref-classes-update-alternatives'>
98 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
99
100 <para>
101 This class helps the alternatives system when multiple sources provide
102 the same command.
103 This situation occurs when several programs that have the same or
104 similar function are installed with the same name.
105 For example, the <filename>ar</filename> command is available from the
106 <filename>busybox</filename>, <filename>binutils</filename> and
107 <filename>elfutils</filename> packages.
108 The <filename>update-alternatives.bbclass</filename> class handles
109 renaming the binaries so that multiple packages can be installed
110 without conflicts.
111 The <filename>ar</filename> command still works regardless of which
112 packages are installed or subsequently removed.
113 The class renames the conflicting binary in each package and symlinks
114 the highest priority binary during installation or removal of packages.
115 </para>
116
117 <para>
118 To use this class, you need to define a number of variables:
119 <itemizedlist>
120 <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
121 </para></listitem>
122 <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
123 </para></listitem>
124 <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
125 </para></listitem>
126 <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
127 </para></listitem>
128 </itemizedlist>
129 These variables list alternative commands needed by a package,
130 provide pathnames for links, default links for targets, and
131 so forth.
132 For details on how to use this class, see the comments in the
133 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>.
134 </para>
135
136 <note>
137 You can use the <filename>update-alternatives</filename> command
138 directly in your recipes.
139 However, this class simplifies things in most cases.
140 </note>
141</section>
142
143<section id='ref-classes-update-rc.d'>
144 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
145
146 <para>
147 This class uses <filename>update-rc.d</filename> to safely install an
148 initialization script on behalf of the package.
149 The OpenEmbedded build system takes care of details such as making sure the script is stopped before
150 a package is removed and started when the package is installed.
151 Three variables control this class:
152 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
153 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
154 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
155 See the variable links for details.
156 </para>
157</section>
158
159<section id='ref-classes-binconfig'>
160 <title><filename>binconfig.bbclass</filename></title>
161
162 <para>
163 This class helps to correct paths in shell scripts.
164 </para>
165
166 <para>
167 Before <filename>pkg-config</filename> had become widespread, libraries
168 shipped shell scripts to give information about the libraries and
169 include paths needed to build software (usually named
170 <filename>LIBNAME-config</filename>).
171 This class assists any recipe using such scripts.
172 </para>
173
174 <para>
175 During staging, the OpenEmbedded build system installs such scripts
176 into the <filename>sysroots/</filename> directory.
177 Inheriting this class results in all paths in these scripts being
178 changed to point into the <filename>sysroots/</filename> directory so
179 that all builds that use the script use the correct directories
180 for the cross compiling layout.
181 See the
182 <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link>
183 variable for more information.
184 </para>
185</section>
186
187<section id='ref-classes-debian'>
188 <title>Debian Renaming - <filename>debian.bbclass</filename></title>
189
190 <para>
191 This class renames packages so that they follow the Debian naming
192 policy (i.e. <filename>eglibc</filename> becomes <filename>libc6</filename>
193 and <filename>eglibc-devel</filename> becomes <filename>libc6-dev</filename>.)
194 </para>
195</section>
196
197<section id='ref-classes-pkgconfig'>
198 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
199
200 <para>
201 <filename>pkg-config</filename> provides a standard way to get
202 header and library information.
203 This class aims to smooth integration of
204 <filename>pkg-config</filename> into libraries that use it.
205 </para>
206
207 <para>
208 During staging, BitBake installs <filename>pkg-config</filename> data into the
209 <filename>sysroots/</filename> directory.
210 By making use of sysroot functionality within <filename>pkg-config</filename>,
211 this class no longer has to manipulate the files.
212 </para>
213</section>
214
215<section id='ref-classes-archiver'>
216 <title>Archiving Sources - <filename>archive*.bbclass</filename></title>
217
218 <para>
219 Many software licenses require that source code and other materials be
220 released with the binaries.
221 To help with that task, the following classes are provided:
222 <itemizedlist>
223 <listitem><filename>archive-original-sources.bbclass</filename></listitem>
224 <listitem><filename>archive-patched-sources.bbclass</filename></listitem>
225 <listitem><filename>archive-configured-sources.bbclass</filename></listitem>
226 <listitem><filename>archiver.bbclass</filename></listitem>
227 </itemizedlist>
228 </para>
229
230 <para>
231 For more details on the source archiver, see the
232 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
233 section in the Yocto Project Development Manual.
234 </para>
235</section>
236
237<section id='ref-classes-perl'>
238 <title>Perl Modules - <filename>cpan.bbclass</filename></title>
239
240 <para>
241 Recipes for Perl modules are simple.
242 These recipes usually only need to point to the source's archive and then inherit the
243 proper <filename>.bbclass</filename> file.
244 Building is split into two methods depending on which method the module authors used.
245 <itemizedlist>
246 <listitem><para>Modules that use old
247 <filename>Makefile.PL</filename>-based build system require
248 <filename>cpan.bbclass</filename> in their recipes.
249 </para></listitem>
250 <listitem><para>Modules that use
251 <filename>Build.PL</filename>-based build system require
252 using <filename>cpan_build.bbclass</filename> in their recipes.
253 </para></listitem>
254 </itemizedlist>
255 </para>
256</section>
257
258<section id='ref-classes-distutils'>
259 <title>Python Extensions - <filename>distutils.bbclass</filename></title>
260
261 <para>
262 Recipes for Python extensions are simple.
263 These recipes usually only need to point to the source's archive and then inherit
264 the proper <filename>.bbclass</filename> file.
265 Building is split into two methods depending on which method the module authors used.
266 <itemizedlist>
267 <listitem><para>Extensions that use an Autotools-based build system
268 require Autotools and
269 <filename>distutils</filename>-based
270 <filename>.bbclasse</filename> files in their recipes.
271 </para></listitem>
272 <listitem><para>Extensions that use
273 <filename>distutils</filename>-based build systems require
274 <filename>distutils.bbclass</filename> in their recipes.
275 </para></listitem>
276 </itemizedlist>
277 </para>
278</section>
279
280<section id='ref-classes-devshell'>
281 <title>Developer Shell - <filename>devshell.bbclass</filename></title>
282
283 <para>
284 This class adds the <filename>devshell</filename> task.
285 Distribution policy dictates whether to include this class.
286 See the
287 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
288 in the Yocto Project Development Manual for more information about using <filename>devshell</filename>.
289 </para>
290</section>
291
292<section id='ref-classes-packagegroup'>
293 <title>Package Groups - <filename>packagegroup.bbclass</filename></title>
294
295 <para>
296 This class sets default values appropriate for package group recipes (e.g.
297 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
298 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
299 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
300 and so forth).
301 It is highly recommended that all package group recipes inherit this class.
302 </para>
303 <para>
304 For information on how to use this class, see the
305 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
306 section in the Yocto Project Development Manual.
307 </para>
308 <para>
309 Previously, this class was named <filename>task.bbclass</filename>.
310 </para>
311</section>
312
313
314<section id='ref-classes-package'>
315 <title>Packaging - <filename>package*.bbclass</filename></title>
316
317 <para>
318 The packaging classes add support for generating packages from a build's
319 output.
320 The core generic functionality is in <filename>package.bbclass</filename>.
321 The code specific to particular package types is contained in various sub-classes such as
322 <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
323 and <filename>package_rpm.bbclass</filename>.
324 Most users will want one or more of these classes.
325 </para>
326
327 <para>
328 You can control the list of resulting package formats by using the
329 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
330 variable defined in the <filename>local.conf</filename> configuration file,
331 which is located in the <filename>conf</filename> folder of the
332 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
333 When defining the variable, you can specify one or more package types.
334 Since images are generated from packages, a packaging class is
335 needed to enable image generation.
336 The first class listed in this variable is used for image generation.
337 </para>
338
339 <para>
340 If you take the optional step to set up a repository (package feed)
341 on the development host that can be used by Smart, you can
342 install packages from the feed while you are running the image
343 on the target (i.e. runtime installation of packages).
344 For more information, see the
345 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
346 section in the Yocto Project Development Manual.
347 </para>
348
349 <para>
350 The package class you choose can affect build-time performance and has space
351 ramifications.
352 In general, building a package with IPK takes about thirty percent less
353 time as compared to using RPM to build the same or similar package.
354 This comparison takes into account a complete build of the package with
355 all dependencies previously built.
356 The reason for this discrepancy is because the RPM package manager
357 creates and processes more
358 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the
359 IPK package manager.
360 Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
361 to "package_ipk" if you are building smaller systems.
362 </para>
363
364 <para>
365 Before making your decision on package manager, however, you should
366 consider some further things about using RPM:
367 <itemizedlist>
368 <listitem><para>
369 RPM starts to provide more abilities than IPK due to
370 the fact that it processes more metadata.
371 For example, this information includes individual file types,
372 file checksum generation and evaluation on install, sparse file
373 support, conflict detection and resolution for Multilib systems,
374 ACID style upgrade, and repackaging abilities for rollbacks.
375 </para></listitem>
376 <listitem><para>
377 For smaller systems, the extra space used for the Berkley
378 Database and the amount of metadata when using RPM can affect
379 your ability to perform on-device upgrades.
380 </para></listitem>
381 </itemizedlist>
382 </para>
383
384 <para>
385 You can find additional information on the effects of the package
386 class at these two Yocto Project mailing list links:
387 <itemizedlist>
388 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
389 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
390 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
391 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
392 </itemizedlist>
393 </para>
394</section>
395
396<section id='ref-classes-kernel'>
397 <title>Building Kernels - <filename>kernel.bbclass</filename></title>
398
399 <para>
400 This class handles building Linux kernels.
401 The class contains code to build all kernel trees.
402 All needed headers are staged into the
403 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
404 directory to allow out-of-tree module builds using <filename>module.bbclass</filename>.
405 </para>
406
407 <para>
408 This means that each built kernel module is packaged separately and inter-module
409 dependencies are created by parsing the <filename>modinfo</filename> output.
410 If all modules are required, then installing the <filename>kernel-modules</filename>
411 package installs all packages with modules and various other kernel packages
412 such as <filename>kernel-vmlinux</filename>.
413 </para>
414
415 <para>
416 Various other classes are used by the kernel and module classes internally including
417 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
418 <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>.
419 </para>
420</section>
421
422<section id='ref-classes-image'>
423 <title>Creating Images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
424
425 <para>
426 These classes add support for creating images in several formats.
427 First, the root filesystem is created from packages using
428 one of the <filename>rootfs_*.bbclass</filename>
429 files (depending on the package format used) and then the image is created.
430 <itemizedlist>
431 <listitem><para>The
432 <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
433 variable controls the types of images to generate.
434 </para></listitem>
435 <listitem><para>The
436 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
437 variable controls the list of packages to install into the
438 image.</para></listitem>
439 </itemizedlist>
440 </para>
441</section>
442
443<section id='ref-classes-sanity'>
444 <title>Host System Sanity Checks - <filename>sanity.bbclass</filename></title>
445
446 <para>
447 This class checks to see if prerequisite software is present on the host system
448 so that users can be notified of potential problems that might affect their build.
449 The class also performs basic user configuration checks from
450 the <filename>local.conf</filename> configuration file to
451 prevent common mistakes that cause build failures.
452 Distribution policy usually determines whether to include this class.
453 </para>
454</section>
455
456<section id='ref-classes-insane'>
457<title><filename>insane.bbclass</filename></title>
458
459 <para>
460 This class adds a step to the package generation process so that
461 output quality assurance checks are generated by the OpenEmbedded
462 build system.
463 A range of checks are performed that check the build's output
464 for common problems that show up during runtime.
465 Distribution policy usually dictates whether to include this class.
466 </para>
467
468 <para>
469 You can configure the sanity checks so that specific test failures
470 either raise a warning or an error message.
471 Typically, failures for new tests generate a warning.
472 Subsequent failures for the same test would then generate an error
473 message once the metadata is in a known and good condition.
474 </para>
475
476 <para>
477 Use the
478 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
479 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
480 variables to control the behavior of
481 these checks at the global level (i.e. in your custom distro
482 configuration).
483 However, to skip one or more checks in recipes, you should use
484 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
485 For example, to skip the check for symbolic link
486 <filename>.so</filename> files in the main package of a recipe,
487 add the following to the recipe.
488 You need to realize that the package name override, in this example
489 <filename>${PN}</filename>, must be used:
490 <literallayout class='monospaced'>
491 INSANE_SKIP_${PN} += "dev-so"
492 </literallayout>
493 Please keep in mind that the QA checks exist in order to detect real
494 or potential problems in the packaged output.
495 So exercise caution when disabling these checks.
496 </para>
497
498 <para>
499 The following list shows the tests you can list with the
500 <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
501 variables:
502 <itemizedlist>
503 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
504 Ensures that the binaries were linked with the
505 <filename>LDFLAGS</filename> options provided by the build system.
506 If this test fails, check that the <filename>LDFLAGS</filename> variable
507 is being passed to the linker command.</para></listitem>
508 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
509 Checks for dynamic library load paths (rpaths) in the binaries that
510 by default on a standard system are searched by the linker (e.g.
511 <filename>/lib</filename> and <filename>/usr/lib</filename>).
512 While these paths will not cause any breakage, they do waste space and
513 are unnecessary.</para></listitem>
514 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
515 Checks for rpaths in the binaries that contain build system paths such
516 as <filename>TMPDIR</filename>.
517 If this test fails, bad <filename>-rpath</filename> options are being
518 passed to the linker commands and your binaries have potential security
519 issues.</para></listitem>
520 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
521 Checks that the <filename>.so</filename> symbolic links are in the
522 <filename>-dev</filename> package and not in any of the other packages.
523 In general, these symlinks are only useful for development purposes.
524 Thus, the <filename>-dev</filename> package is the correct location for
525 them.
526 Some very rare cases do exist for dynamically loaded modules where
527 these symlinks are needed instead in the main package.
528 </para></listitem>
529 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
530 Checks for <filename>.debug</filename> directories in anything but the
531 <filename>-dbg</filename> package.
532 The debug files should all be in the <filename>-dbg</filename> package.
533 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
534 <listitem><para><emphasis><filename>arch:</filename></emphasis>
535 Checks the Executable and Linkable Format (ELF) type, bit size, and endianness
536 of any binaries to ensure they match the target architecture.
537 This test fails if any binaries don't match the type since there would be an
538 incompatibility.
539 Sometimes software, like bootloaders, might need to bypass this check.
540 </para></listitem>
541 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
542 Checks that <filename>-dbg</filename> packages only depend on other
543 <filename>-dbg</filename> packages and not on any other types of packages,
544 which would cause a packaging bug.</para></listitem>
545 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
546 Checks that <filename>-dev</filename> packages only depend on other
547 <filename>-dev</filename> packages and not on any other types of packages,
548 which would be a packaging bug.</para></listitem>
549 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
550 Checks <filename>.pc</filename> files for any
551 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
552 paths.
553 Any <filename>.pc</filename> file containing these paths is incorrect
554 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
555 when the files are accessed.</para></listitem>
556 <listitem><para><emphasis><filename>textrel:</filename></emphasis>
557 Checks for ELF binaries that contain relocations in their
558 <filename>.text</filename> sections, which can result in a
559 performance impact at runtime.</para></listitem>
560 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
561 Checks through the variables
562 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
563 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
564 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
565 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
566 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
567 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
568 <link linkend='var-FILES'><filename>FILES</filename></link>,
569 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
570 <filename>pkg_preinst</filename>,
571 <filename>pkg_postinst</filename>,
572 <filename>pkg_prerm</filename>
573 and <filename>pkg_postrm</filename>, and reports if there are
574 variable sets that are not package-specific.
575 Using these variables without a package suffix is bad practice,
576 and might unnecessarily complicate dependencies of other packages
577 within the same recipe or have other unintended consequences.
578 </para></listitem>
579 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
580 Checks that all packages containing Xorg drivers have ABI
581 dependencies.
582 The <filename>xserver-xorg</filename> recipe provides driver
583 ABI names.
584 All drivers should depend on the ABI versions that they have
585 been built against.
586 Driver recipes that include
587 <filename>xorg-driver-input.inc</filename>
588 or <filename>xorg-driver-video.inc</filename> will
589 automatically get these versions.
590 Consequently, you should only need to explicitly add
591 dependencies to binary driver recipes.
592 </para></listitem>
593 <listitem><para><emphasis><filename>libexec:</filename></emphasis>
594 Checks if a package contains files in
595 <filename>/usr/libexec</filename>.
596 This check is not performed if the
597 <filename>libexecdir</filename> variable has been set
598 explicitly to <filename>/usr/libexec</filename>.
599 </para></listitem>
600 <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
601 Checks for static library files (<filename>*.a</filename>) in
602 non-<filename>staticdev</filename> packages.
603 </para></listitem>
604 <listitem><para><emphasis><filename>la:</filename></emphasis>
605 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
606 paths.
607 Any <filename>.la</filename> file containing these paths is incorrect since
608 <filename>libtool</filename> adds the correct sysroot prefix when using the
609 files automatically itself.</para></listitem>
610 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
611 Runs the <filename>desktop-file-validate</filename> program
612 against any <filename>.desktop</filename> files to validate
613 their contents against the specification for
614 <filename>.desktop</filename> files.</para></listitem>
615 <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
616 Checks that produced binaries have not already been
617 stripped prior to the build system extracting debug symbols.
618 It is common for upstream software projects to default to
619 stripping debug symbols for output binaries.
620 In order for debugging to work on the target using
621 <filename>-dbg</filename> packages, this stripping must be
622 disabled.
623 </para></listitem>
624 <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
625 Reports that splitting or stripping debug symbols from binaries
626 has failed.
627 </para></listitem>
628 <listitem><para><emphasis><filename>arch:</filename></emphasis>
629 Checks to ensure the architecture, bit size, and endianness
630 of all output binaries matches that of the target.
631 This test can detect when the wrong compiler or compiler options
632 have been used.
633 </para></listitem>
634 <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
635 Reports when files have been installed within
636 <filename>do_install</filename> but have not been included in
637 any package by way of the
638 <link linkend='var-FILES'><filename>FILES</filename></link>
639 variable.
640 Files that do not appear in any package cannot be present in
641 an image later on in the build process.
642 Ideally, all installed files should be packaged or not
643 installed at all.
644 These files can be deleted at the end of
645 <filename>do_install</filename> if the files are not
646 needed in any package.
647 </para></listitem>
648 <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
649 Checks for invalid version comparison statements in runtime
650 dependency relationships between packages (i.e. in
651 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
652 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
653 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
654 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
655 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
656 and
657 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
658 variable values).
659 Any invalid comparisons might trigger failures or undesirable
660 behavior when passed to the package manager.
661 </para></listitem>
662 <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
663 Checks for
664 <link linkend='var-FILES'><filename>FILES</filename></link>
665 variable values that contain "//", which is invalid.
666 </para></listitem>
667 <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
668 Report when packages are excluded from being created due to
669 being marked with a license that is in
670 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
671 </para></listitem>
672 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
673 Checks the <filename>do_compile</filename> log for indications
674 that paths to locations on the build host were used.
675 Using such paths might result in host contamination of the
676 build output.
677 </para></listitem>
678 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
679 Checks the <filename>do_install</filename> log for indications
680 that paths to locations on the build host were used.
681 Using such paths might result in host contamination of the
682 build output.
683 </para></listitem>
684 <listitem><para><emphasis><filename>libdir:</filename></emphasis>
685 Checks for libraries being installed into incorrect
686 (possibly hardcoded) installation paths.
687 For example, this test will catch recipes that install
688 <filename>/lib/bar.so</filename> when
689 <filename>${base_libdir}</filename> is "lib32".
690 Another example is when recipes install
691 <filename>/usr/lib64/foo.so</filename> when
692 <filename>${libdir}</filename> is "/usr/lib".
693 </para></listitem>
694 <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
695 Checks for the same package being listed multiple times through
696 the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
697 variable value.
698 Installing the package in this manner can cause errors during
699 packaging.
700 </para></listitem>
701 <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
702 Reports lines in <filename>fs-perms.txt</filename> that have
703 an invalid format.
704 </para></listitem>
705 <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
706 Reports lines in <filename>fs-perms.txt</filename> that have
707 an invalid format.
708 </para></listitem>
709 <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
710 Reports lines in <filename>fs-perms.txt</filename> that
711 specify 'link' where the specified target already exists.
712 </para></listitem>
713 <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
714 Checks that all packages in
715 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
716 have names that do not contain invalid characters (i.e.
717 characters other than 0-9, a-z, ., +, and -).
718 </para></listitem>
719 <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
720 Checks that a recipe does not have a name
721 (<link linkend='var-PN'><filename>PN</filename></link>) value
722 that appears in
723 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
724 If a recipe is named such that its <filename>PN</filename>
725 value matches something already in
726 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
727 happens to be the same as
728 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
729 or
730 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
731 it can have unexpected consequences.
732 For example, assignments such as
733 <filename>FILES_${PN} = "xyz"</filename> effectively turn into
734 <filename>FILES = "xyz"</filename>.
735 </para></listitem>
736 <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
737 Reports when a binary installed in
738 <filename>${base_libdir}</filename>,
739 <filename>${base_bindir}</filename>, or
740 <filename>${base_sbindir}</filename>, depends on another
741 binary installed under <filename>${exec_prefix}</filename>.
742 This dependency is a concern if you want the system to remain
743 basically operable if <filename>/usr</filename> is mounted
744 separately and is not mounted.
745 <note>
746 Defaults for binaries installed in
747 <filename>${base_libdir}</filename>,
748 <filename>${base_bindir}</filename>, and
749 <filename>${base_sbindir}</filename> are
750 <filename>/lib</filename>, <filename>/bin</filename>, and
751 <filename>/sbin</filename>, respectively.
752 The default for a binary installed
753 under <filename>${exec_prefix}</filename> is
754 <filename>/usr</filename>.
755 </note>
756 </para></listitem>
757 <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis>
758 Reports when a script file installed in
759 <filename>${base_libdir}</filename>,
760 <filename>${base_bindir}</filename>, or
761 <filename>${base_sbindir}</filename>, depends on files
762 installed under <filename>${exec_prefix}</filename>.
763 This dependency is a concern if you want the system to remain
764 basically operable if <filename>/usr</filename> is mounted
765 separately and is not mounted.
766 <note>
767 Defaults for binaries installed in
768 <filename>${base_libdir}</filename>,
769 <filename>${base_bindir}</filename>, and
770 <filename>${base_sbindir}</filename> are
771 <filename>/lib</filename>, <filename>/bin</filename>, and
772 <filename>/sbin</filename>, respectively.
773 The default for a binary installed
774 under <filename>${exec_prefix}</filename> is
775 <filename>/usr</filename>.
776 </note>
777 </para></listitem>
778 <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
779 Reports when variables fundamental to packaging (i.e.
780 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
781 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
782 <link linkend='var-D'><filename>D</filename></link>,
783 <link linkend='var-PN'><filename>PN</filename></link>, and
784 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
785 undefined during <filename>do_package</filename>.
786 </para></listitem>
787 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
788 Checks to see if the <filename>PKGV</filename> variable
789 is undefined during <filename>do_package</filename>.
790 </para></listitem>
791 <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
792 Checks for paths to locations on the build host inside the
793 output files.
794 Currently, this test triggers too many false positives and
795 thus is not normally enabled.
796 </para></listitem>
797 <listitem><para><emphasis><filename>perms:</filename></emphasis>
798 Currently, this check is unused but reserved.
799 </para></listitem>
800 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
801 If Build History is enabled, reports when a package
802 being written out has a lower version than the previously
803 written package under the same name.
804 If you are placing output packages into a feed and
805 upgrading packages on a target system using that feed, the
806 version of a package going backwards can result in the target
807 system not correctly upgrading to the "new" version of the
808 package.
809 <note>
810 If you are not using runtime package management on your
811 target system, then you do not need to worry about
812 this situation.
813 </note>
814 </para></listitem>
815 </itemizedlist>
816 </para>
817</section>
818
819<section id='ref-classes-rm-work'>
820 <title>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></title>
821
822 <para>
823 The OpenEmbedded build system can use a substantial amount of disk
824 space during the build process.
825 A portion of this space is the work files under the
826 <filename>${TMPDIR}/work</filename> directory for each recipe.
827 Once the build system generates the packages for a recipe, the work
828 files for that recipe are no longer needed.
829 However, by default, the build system preserves these files
830 for inspection and possible debugging purposes.
831 If you would rather have these files deleted to save disk space
832 as the build progresses, you can enable <filename>rm_work</filename>
833 by adding the following to your <filename>local.conf</filename> file,
834 which is found in the
835 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
836 <literallayout class='monospaced'>
837 INHERIT += "rm_work"
838 </literallayout>
839 If you are modifying and building source code out of the work directory
840 for a recipe, enabling <filename>rm_work</filename> will potentially
841 result in your changes to the source being lost.
842 To exclude some recipes from having their work directories deleted by
843 <filename>rm_work</filename>, you can add the names of the recipe or
844 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
845 variable, which can also be set in your <filename>local.conf</filename>
846 file.
847 Here is an example:
848 <literallayout class='monospaced'>
849 RM_WORK_EXCLUDE += "busybox eglibc"
850 </literallayout>
851 </para>
852</section>
853
854
855<section id='ref-classes-siteinfo'>
856 <title>Autotools Configuration Data Cache - <filename>siteinfo.bbclass</filename></title>
857
858 <para>
859 Autotools can require tests that must execute on the target hardware.
860 Since this is not possible in general when cross compiling, site information is
861 used to provide cached test results so these tests can be skipped over but
862 still make the correct values available.
863 The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
864 contains test results sorted into different categories such as architecture, endianness, and
865 the <filename>libc</filename> used.
866 Site information provides a list of files containing data relevant to
867 the current build in the
868 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
869 that Autotools automatically picks up.
870 </para>
871
872 <para>
873 The class also provides variables like
874 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
875 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
876 that can be used elsewhere in the metadata.
877 </para>
878
879 <para>
880 Because this class is included from <filename>base.bbclass</filename>, it is always active.
881 </para>
882</section>
883
884<section id='ref-classes-useradd'>
885 <title>Adding Users - <filename>useradd.bbclass</filename></title>
886
887 <para>
888 If you have packages that install files that are owned by custom users or groups,
889 you can use this class to specify those packages and associate the users and groups
890 with those packages.
891 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
892 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
893 provides a simple example that shows how to add three
894 users and groups to two packages.
895 See the <filename>useradd-example.bb</filename> for more information on how to
896 use this class.
897 </para>
898</section>
899
900<section id='ref-classes-externalsrc'>
901 <title><filename>externalsrc.bbclass</filename></title>
902
903 <para>
904 You can use this class to build software from source code that is
905 external to the OpenEmbedded build system.
906 Building software from an external source tree means that the build
907 system's normal fetch, unpack, and patch process is not used.
908 </para>
909
910 <para>
911 By default, the OpenEmbedded build system uses the
912 <link linkend='var-S'><filename>S</filename></link> and
913 <link linkend='var-B'><filename>B</filename></link> variables to
914 locate unpacked recipe source code and to build it, respectively.
915 When your recipe inherits <filename>externalsrc.bbclass</filename>,
916 you use the
917 <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
918 and
919 <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
920 variables to ultimately define <filename>S</filename> and
921 <filename>B</filename>.
922 </para>
923
924 <para>
925 By default, this class expects the source code to support recipe builds
926 that use the <link linkend='var-B'><filename>B</filename></link>
927 variable to point to the directory in which the OpenEmbedded build
928 system places the generated objects built from the recipes.
929 By default, the <filename>B</filename> directory is set to the
930 following, which is separate from the source directory
931 (<filename>S</filename>):
932 <literallayout class='monospaced'>
933 ${WORKDIR}/${BPN}/{PV}/
934 </literallayout>
935 See the glossary entries for the
936 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
937 <link linkend='var-BPN'><filename>BPN</filename></link>,
938 <link linkend='var-PV'><filename>PV</filename></link>,
939 </para>
940
941 <para>
942 For more information on
943 <filename>externalsrc.bbclass</filename>, see the comments in
944 <filename>meta/classes/externalsrc.bbclass</filename> in the
945 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
946 For information on how to use <filename>externalsrc.bbclass</filename>,
947 see the
948 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
949 section in the Yocto Project Development Manual.
950 </para>
951</section>
952
953<section id='ref-classes-testimage'>
954 <title><filename>testimage.bbclass</filename></title>
955
956 <para>
957 You can use this class to enable running a series of automated tests
958 for images.
959 The class handles loading the tests and starting the image.
960 <note>
961 Currently, there is only support for running these tests
962 under QEMU.
963 </note>
964 </para>
965
966 <para>
967 To use the class, you need to perform steps to set up the
968 environment.
969 The tests are commands that run on the target system over
970 <filename>ssh</filename>.
971 they are written in Python and make use of the
972 <filename>unittest</filename> module.
973 </para>
974
975 <para>
976 For information on how to enable, run, and create new tests, see the
977 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
978 section.
979 </para>
980</section>
981
982<section id='ref-classes-others'>
983 <title>Other Classes</title>
984
985 <para>
986 Thus far, this chapter has discussed only the most useful and important
987 classes.
988 However, other classes exist within the <filename>meta/classes</filename> directory
989 in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
990 You can examine the <filename>.bbclass</filename> files directly for more
991 information.
992 </para>
993</section>
994
995<!-- Undocumented classes are:
996 allarch.bbclass
997 archive*.bbclass
998 binconfig.bbclass
999 bin_package.bbclass
1000 blacklist.bbclass
1001 bootimg.bbclass
1002 boot-directdisk.bbclass
1003 bugzilla.bbclass
1004 buildhistory.bbclass
1005 buildstats.bbclass
1006 ccache.bbclass
1007 chrpath.bbclass
1008 clutter.bbclass
1009 cmake.bbclass
1010 cml1.bbclass
1011 copyleft_compliance.bbclass
1012 core-image.bbclass
1013 cross.bbclass
1014 cross-canadian.bbclass
1015 crosssdk.bbclass
1016 deploy.bbclass
1017 distrodata.bbclass
1018 distro_features_check.bbclass
1019 dummy.bbclass
1020 extrausers.bbclass
1021 fontcache.bbclass
1022 gconf.bbclass
1023 gettext.bbclass
1024 gnomebase.bbclass
1025 gnome.bbclass
1026 grub-efi.bbclass
1027 gsettings.bbclass
1028 gtk-doc.bbclass
1029 gtk-icon-cache.bbclass
1030 gtk-immodules-cache.bbclass
1031 gzipnative.bbclass
1032 icecc.bbclass
1033 image-empty.bbclass
1034 image-live.bbclass
1035 image-vmdk.bbclass
1036 image-mklibs.bbclass
1037 image-prelink.bbclass
1038 image-swab.bbclass
1039 image_types.bbclass
1040 image_types_uboot.bbclass
1041 insserv.bbclass
1042 kernel-arch.bbclass
1043 kernel-module-split.bbclass
1044 kernel-yocto.bbclass
1045 lib_package.bbclass
1046 linux-kernel-base.bbclass
1047 license.bbclass
1048 logging.bbclass
1049 meta.bbclass
1050 metadata_scm.bbclass
1051 migrate_localcount.bbclass
1052 mime.bbclass
1053 mirrors.bbclass
1054 multilib*.bbclass
1055 native.bbclass
1056 nativesdk.bbclass
1057 oelint.bbclass
1058 own-mirrors.bbclass
1059 packagedata.bbclass
1060 packageinfo.bbclass
1061 patch.bbclass
1062 perlnative.bbclass
1063 pixbufcache.bbclass
1064 pkg_distribute.bbclass
1065 pkg_metainfo.bbclass
1066 populate_sdk*.bbclass
1067 prexport.bbclass
1068 primport.bbclass
1069 prserv.bbclass
1070 ptest.bbclass
1071 python-dir.bbclass
1072 pythonnative.bbclass
1073 qemu.bbclass
1074 qmake*.bbclass
1075 qt4*.bbclass
1076 recipe_sanity.bbclass
1077 relocatable.bbclass
1078 scons.bbclass
1079 sdl.bbclass
1080 setuptools.bbclass
1081 sip.bbclass
1082 siteconfig.bbclass
1083 sourcepkg.bbclass
1084 spdx.bbclass
1085 sstate.bbclass
1086 staging.bbclass
1087 syslinux.bbclass
1088 systemd.bbclass
1089 terminal.bbclass
1090 tinderclient.bbclass
1091 toolchain-scripts.bbclass
1092 typecheck.bbclass
1093 uboot-config.bbclass
1094 utility-tasks.bbclass
1095 utils.bbclass
1096 vala.bbclass
1097 waf.bbclass
1098-->
1099
1100
1101</chapter>
1102<!--
1103vim: expandtab tw=80 ts=4
1104-->
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
new file mode 100644
index 0000000000..3f216e3a64
--- /dev/null
+++ b/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,334 @@
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='ref-features'>
6 <title>Reference: Features</title>
7
8 <para>
9 This chapter provides a reference of shipped machine and distro features
10 you can include as part of the image, a reference on image types you can
11 build, and a reference on feature backfilling.
12 </para>
13
14 <para>
15 Features provide a mechanism for working out which packages
16 should be included in the generated images.
17 Distributions can select which features they want to support through the
18 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
19 variable, which is set in the <filename>poky.conf</filename> distribution configuration file.
20 Machine features are set in the
21 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
22 variable, which is set in the machine configuration file and
23 specifies the hardware features for a given machine.
24 </para>
25
26 <para>
27 These two variables combine to work out which kernel modules,
28 utilities, and other packages to include.
29 A given distribution can support a selected subset of features so some machine features might not
30 be included if the distribution itself does not support them.
31 </para>
32
33 <para>
34 One method you can use to determine which recipes are checking to see if a
35 particular feature is contained or not is to <filename>grep</filename> through
36 the <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
37 for the feature.
38 Here is an example that discovers the recipes whose build is potentially
39 changed based on a given feature:
40 <literallayout class='monospaced'>
41 $ cd $HOME/poky
42 $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
43 </literallayout>
44 </para>
45
46 <section id='ref-features-distro'>
47 <title>Distro</title>
48
49 <para>
50 The items below are features you can use with
51 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
52 Features do not have a one-to-one correspondence to packages, and they can
53 go beyond simply controlling the installation of a package or packages.
54 Sometimes a feature can influence how certain recipes are built.
55 For example, a feature might determine whether a particular configure option
56 is specified within <filename>do_configure</filename> for a particular
57 recipe.
58 </para>
59
60 <para>
61 This list only represents features as shipped with the Yocto Project metadata:
62 <itemizedlist>
63 <listitem><para><emphasis>alsa:</emphasis> Include ALSA support
64 (OSS compatibility kernel modules installed if available).
65 </para></listitem>
66 <listitem><para><emphasis>bluetooth:</emphasis> Include
67 bluetooth support (integrated BT only).</para></listitem>
68 <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
69 support.</para></listitem>
70 <listitem><para><emphasis>ext2:</emphasis> Include tools for
71 supporting for devices with internal HDD/Microdrive for
72 storing files (instead of Flash only devices).
73 </para></listitem>
74 <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
75 support.</para></listitem>
76 <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
77 </para></listitem>
78 <listitem><para><emphasis>irda:</emphasis> Include Irda support.
79 </para></listitem>
80 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
81 support (e.g. keymaps will be loaded during boot).
82 </para></listitem>
83 <listitem><para><emphasis>nfs:</emphasis> Include NFS client
84 support (for mounting NFS exports on device).
85 </para></listitem>
86 <listitem><para><emphasis>opengl:</emphasis>
87 Include the Open Graphics Library, which is a
88 cross-language, multi-platform application programming
89 interface used for rendering two and three-dimensional
90 graphics.</para></listitem>
91 <listitem><para><emphasis>pci:</emphasis> Include PCI bus
92 support.</para></listitem>
93 <listitem><para><emphasis>pcmcia:</emphasis> Include
94 PCMCIA/CompactFlash support.</para></listitem>
95 <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
96 support.</para></listitem>
97 <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
98 client support (for mounting Samba/Microsoft Windows shares
99 on device).</para></listitem>
100 <listitem><para><emphasis>systemd:</emphasis> Include support
101 for this <filename>init</filename> manager, which is a full
102 replacement of for <filename>init</filename> with parallel
103 starting of services, reduced shell overhead, and other
104 features.
105 This <filename>init</filename> manager is used by many
106 distributions.</para></listitem>
107 <listitem><para><emphasis>usbgadget:</emphasis> Include USB
108 Gadget Device support (for USB networking/serial/storage).
109 </para></listitem>
110 <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
111 support (allows to connect external keyboard, mouse,
112 storage, network etc).</para></listitem>
113 <listitem><para><emphasis>wayland:</emphasis> Include the
114 Wayland display server protocol and the library that
115 supports it.</para></listitem>
116 <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
117 (integrated only).</para></listitem>
118 <listitem><para><emphasis>sdk-pms:</emphasis> Include Package
119 Management Tools in the
120 <filename>nativesdk</filename> toolchain tarball.
121 Including these tools allows for easy sandbox use when
122 creating the root filesystem while using the SDK tarball.
123 </para></listitem>
124 </itemizedlist>
125 </para>
126 </section>
127
128 <section id='ref-features-machine'>
129 <title>Machine</title>
130
131 <para>
132 The items below are features you can use with
133 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
134 Features do not have a one-to-one correspondence to packages, and they can
135 go beyond simply controlling the installation of a package or packages.
136 Sometimes a feature can influence how certain recipes are built.
137 For example, a feature might determine whether a particular configure option
138 is specified within <filename>do_configure</filename> for a particular
139 recipe.
140 </para>
141
142 <para>
143 This feature list only represents features as shipped with the Yocto Project metadata:
144 <itemizedlist>
145 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
146 </para></listitem>
147 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
148 </para></listitem>
149 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
150 </para></listitem>
151 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
152 </para></listitem>
153 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
154 </para></listitem>
155 <listitem><para><emphasis>irda:</emphasis> Hardware has Irda support
156 </para></listitem>
157 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
158 </para></listitem>
159 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
160 </para></listitem>
161 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
162 </para></listitem>
163 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
164 </para></listitem>
165 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
166 </para></listitem>
167 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
168 </para></listitem>
169 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
170 </para></listitem>
171 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
172 </para></listitem>
173 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
174 </para></listitem>
175 </itemizedlist>
176 </para>
177 </section>
178
179 <section id='ref-features-image'>
180 <title>Images</title>
181
182 <para>
183 The contents of images generated by the OpenEmbedded build system can be controlled by the
184 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
185 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
186 variables that you typically configure in your image recipes.
187 Through these variables, you can add several different
188 predefined packages such as development utilities or packages with debug
189 information needed to investigate application problems or profile applications.
190 </para>
191
192 <para>
193 Current list of
194 <filename>IMAGE_FEATURES</filename> contains the following:
195 <itemizedlist>
196 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages
197 installed in a given image.</para></listitem>
198 <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and
199 extra library links) for all packages installed in a given image.</para></listitem>
200 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages
201 installed in a given image.</para></listitem>
202 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem>
203 <listitem><para><emphasis>read-only-rootfs:</emphasis> Creates
204 an image whose root filesystem is read-only.
205 See the
206 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
207 section in the Yocto Project Development Manual for more
208 information.</para></listitem>
209 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot.
210 By default, this screen is provided by <filename>psplash</filename>, which does
211 allow customization.
212 If you prefer to use an alternative splash screen package, you can do so by
213 setting the <filename>SPLASH</filename> variable
214 to a different package name (or names) within the image recipe or at the distro
215 configuration level.</para></listitem>
216 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
217 SSH server.
218 </para></listitem>
219 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
220 which is more full-featured than Dropbear.
221 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
222 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
223 precedence and Dropbear will not be installed.</para></listitem>
224 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
225 packages (i.e. static libraries containing <filename>*.a</filename> files) for all
226 packages installed in a given image.</para></listitem>
227 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
228 <filename>strace</filename> and <filename>gdb</filename>.
229 For information on GDB, see the
230 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
231 section in the Yocto Project Development Manual.
232 For information on tracing and profiling, see the
233 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
234 </para></listitem>
235 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
236 <filename>oprofile</filename>, <filename>exmap</filename>, and
237 <filename>LTTng</filename>.
238 For general information on user-space tools, see the
239 "<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>"
240 section in the Yocto Project Application Developer's Guide.</para></listitem>
241 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
242 </para></listitem>
243 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
244 touchscreen debugging).</para></listitem>
245 <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem>
246 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
247 minimal environment.</para></listitem>
248 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
249 </para></listitem>
250 </itemizedlist>
251 </para>
252 </section>
253
254 <section id='ref-features-backfill'>
255 <title>Feature Backfilling</title>
256
257 <para>
258 Sometimes it is necessary in the OpenEmbedded build system to extend
259 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
260 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
261 to control functionality that was previously enabled and not able
262 to be disabled.
263 For these cases, we need to add an
264 additional feature item to appear in one of these variables,
265 but we do not want to force developers who have existing values
266 of the variables in their configuration to add the new feature
267 in order to retain the same overall level of functionality.
268 Thus, the OpenEmbedded build system has a mechanism to
269 automatically "backfill" these added features into existing
270 distro or machine configurations.
271 You can see the list of features for which this is done by
272 finding the
273 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
274 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
275 variables in the <filename>meta/conf/bitbake.conf</filename> file.
276 </para>
277
278 <para>
279 Because such features are backfilled by default into all
280 configurations as described in the previous paragraph, developers
281 who wish to disable the new features need to be able to selectively
282 prevent the backfilling from occurring.
283 They can do this by adding the undesired feature or features to the
284 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
285 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
286 variables for distro features and machine features respectively.
287 </para>
288
289 <para>
290 Here are two examples to help illustrate feature backfilling:
291 <itemizedlist>
292 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
293 Previously, PulseAudio support was enabled within the Qt and
294 GStreamer frameworks.
295 Because of this, the feature is backfilled and thus
296 enabled for all distros through the
297 <filename>DISTRO_FEATURES_BACKFILL</filename>
298 variable in the <filename>meta/conf/bitbake.conf</filename> file.
299 However, your distro needs to disable the feature.
300 You can disable the feature without affecting
301 other existing distro configurations that need PulseAudio support
302 by adding "pulseaudio" to
303 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
304 in your distro's <filename>.conf</filename> file.
305 Adding the feature to this variable when it also
306 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
307 variable prevents the build system from adding the feature to
308 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
309 the feature for that particular distro.</para></listitem>
310 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
311 Previously, real time clock (RTC) support was enabled for all
312 target devices.
313 Because of this, the feature is backfilled and thus enabled
314 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
315 variable in the <filename>meta/conf/bitbake.conf</filename> file.
316 However, your target device does not have this capability.
317 You can disable RTC support for your device without
318 affecting other machines that need RTC support
319 by adding the feature to your machine's
320 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
321 list in the machine's <filename>.conf</filename> file.
322 Adding the feature to this variable when it also
323 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
324 variable prevents the build system from adding the feature to
325 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
326 disabling RTC support for that particular machine.</para></listitem>
327 </itemizedlist>
328 </para>
329 </section>
330</chapter>
331
332<!--
333vim: expandtab tw=80 ts=4 spell spelllang=en_gb
334-->
diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml
new file mode 100644
index 0000000000..37c8051a26
--- /dev/null
+++ b/documentation/ref-manual/ref-images.xml
@@ -0,0 +1,150 @@
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='ref-images'>
6 <title>Images</title>
7
8 <para>
9 The OpenEmbedded build system provides several example
10 images to satisfy different needs.
11 When you issue the <filename>bitbake</filename> command you provide a “top-level” recipe
12 that essentially begins the build for the type of image you want.
13 </para>
14
15 <note>
16 Building an image without GNU General Public License Version 3 (GPLv3) components
17 is only supported for minimal and base images.
18 Furthermore, if you are going to build an image using non-GPLv3 components,
19 you must make the following changes in the <filename>local.conf</filename> file
20 before using the BitBake command to build the minimal or base image:
21 <literallayout class='monospaced'>
22 1. Comment out the EXTRA_IMAGE_FEATURES line
23 2. Set INCOMPATIBLE_LICENSE = "GPLv3"
24 </literallayout>
25 </note>
26
27 <para>
28 From within the <filename>poky</filename> Git repository, use the following command to list
29 the supported images:
30 <literallayout class='monospaced'>
31 $ ls meta*/recipes*/images/*.bb
32 </literallayout>
33 These recipes reside in the <filename>meta/recipes-core/images</filename>,
34 <filename>meta/recipes-extended/images</filename>,
35 <filename>meta/recipes-graphics/images</filename>,
36 <filename>meta/recipes-qt/images</filename>,
37 <filename>meta/recipes-rt/images</filename>,
38 <filename>meta/recipes-sato/images</filename>, and
39 <filename>meta-skeleton/recipes-multilib/images</filename> directories
40 within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
41 Although the recipe names are somewhat explanatory, here is a list that describes them:
42 </para>
43
44 <itemizedlist>
45 <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis>
46 An example virtual machine that contains all the pieces required to
47 run builds using the build system as well as the build system itself.
48 You can boot and run the image using either the
49 <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink>
50 or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>.
51 For more information on this image, see the
52 <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on
53 the Yocto Project website.</para></listitem>
54 <listitem><para><emphasis><filename>core-image-base</filename>:</emphasis>
55 A console-only image that fully supports the target device hardware.</para></listitem>
56 <listitem><para><emphasis><filename>core-image-minimal</filename>:</emphasis>
57 A small image just capable of allowing a device to boot.</para></listitem>
58 <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis>
59 A <filename>core-image-minimal</filename> image suitable for development work
60 using the host.
61 The image includes headers and libraries you can use in a host development
62 environment.
63 </para></listitem>
64 <listitem><para><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis>
65 A <filename>core-image-minimal</filename> image that has the Minimal RAM-based
66 Initial Root Filesystem (<filename>initramfs</filename>) as part of the kernel,
67 which allows the system to find the first “init” program more efficiently.
68 </para></listitem>
69 <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis>
70 A <filename>core-image-minimal</filename> image that has support
71 for the Minimal MTD Utilities, which let the user interact with the
72 MTD subsystem in the kernel to perform operations on flash devices.
73 </para></listitem>
74 <listitem><para><emphasis><filename>core-image-basic</filename>:</emphasis>
75 A console-only image with more full-featured Linux system
76 functionality installed.</para></listitem>
77 <listitem><para><emphasis><filename>core-image-lsb</filename>:</emphasis>
78 An image that conforms to the Linux Standard Base (LSB) specification.
79 </para></listitem>
80 <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis>
81 A <filename>core-image-lsb</filename> image that is suitable for development work
82 using the host.
83 The image includes headers and libraries you can use in a host development
84 environment.
85 </para></listitem>
86 <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis>
87 A <filename>core-image-lsb</filename> that includes everything in meta-toolchain
88 but also includes development headers and libraries to form a complete standalone SDK.
89 This image is suitable for development using the target.</para></listitem>
90 <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis>
91 An image with support for the Open GL-based toolkit Clutter, which enables development of
92 rich and animated graphical user interfaces.</para></listitem>
93 <listitem><para><emphasis><filename>core-image-gtk-directfb</filename>:</emphasis>
94 An image that uses <filename>gtk+</filename> over <filename>directfb</filename>
95 instead of X11.
96 In order to build, this image requires specific distro configuration that enables
97 <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem>
98 <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis>
99 A very basic X11 image with a terminal.
100 </para></listitem>
101 <listitem><para><emphasis><filename>qt4e-demo-image</filename>:</emphasis>
102 An image that launches into the demo application for the embedded
103 (not based on X11) version of Qt.</para></listitem>
104 <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis>
105 A <filename>core-image-minimal</filename> image plus a real-time test suite and
106 tools appropriate for real-time use.</para></listitem>
107 <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis>
108 A <filename>core-image-rt</filename> image that includes everything in
109 <filename>meta-toolchain</filename>.
110 The image also includes development headers and libraries to form a complete
111 stand-alone SDK and is suitable for development using the target.
112 </para></listitem>
113 <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis>
114 An image with Sato support, a mobile environment and visual style that works well
115 with mobile devices.
116 The image supports X11 with a Sato theme and applications such as
117 a terminal, editor, file manager, media player, and so forth.
118 </para></listitem>
119 <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis>
120 A <filename>core-image-sato</filename> image suitable for development
121 using the host.
122 The image includes libraries needed to build applications on the device itself,
123 testing and profiling tools, and debug symbols.
124 This image was formerly <filename>core-image-sdk</filename>.
125 </para></listitem>
126 <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis>
127 A <filename>core-image-sato</filename> image that includes everything in meta-toolchain.
128 The image also includes development headers and libraries to form a complete standalone SDK
129 and is suitable for development using the target.</para></listitem>
130 <listitem><para><emphasis><filename>core-image-multilib-example</filename>:</emphasis>
131 An example image that includes a <filename>lib32</filename> version
132 of Bash into an otherwise standard <filename>sato</filename> image.
133 The image assumes a "lib32" multilib has been enabled in the your
134 configuration.</para></listitem>
135 </itemizedlist>
136
137 <tip>
138 From the Yocto Project release 1.1 onwards, <filename>-live</filename> and
139 <filename>-directdisk</filename> images have been replaced by a "live"
140 option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an
141 image file that can be
142 copied directly to a CD or USB device and run as is.
143 To build a live image, simply add
144 "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename>
145 file or wherever appropriate and then build the desired image as normal.
146 </tip>
147</chapter>
148<!--
149vim: expandtab tw=80 ts=4
150-->
diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl
new file mode 100644
index 0000000000..3ad3a315c0
--- /dev/null
+++ b/documentation/ref-manual/ref-manual-customization.xsl
@@ -0,0 +1,11 @@
1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
3
4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
5
6 <xsl:param name="html.stylesheet" select="'ref-style.css'" />
7 <xsl:param name="chapter.autolabel" select="1" />
8 <xsl:param name="appendix.autolabel" select="A" />
9 <xsl:param name="section.autolabel" select="1" />
10 <xsl:param name="section.label.includes.component.label" select="1" />
11</xsl:stylesheet>
diff --git a/documentation/ref-manual/ref-manual-eclipse-customization.xsl b/documentation/ref-manual/ref-manual-eclipse-customization.xsl
new file mode 100644
index 0000000000..4e6b7997b8
--- /dev/null
+++ b/documentation/ref-manual/ref-manual-eclipse-customization.xsl
@@ -0,0 +1,27 @@
1<?xml version='1.0'?>
2<xsl:stylesheet
3 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4 xmlns="http://www.w3.org/1999/xhtml"
5 xmlns:fo="http://www.w3.org/1999/XSL/Format"
6 version="1.0">
7
8 <xsl:import
9 href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
10
11 <xsl:param name="chunker.output.indent" select="'yes'"/>
12 <xsl:param name="chunk.quietly" select="1"/>
13 <xsl:param name="chunk.first.sections" select="1"/>
14 <xsl:param name="chunk.section.depth" select="10"/>
15 <xsl:param name="use.id.as.filename" select="1"/>
16 <xsl:param name="ulink.target" select="'_self'" />
17 <xsl:param name="base.dir" select="'html/ref-manual/'"/>
18 <xsl:param name="html.stylesheet" select="'../book.css'"/>
19 <xsl:param name="eclipse.manifest" select="0"/>
20 <xsl:param name="create.plugin.xml" select="0"/>
21 <xsl:param name="suppress.navigation" select="1"/>
22 <xsl:param name="generate.index" select="0"/>
23 <xsl:param name="chapter.autolabel" select="1" />
24 <xsl:param name="appendix.autolabel">A</xsl:param>
25 <xsl:param name="section.autolabel" select="1" />
26 <xsl:param name="section.label.includes.component.label" select="1" />
27</xsl:stylesheet>
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml
new file mode 100644
index 0000000000..7db880b404
--- /dev/null
+++ b/documentation/ref-manual/ref-manual.xml
@@ -0,0 +1,138 @@
1<!DOCTYPE book 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<book id='ref-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/poky-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title>
20 Yocto Project Reference Manual
21 </title>
22
23 <authorgroup>
24 <author>
25 <firstname>Richard</firstname> <surname>Purdie</surname>
26 <affiliation>
27 <orgname>Linux Foundation</orgname>
28 </affiliation>
29 <email>richard.purdie@linuxfoundation.org</email>
30 </author>
31
32 </authorgroup>
33
34 <revhistory>
35 <revision>
36 <revnumber>4.0+git</revnumber>
37 <date>24 November 2010</date>
38 <revremark>Released with the Yocto Project 0.9 Release</revremark>
39 </revision>
40 <revision>
41 <revnumber>1.0</revnumber>
42 <date>6 April 2011</date>
43 <revremark>Released with the Yocto Project 1.0 Release.</revremark>
44 </revision>
45 <revision>
46 <revnumber>1.0.1</revnumber>
47 <date>23 May 2011</date>
48 <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
49 </revision>
50 <revision>
51 <revnumber>1.1</revnumber>
52 <date>6 October 2011</date>
53 <revremark>Released with the Yocto Project 1.1 Release.</revremark>
54 </revision>
55 <revision>
56 <revnumber>1.2</revnumber>
57 <date>April 2012</date>
58 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
59 </revision>
60 <revision>
61 <revnumber>1.3</revnumber>
62 <date>October 2012</date>
63 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
64 </revision>
65 <revision>
66 <revnumber>1.4</revnumber>
67 <date>April 2013</date>
68 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
69 </revision>
70 <revision>
71 <revnumber>1.5</revnumber>
72 <date>October 2013</date>
73 <revremark>Released with the Yocto Project 1.5 Release.</revremark>
74 </revision>
75 <revision>
76 <revnumber>1.5.1</revnumber>
77 <date>Sometime in 2013</date>
78 <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
79 </revision>
80 </revhistory>
81
82 <copyright>
83 <year>&COPYRIGHT_YEAR;</year>
84 <holder>Linux Foundation</holder>
85 </copyright>
86
87 <legalnotice>
88 <para>
89 Permission is granted to copy, distribute and/or modify this document under
90 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
91 </para>
92 <note>
93 For the latest version of this manual associated with this
94 Yocto Project release, see the
95 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>
96 from the Yocto Project website.
97 </note>
98 </legalnotice>
99
100 </bookinfo>
101
102 <xi:include href="introduction.xml"/>
103
104 <xi:include href="usingpoky.xml"/>
105
106 <xi:include href="closer-look.xml"/>
107
108 <xi:include href="technical-details.xml"/>
109
110 <xi:include href="migration.xml"/>
111
112 <xi:include href="ref-structure.xml"/>
113
114 <xi:include href="ref-bitbake.xml"/>
115
116 <xi:include href="ref-classes.xml"/>
117
118 <xi:include href="ref-images.xml"/>
119
120 <xi:include href="ref-features.xml"/>
121
122 <xi:include href="ref-variables.xml"/>
123
124 <xi:include href="ref-varlocality.xml"/>
125
126 <xi:include href="faq.xml"/>
127
128 <xi:include href="resources.xml"/>
129
130<!-- <index id='index'>
131 <title>Index</title>
132 </index>
133-->
134
135</book>
136<!--
137vim: expandtab tw=80 ts=4
138-->
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
new file mode 100644
index 0000000000..13803f5a41
--- /dev/null
+++ b/documentation/ref-manual/ref-structure.xml
@@ -0,0 +1,953 @@
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='ref-structure'>
6
7<title>Source Directory Structure</title>
8
9<para>
10 The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components.
11 Understanding them and knowing where they are located is key to using the Yocto Project well.
12 This chapter describes the Source Directory and gives information about the various
13 files and directories.
14</para>
15
16<para>
17 For information on how to establish a local Source Directory on your development system, see the
18 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
19 section in the Yocto Project Development Manual.
20</para>
21
22<note>
23 The OpenEmbedded build system does not support file or directory names that
24 contain spaces.
25 Be sure that the Source Directory you use does not contain these types
26 of names.
27</note>
28
29<section id='structure-core'>
30 <title>Top-Level Core Components</title>
31
32 <para>
33 This section describes the top-level components of the
34 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
35 </para>
36
37 <section id='structure-core-bitbake'>
38 <title><filename>bitbake/</filename></title>
39
40 <para>
41 This directory includes a copy of BitBake for ease of use.
42 The copy usually matches the current stable BitBake release from the BitBake project.
43 BitBake, a
44 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
45 interpreter, reads the Yocto Project metadata and runs the tasks
46 defined by that data.
47 Failures are usually from the metadata and not from BitBake itself.
48 Consequently, most users do not need to worry about BitBake.
49 </para>
50
51 <para>
52 When you run the <filename>bitbake</filename> command, the wrapper script in
53 <filename>scripts/</filename> is executed to run the main BitBake executable,
54 which resides in the <filename>bitbake/bin/</filename> directory.
55 Sourcing the <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
56 script places the <filename>scripts</filename> and <filename>bitbake/bin</filename>
57 directories (in that order) into the shell's <filename>PATH</filename> environment
58 variable.
59 </para>
60
61 <para>
62 For more information on BitBake, see the BitBake documentation
63 included in the <filename>bitbake/doc/manual</filename> directory of the
64 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
65 </para>
66 </section>
67
68 <section id='structure-core-build'>
69 <title><filename>build/</filename></title>
70
71 <para>
72 This directory contains user configuration files and the output
73 generated by the OpenEmbedded build system in its standard configuration where
74 the source tree is combined with the output.
75 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
76 is created initially when you <filename>source</filename>
77 the OpenEmbedded build environment setup script
78 (i.e.
79 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
80 or
81 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
82 </para>
83
84 <para>
85 It is also possible to place output and configuration
86 files in a directory separate from the
87 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
88 by providing a directory name when you <filename>source</filename>
89 the setup script.
90 For information on separating output from your local
91 Source Directory files, see the
92 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
93 and
94 "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
95 sections.
96 </para>
97 </section>
98
99 <section id='handbook'>
100 <title><filename>documentation</filename></title>
101
102 <para>
103 This directory holds the source for the Yocto Project documentation
104 as well as templates and tools that allow you to generate PDF and HTML
105 versions of the manuals.
106 Each manual is contained in a sub-folder.
107 For example, the files for this manual reside in
108 <filename>ref-manual</filename>.
109 </para>
110 </section>
111
112 <section id='structure-core-meta'>
113 <title><filename>meta/</filename></title>
114
115 <para>
116 This directory contains the OpenEmbedded Core metadata.
117 The directory holds recipes, common classes, and machine
118 configuration for emulated targets (<filename>qemux86</filename>,
119 <filename>qemuarm</filename>, and so forth.)
120 </para>
121 </section>
122
123 <section id='structure-core-meta-yocto'>
124 <title><filename>meta-yocto/</filename></title>
125
126 <para>
127 This directory contains the configuration for the Poky
128 reference distribution.
129 </para>
130 </section>
131
132 <section id='structure-core-meta-yocto-bsp'>
133 <title><filename>meta-yocto-bsp/</filename></title>
134
135 <para>
136 This directory contains the Yocto Project reference
137 hardware Board Support Packages (BSPs).
138 For more information on BSPs, see the
139 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support
140 Package (BSP) Developer's Guide</ulink>.
141 </para>
142 </section>
143
144 <section id='structure-meta-hob'>
145 <title><filename>meta-hob/</filename></title>
146
147 <para>
148 This directory contains template recipes used by Hob,
149 which is a Yocto Project build user interface.
150 For more information on the Hob, see the
151 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project</ulink>
152 web page.
153 </para>
154 </section>
155
156 <section id='structure-meta-skeleton'>
157 <title><filename>meta-skeleton/</filename></title>
158
159 <para>
160 This directory contains template recipes for BSP and kernel development.
161 </para>
162 </section>
163
164 <section id='structure-core-scripts'>
165 <title><filename>scripts/</filename></title>
166
167 <para>
168 This directory contains various integration scripts that implement
169 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
170 The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
171 and
172 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
173 scripts append this directory to the shell's
174 <filename>PATH</filename> environment variable.
175 </para>
176
177 <para>
178 The <filename>scripts</filename> directory has useful scripts that assist contributing
179 back to the Yocto Project, such as <filename>create_pull_request</filename> and
180 <filename>send_pull_request</filename>.
181 </para>
182 </section>
183
184 <section id='structure-core-script'>
185 <title><filename>&OE_INIT_FILE;</filename></title>
186
187 <para>
188 This script is one of two scripts that set up the OpenEmbedded build
189 environment.
190 For information on the other script, see the
191 "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
192 section.
193 </para>
194
195 <para>
196 Running this script with the <filename>source</filename> command in
197 a shell makes changes to <filename>PATH</filename> and sets other
198 core BitBake variables based on the current working directory.
199 You need to run an environment setup script before running BitBake
200 commands.
201 The script uses other scripts within the
202 <filename>scripts</filename> directory to do the bulk of the work.
203 </para>
204
205 <para>
206 By default, running this script without a
207 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
208 argument creates the <filename>build</filename> directory.
209 If you provide a Build Directory argument when you
210 <filename>source</filename> the script, you direct the OpenEmbedded
211 build system to create a Build Directory of your choice.
212 For example, the following command creates a Build Directory named
213 <filename>mybuilds</filename> that is outside of the
214 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
215 <literallayout class='monospaced'>
216 $ source &OE_INIT_FILE; ~/mybuilds
217 </literallayout>
218 <note>
219 The OpenEmbedded build system does not support file or directory names that
220 contain spaces.
221 If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
222 from a Source Directory that contains spaces in either the filenames
223 or directory names, the script returns an error indicating no such
224 file or directory.
225 Be sure to use a Source Directory free of names containing spaces.
226 </note>
227 </para>
228 </section>
229
230 <section id='structure-memres-core-script'>
231 <title><filename>oe-init-build-env-memres</filename></title>
232
233 <para>
234 This script is one of two scripts that set up the OpenEmbedded build
235 environment.
236 Setting up the environment with this script uses a
237 memory-resident BitBake.
238 For information on the other setup script, see the
239 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
240 section.
241 </para>
242
243 <para>
244 Memory-resident BitBake resides in memory until you specifically
245 remove it using the following BitBake command:
246 <literallayout class='monospaced'>
247 $ bitbake -m
248 </literallayout>
249 </para>
250
251 <para>
252 Running this script with the <filename>source</filename> command in
253 a shell makes changes to <filename>PATH</filename> and sets other
254 core BitBake variables based on the current working directory.
255 One of these variables is the
256 <link linkend='var-BBSERVER'><filename>BBSERVER</filename></link>
257 variable, which allows the OpenEmbedded build system to locate
258 the server that is running BitBake.
259 </para>
260
261 <para>
262 You need to run an environment setup script before running BitBake
263 commands.
264 Following is the script syntax:
265 <literallayout class='monospaced'>
266 $ source oe-init-build-env-memres &lt;port_number&gt; &lt;build_dir&gt;
267 </literallayout>
268 The script uses other scripts within the
269 <filename>scripts</filename> directory to do the bulk of the work.
270 </para>
271
272 <para>
273 If you do not provide a port number with the script, the default
274 port "12345" is used.
275 </para>
276
277 <para>
278 By default, running this script without a
279 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
280 argument creates the <filename>build</filename> directory.
281 If you provide a Build Directory argument when you
282 <filename>source</filename> the script, you direct the OpenEmbedded
283 build system to create a Build Directory of your choice.
284 For example, the following command uses the default port number
285 "12345" and creates a Build Directory named
286 <filename>mybuilds</filename> that is outside of the
287 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
288 <literallayout class='monospaced'>
289 $ source oe-init-build-env-memres ~/mybuilds
290 </literallayout>
291 <note>
292 The OpenEmbedded build system does not support file or
293 directory names that contain spaces.
294 If you attempt to run the
295 <filename>oe-init-build-env-memres</filename> script
296 from a Source Directory that contains spaces in either the
297 filenames or directory names, the script returns an error
298 indicating no such file or directory.
299 Be sure to use a Source Directory free of names containing
300 spaces.
301 </note>
302 </para>
303 </section>
304
305 <section id='structure-basic-top-level'>
306 <title><filename>LICENSE, README, and README.hardware</filename></title>
307
308 <para>
309 These files are standard top-level files.
310 </para>
311 </section>
312</section>
313
314<section id='structure-build'>
315 <title>The Build Directory - <filename>build/</filename></title>
316
317 <para>
318 The OpenEmbedded build system creates the
319 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
320 during the build.
321 By default, this directory is named <filename>build</filename>.
322 </para>
323
324 <section id='structure-build-pseudodone'>
325 <title><filename>build/pseudodone</filename></title>
326
327 <para>
328 This tag file indicates that the initial pseudo binary was created.
329 The file is built the first time BitBake is invoked.
330 </para>
331 </section>
332
333 <section id='structure-build-conf-local.conf'>
334 <title><filename>build/conf/local.conf</filename></title>
335
336 <para>
337 This configuration file contains all the local user configurations
338 for your build environment.
339 The <filename>local.conf</filename> file contains documentation on
340 the various configuration options.
341 Any variable set here overrides any variable set elsewhere within
342 the environment unless that variable is hard-coded within a file
343 (e.g. by using '=' instead of '?=').
344 Some variables are hard-coded for various reasons but these
345 variables are relatively rare.
346 </para>
347
348 <para>
349 Edit this file to set the
350 <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
351 for which you want to build, which package types you wish to use
352 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
353 the location from which you want to downloaded files
354 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
355 and how you want your host machine to use resources
356 (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
357 and
358 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
359 </para>
360
361 <para>
362 If <filename>local.conf</filename> is not present when you
363 start the build, the OpenEmbedded build system creates it from
364 <filename>local.conf.sample</filename> when
365 you <filename>source</filename> the top-level build environment
366 setup script (i.e.
367 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
368 or
369 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
370 </para>
371
372 <para>
373 The source <filename>local.conf.sample</filename> file used
374 depends on the <filename>$TEMPLATECONF</filename> script variable,
375 which defaults to <filename>/meta-yocto/conf</filename>
376 when you are building from the Yocto Project development
377 environment and defaults to <filename>/meta/conf</filename> when
378 you are building from the OpenEmbedded Core environment.
379 Because the script variable points to the source of the
380 <filename>local.conf.sample</filename> file, this implies that
381 you can configure your build environment from any layer by setting
382 the variable in the top-level build environment setup script as
383 follows:
384 <literallayout class='monospaced'>
385 TEMPLATECONF=&lt;your_layer&gt;/conf
386 </literallayout>
387 Once the build process gets the sample file, it uses
388 <filename>sed</filename> to substitute final
389 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
390 values for all <filename>##OEROOT##</filename> values.
391 <note>
392 You can see how the <filename>TEMPLATECONF</filename> variable
393 is used by looking at the
394 <filename>/scripts/oe-setup-builddir</filename> script in the
395 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
396 You can find the Yocto Project version of the
397 <filename>local.conf.sample</filename> file in the
398 <filename>/meta-yocto/conf</filename> directory.
399 </note>
400 </para>
401 </section>
402
403 <section id='structure-build-conf-bblayers.conf'>
404 <title><filename>build/conf/bblayers.conf</filename></title>
405
406 <para>
407 This configuration file defines
408 <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
409 which are directory trees, traversed (or walked) by BitBake.
410 The <filename>bblayers.conf</filename> file uses the
411 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
412 variable to list the layers BitBake tries to find, and uses the
413 <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
414 variable to list layers that must not be removed.
415 </para>
416
417 <para>
418 If <filename>bblayers.conf</filename> is not present when you
419 start the build, the OpenEmbedded build system creates it from
420 <filename>bblayers.conf.sample</filename> when
421 you <filename>source</filename> the top-level build environment
422 setup script (i.e.
423 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
424 or
425 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
426 </para>
427
428 <para>
429 The source <filename>bblayers.conf.sample</filename> file used
430 depends on the <filename>$TEMPLATECONF</filename> script variable,
431 which defaults to <filename>/meta-yocto/conf</filename>
432 when you are building from the Yocto Project development
433 environment and defaults to <filename>/meta/conf</filename> when
434 you are building from the OpenEmbedded Core environment.
435 Because the script variable points to the source of the
436 <filename>bblayers.conf.sample</filename> file, this implies that
437 you can base your build from any layer by setting the variable in
438 the top-level build environment setup script as follows:
439 <literallayout class='monospaced'>
440 TEMPLATECONF=&lt;your_layer&gt;/conf
441 </literallayout>
442 Once the build process gets the sample file, it uses
443 <filename>sed</filename> to substitute final
444 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
445 values for all <filename>##OEROOT##</filename> values.
446 <note>
447 You can see how the <filename>TEMPLATECONF</filename> variable
448 <filename>/scripts/oe-setup-builddir</filename> script in the
449 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
450 You can find the Yocto Project version of the
451 <filename>bblayers.conf.sample</filename> file in the
452 <filename>/meta-yocto/conf</filename> directory.
453 </note>
454 </para>
455 </section>
456
457 <section id='structure-build-conf-sanity_info'>
458 <title><filename>build/conf/sanity_info</filename></title>
459
460 <para>
461 This file indicates the state of the sanity checks and is created
462 during the build.
463 </para>
464 </section>
465
466 <section id='structure-build-downloads'>
467 <title><filename>build/downloads/</filename></title>
468
469 <para>
470 This directory contains downloaded upstream source tarballs.
471 You can reuse the directory for multiple builds or move
472 the directory to another location.
473 You can control the location of this directory through the
474 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
475 </para>
476 </section>
477
478 <section id='structure-build-sstate-cache'>
479 <title><filename>build/sstate-cache/</filename></title>
480
481 <para>
482 This directory contains the shared state cache.
483 You can reuse the directory for multiple builds or move
484 the directory to another location.
485 You can control the location of this directory through the
486 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
487 </para>
488 </section>
489
490 <section id='structure-build-tmp'>
491 <title><filename>build/tmp/</filename></title>
492
493 <para>
494 This directory receives all the OpenEmbedded build system's output.
495 BitBake creates this directory if it does not exist.
496 As a last resort, to clean up a build and start it from scratch (other than the downloads),
497 you can remove everything in the <filename>tmp</filename> directory or get rid of the
498 directory completely.
499 If you do, you should also completely remove the
500 <filename>build/sstate-cache</filename> directory.
501 </para>
502 </section>
503
504 <section id='structure-build-tmp-buildstats'>
505 <title><filename>build/tmp/buildstats/</filename></title>
506
507 <para>
508 This directory stores the build statistics.
509 </para>
510 </section>
511
512 <section id='structure-build-tmp-cache'>
513 <title><filename>build/tmp/cache/</filename></title>
514
515 <para>
516 When BitBake parses the metadata, it creates a cache file of the result that can
517 be used when subsequently running commands.
518 BitBake stores these results here on a per-machine basis.
519 </para>
520 </section>
521
522 <section id='structure-build-tmp-deploy'>
523 <title><filename>build/tmp/deploy/</filename></title>
524
525 <para>
526 This directory contains any "end result" output from the
527 OpenEmbedded build process.
528 The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
529 variable points to this directory.
530 For more detail on the contents of the <filename>deploy</filename>
531 directory, see the
532 "<link linkend='images-dev-environment'>Images</link>" and
533 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
534 sections.
535 </para>
536 </section>
537
538 <section id='structure-build-tmp-deploy-deb'>
539 <title><filename>build/tmp/deploy/deb/</filename></title>
540
541 <para>
542 This directory receives any <filename>.deb</filename> packages produced by
543 the build process.
544 The packages are sorted into feeds for different architecture types.
545 </para>
546 </section>
547
548 <section id='structure-build-tmp-deploy-rpm'>
549 <title><filename>build/tmp/deploy/rpm/</filename></title>
550
551 <para>
552 This directory receives any <filename>.rpm</filename> packages produced by
553 the build process.
554 The packages are sorted into feeds for different architecture types.
555 </para>
556 </section>
557
558 <section id='structure-build-tmp-deploy-licenses'>
559 <title><filename>build/tmp/deploy/licenses/</filename></title>
560
561 <para>
562 This directory receives package licensing information.
563 For example, the directory contains sub-directories for <filename>bash</filename>,
564 <filename>busybox</filename>, and <filename>eglibc</filename> (among others) that in turn
565 contain appropriate <filename>COPYING</filename> license files with other licensing information.
566 For information on licensing, see the
567 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
568 section.
569 </para>
570 </section>
571
572 <section id='structure-build-tmp-deploy-images'>
573 <title><filename>build/tmp/deploy/images/</filename></title>
574
575 <para>
576 This directory receives complete filesystem images.
577 If you want to flash the resulting image from a build onto a device, look here for the image.
578 </para>
579
580 <para>
581 Be careful when deleting files in this directory.
582 You can safely delete old images from this directory (e.g.
583 <filename>core-image-*</filename>, <filename>hob-image-*</filename>,
584 etc.).
585 However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
586 bootloader and other supplementary files might be deployed here prior to building an
587 image.
588 Because these files are not directly produced from the image, if you
589 delete them they will not be automatically re-created when you build the image again.
590 </para>
591
592 <para>
593 If you do accidentally delete files here, you will need to force them to be
594 re-created.
595 In order to do that, you will need to know the target that produced them.
596 For example, these commands rebuild and re-create the kernel files:
597 <literallayout class='monospaced'>
598 $ bitbake -c clean virtual/kernel
599 $ bitbake virtual/kernel
600 </literallayout>
601 </para>
602 </section>
603
604 <section id='structure-build-tmp-deploy-ipk'>
605 <title><filename>build/tmp/deploy/ipk/</filename></title>
606
607 <para>
608 This directory receives <filename>.ipk</filename> packages produced by
609 the build process.</para>
610 </section>
611
612 <section id='structure-build-tmp-sysroots'>
613 <title><filename>build/tmp/sysroots/</filename></title>
614
615 <para>
616 This directory contains shared header files and libraries as well as other shared
617 data.
618 Packages that need to share output with other packages do so within this directory.
619 The directory is subdivided by architecture so multiple builds can run within
620 the one Build Directory.
621 </para>
622 </section>
623
624 <section id='structure-build-tmp-stamps'>
625 <title><filename>build/tmp/stamps/</filename></title>
626
627 <para>
628 This directory holds information that BitBake uses for accounting purposes
629 to track what tasks have run and when they have run.
630 The directory is sub-divided by architecture, package name, and
631 version.
632 Following is an example:
633 <literallayout class='monospaced'>
634 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
635 </literallayout>
636 Although the files in the directory are empty of data,
637 BitBake uses the filenames and timestamps for tracking purposes.
638 </para>
639 </section>
640
641 <section id='structure-build-tmp-log'>
642 <title><filename>build/tmp/log/</filename></title>
643
644 <para>
645 This directory contains general logs that are not otherwise placed using the
646 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
647 Examples of logs are the output from the <filename>check_pkg</filename> or
648 <filename>distro_check</filename> tasks.
649 Running a build does not necessarily mean this directory is created.
650 </para>
651 </section>
652
653 <section id='structure-build-tmp-pkgdata'>
654 <title><filename>build/tmp/pkgdata/</filename></title>
655
656 <para>
657 This directory contains intermediate packaging data that is used later in the packaging process.
658 For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section.
659 </para>
660 </section>
661
662 <section id='structure-build-tmp-work'>
663 <title><filename>build/tmp/work/</filename></title>
664
665 <para>
666 This directory contains architecture-specific work sub-directories
667 for packages built by BitBake.
668 All tasks execute from the appropriate work directory.
669 For example, the source for a particular package is unpacked,
670 patched, configured and compiled all within its own work directory.
671 Within the work directory, organization is based on the package group
672 and version for which the source is being compiled
673 as defined by the
674 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
675 </para>
676
677 <para>
678 It is worth considering the structure of a typical work directory.
679 As an example, consider <filename>linux-yocto-kernel-3.0</filename>
680 on the machine <filename>qemux86</filename>
681 built within the Yocto Project.
682 For this package, a work directory of
683 <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
684 referred to as the
685 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
686 Within this directory, the source is unpacked to
687 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt.
688 (See the
689 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using a Quilt Flow</ulink>"
690 section in the Yocto Project Development Manual for more information.)
691 Within the <filename>linux-qemux86-standard-build</filename> directory,
692 standard Quilt directories <filename>linux-3.0/patches</filename>
693 and <filename>linux-3.0/.pc</filename> are created,
694 and standard Quilt commands can be used.
695 </para>
696
697 <para>
698 There are other directories generated within <filename>WORKDIR</filename>.
699 The most important directory is <filename>WORKDIR/temp/</filename>,
700 which has log files for each task (<filename>log.do_*.pid</filename>)
701 and contains the scripts BitBake runs for each task
702 (<filename>run.do_*.pid</filename>).
703 The <filename>WORKDIR/image/</filename> directory is where "make
704 install" places its output that is then split into sub-packages
705 within <filename>WORKDIR/packages-split/</filename>.
706 </para>
707 </section>
708</section>
709
710<section id='structure-meta'>
711 <title>The Metadata - <filename>meta/</filename></title>
712
713 <para>
714 As mentioned previously,
715 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> is the core
716 of the Yocto Project.
717 Metadata has several important subdivisions:
718 </para>
719
720 <section id='structure-meta-classes'>
721 <title><filename>meta/classes/</filename></title>
722
723 <para>
724 This directory contains the <filename>*.bbclass</filename> files.
725 Class files are used to abstract common code so it can be reused by multiple
726 packages.
727 Every package inherits the <filename>base.bbclass</filename> file.
728 Examples of other important classes are <filename>autotools.bbclass</filename>, which
729 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
730 Another example is <filename>kernel.bbclass</filename> that contains common code and functions
731 for working with the Linux kernel.
732 Functions like image generation or packaging also have their specific class files
733 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
734 <filename>package*.bbclass</filename>.
735 </para>
736
737 <para>
738 For reference information on classes, see the
739 "<link linkend='ref-classes'>Classes</link>" chapter.
740 </para>
741 </section>
742
743 <section id='structure-meta-conf'>
744 <title><filename>meta/conf/</filename></title>
745
746 <para>
747 This directory contains the core set of configuration files that start from
748 <filename>bitbake.conf</filename> and from which all other configuration
749 files are included.
750 See the include statements at the end of the
751 <filename>bitbake.conf</filename> file and you will note that even
752 <filename>local.conf</filename> is loaded from there.
753 While <filename>bitbake.conf</filename> sets up the defaults, you can often override
754 these by using the (<filename>local.conf</filename>) file, machine file or
755 the distribution configuration file.
756 </para>
757 </section>
758
759 <section id='structure-meta-conf-machine'>
760 <title><filename>meta/conf/machine/</filename></title>
761
762 <para>
763 This directory contains all the machine configuration files.
764 If you set <filename>MACHINE = "qemux86"</filename>,
765 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
766 directory.
767 The <filename>include</filename> directory contains various data common to multiple machines.
768 If you want to add support for a new machine to the Yocto Project, look in this directory.
769 </para>
770 </section>
771
772 <section id='structure-meta-conf-distro'>
773 <title><filename>meta/conf/distro/</filename></title>
774
775 <para>
776 The contents of this directory controls any distribution-specific
777 configurations.
778 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
779 This directory includes the versions and the
780 <filename>SRCDATE</filename> definitions for applications that are configured here.
781 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
782 Although this file mainly inherits its configuration from Poky.
783 </para>
784 </section>
785
786 <section id='structure-meta-files'>
787 <title><filename>meta/files/</filename></title>
788
789 <para>
790 This directory contains common license files and several text files
791 used by the build system.
792 The text files contain minimal device information and
793 lists of files and directories with knows permissions.
794 </para>
795 </section>
796
797 <section id='structure-meta-lib'>
798 <title><filename>meta/lib/</filename></title>
799
800 <para>
801 This directory contains OpenEmbedded Python library code
802 used during the build process.
803 </para>
804 </section>
805
806 <section id='structure-meta-recipes-bsp'>
807 <title><filename>meta/recipes-bsp/</filename></title>
808
809 <para>
810 This directory contains anything linking to specific hardware or hardware
811 configuration information such as "u-boot" and "grub".
812 </para>
813 </section>
814
815 <section id='structure-meta-recipes-connectivity'>
816 <title><filename>meta/recipes-connectivity/</filename></title>
817
818 <para>
819 This directory contains libraries and applications related to communication with other devices.
820 </para>
821 </section>
822
823 <section id='structure-meta-recipes-core'>
824 <title><filename>meta/recipes-core/</filename></title>
825
826 <para>
827 This directory contains what is needed to build a basic working Linux image
828 including commonly used dependencies.
829 </para>
830 </section>
831
832 <section id='structure-meta-recipes-devtools'>
833 <title><filename>meta/recipes-devtools/</filename></title>
834
835 <para>
836 This directory contains tools that are primarily used by the build system.
837 The tools, however, can also be used on targets.
838 </para>
839 </section>
840
841 <section id='structure-meta-recipes-extended'>
842 <title><filename>meta/recipes-extended/</filename></title>
843
844 <para>
845 This directory contains non-essential applications that add features compared to the
846 alternatives in core.
847 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
848 compliance.
849 </para>
850 </section>
851
852 <section id='structure-meta-recipes-gnome'>
853 <title><filename>meta/recipes-gnome/</filename></title>
854
855 <para>
856 This directory contains all things related to the GTK+ application framework.
857 </para>
858 </section>
859
860 <section id='structure-meta-recipes-graphics'>
861 <title><filename>meta/recipes-graphics/</filename></title>
862
863 <para>
864 This directory contains X and other graphically related system libraries
865 </para>
866 </section>
867
868 <section id='structure-meta-recipes-kernel'>
869 <title><filename>meta/recipes-kernel/</filename></title>
870
871 <para>
872 This directory contains the kernel and generic applications and libraries that
873 have strong kernel dependencies.
874 </para>
875 </section>
876
877 <section id='structure-meta-recipes-lsb4'>
878 <title><filename>meta/recipes-lsb4/</filename></title>
879
880 <para>
881 This directory contains recipes specifically added to support
882 the Linux Standard Base (LSB) version 4.x.
883 </para>
884 </section>
885
886 <section id='structure-meta-recipes-multimedia'>
887 <title><filename>meta/recipes-multimedia/</filename></title>
888
889 <para>
890 This directory contains codecs and support utilities for audio, images and video.
891 </para>
892 </section>
893
894 <section id='structure-meta-recipes-qt'>
895 <title><filename>meta/recipes-qt/</filename></title>
896
897 <para>
898 This directory contains all things related to the Qt application framework.
899 </para>
900 </section>
901
902 <section id='structure-meta-recipes-rt'>
903 <title><filename>meta/recipes-rt/</filename></title>
904
905 <para>
906 This directory contains package and image recipes for using and testing
907 the <filename>PREEMPT_RT</filename> kernel.
908 </para>
909 </section>
910
911 <section id='structure-meta-recipes-sato'>
912 <title><filename>meta/recipes-sato/</filename></title>
913
914 <para>
915 This directory contains the Sato demo/reference UI/UX and its associated applications
916 and configuration data.
917 </para>
918 </section>
919
920 <section id='structure-meta-recipes-support'>
921 <title><filename>meta/recipes-support/</filename></title>
922
923 <para>
924 This directory contains recipes used by other recipes, but that are
925 not directly included in images (i.e. dependencies of other
926 recipes).
927 </para>
928 </section>
929
930 <section id='structure-meta-site'>
931 <title><filename>meta/site/</filename></title>
932
933 <para>
934 This directory contains a list of cached results for various architectures.
935 Because certain "autoconf" test results cannot be determined when cross-compiling due to
936 the tests not able to run on a live system, the information in this directory is
937 passed to "autoconf" for the various architectures.
938 </para>
939 </section>
940
941 <section id='structure-meta-recipes-txt'>
942 <title><filename>meta/recipes.txt</filename></title>
943
944 <para>
945 This file is a description of the contents of <filename>recipes-*</filename>.
946 </para>
947 </section>
948</section>
949
950</chapter>
951<!--
952vim: expandtab tw=80 ts=4
953-->
diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css
new file mode 100644
index 0000000000..e896a39d33
--- /dev/null
+++ b/documentation/ref-manual/ref-style.css
@@ -0,0 +1,979 @@
1/*
2 Generic XHTML / DocBook XHTML CSS Stylesheet.
3
4 Browser wrangling and typographic design by
5 Oyvind Kolas / pippin@gimp.org
6
7 Customised for Poky by
8 Matthew Allum / mallum@o-hand.com
9
10 Thanks to:
11 Liam R. E. Quin
12 William Skaggs
13 Jakub Steiner
14
15 Structure
16 ---------
17
18 The stylesheet is divided into the following sections:
19
20 Positioning
21 Margins, paddings, width, font-size, clearing.
22 Decorations
23 Borders, style
24 Colors
25 Colors
26 Graphics
27 Graphical backgrounds
28 Nasty IE tweaks
29 Workarounds needed to make it work in internet explorer,
30 currently makes the stylesheet non validating, but up until
31 this point it is validating.
32 Mozilla extensions
33 Transparency for footer
34 Rounded corners on boxes
35
36*/
37
38
39 /*************** /
40 / Positioning /
41/ ***************/
42
43body {
44 font-family: Verdana, Sans, sans-serif;
45
46 min-width: 640px;
47 width: 80%;
48 margin: 0em auto;
49 padding: 2em 5em 5em 5em;
50 color: #333;
51}
52
53h1,h2,h3,h4,h5,h6,h7 {
54 font-family: Arial, Sans;
55 color: #00557D;
56 clear: both;
57}
58
59h1 {
60 font-size: 2em;
61 text-align: left;
62 padding: 0em 0em 0em 0em;
63 margin: 2em 0em 0em 0em;
64}
65
66h2.subtitle {
67 margin: 0.10em 0em 3.0em 0em;
68 padding: 0em 0em 0em 0em;
69 font-size: 1.8em;
70 padding-left: 20%;
71 font-weight: normal;
72 font-style: italic;
73}
74
75h2 {
76 margin: 2em 0em 0.66em 0em;
77 padding: 0.5em 0em 0em 0em;
78 font-size: 1.5em;
79 font-weight: bold;
80}
81
82h3.subtitle {
83 margin: 0em 0em 1em 0em;
84 padding: 0em 0em 0em 0em;
85 font-size: 142.14%;
86 text-align: right;
87}
88
89h3 {
90 margin: 1em 0em 0.5em 0em;
91 padding: 1em 0em 0em 0em;
92 font-size: 140%;
93 font-weight: bold;
94}
95
96h4 {
97 margin: 1em 0em 0.5em 0em;
98 padding: 1em 0em 0em 0em;
99 font-size: 120%;
100 font-weight: bold;
101}
102
103h5 {
104 margin: 1em 0em 0.5em 0em;
105 padding: 1em 0em 0em 0em;
106 font-size: 110%;
107 font-weight: bold;
108}
109
110h6 {
111 margin: 1em 0em 0em 0em;
112 padding: 1em 0em 0em 0em;
113 font-size: 110%;
114 font-weight: bold;
115}
116
117.authorgroup {
118 background-color: transparent;
119 background-repeat: no-repeat;
120 padding-top: 256px;
121 background-image: url("figures/poky-title.png");
122 background-position: left top;
123 margin-top: -256px;
124 padding-right: 50px;
125 margin-left: 0px;
126 text-align: right;
127 width: 740px;
128}
129
130h3.author {
131 margin: 0em 0me 0em 0em;
132 padding: 0em 0em 0em 0em;
133 font-weight: normal;
134 font-size: 100%;
135 color: #333;
136 clear: both;
137}
138
139.author tt.email {
140 font-size: 66%;
141}
142
143.titlepage hr {
144 width: 0em;
145 clear: both;
146}
147
148.revhistory {
149 padding-top: 2em;
150 clear: both;
151}
152
153.toc,
154.list-of-tables,
155.list-of-examples,
156.list-of-figures {
157 padding: 1.33em 0em 2.5em 0em;
158 color: #00557D;
159}
160
161.toc p,
162.list-of-tables p,
163.list-of-figures p,
164.list-of-examples p {
165 padding: 0em 0em 0em 0em;
166 padding: 0em 0em 0.3em;
167 margin: 1.5em 0em 0em 0em;
168}
169
170.toc p b,
171.list-of-tables p b,
172.list-of-figures p b,
173.list-of-examples p b{
174 font-size: 100.0%;
175 font-weight: bold;
176}
177
178.toc dl,
179.list-of-tables dl,
180.list-of-figures dl,
181.list-of-examples dl {
182 margin: 0em 0em 0.5em 0em;
183 padding: 0em 0em 0em 0em;
184}
185
186.toc dt {
187 margin: 0em 0em 0em 0em;
188 padding: 0em 0em 0em 0em;
189}
190
191.toc dd {
192 margin: 0em 0em 0em 2.6em;
193 padding: 0em 0em 0em 0em;
194}
195
196div.glossary dl,
197div.variablelist dl {
198}
199
200.glossary dl dt,
201.variablelist dl dt,
202.variablelist dl dt span.term {
203 font-weight: normal;
204 width: 20em;
205 text-align: right;
206}
207
208.variablelist dl dt {
209 margin-top: 0.5em;
210}
211
212.glossary dl dd,
213.variablelist dl dd {
214 margin-top: -1em;
215 margin-left: 25.5em;
216}
217
218.glossary dd p,
219.variablelist dd p {
220 margin-top: 0em;
221 margin-bottom: 1em;
222}
223
224
225div.calloutlist table td {
226 padding: 0em 0em 0em 0em;
227 margin: 0em 0em 0em 0em;
228}
229
230div.calloutlist table td p {
231 margin-top: 0em;
232 margin-bottom: 1em;
233}
234
235div p.copyright {
236 text-align: left;
237}
238
239div.legalnotice p.legalnotice-title {
240 margin-bottom: 0em;
241}
242
243p {
244 line-height: 1.5em;
245 margin-top: 0em;
246
247}
248
249dl {
250 padding-top: 0em;
251}
252
253hr {
254 border: solid 1px;
255}
256
257
258.mediaobject,
259.mediaobjectco {
260 text-align: center;
261}
262
263img {
264 border: none;
265}
266
267ul {
268 padding: 0em 0em 0em 1.5em;
269}
270
271ul li {
272 padding: 0em 0em 0em 0em;
273}
274
275ul li p {
276 text-align: left;
277}
278
279table {
280 width :100%;
281}
282
283th {
284 padding: 0.25em;
285 text-align: left;
286 font-weight: normal;
287 vertical-align: top;
288}
289
290td {
291 padding: 0.25em;
292 vertical-align: top;
293}
294
295p a[id] {
296 margin: 0px;
297 padding: 0px;
298 display: inline;
299 background-image: none;
300}
301
302a {
303 text-decoration: underline;
304 color: #444;
305}
306
307pre {
308 overflow: auto;
309}
310
311a:hover {
312 text-decoration: underline;
313 /*font-weight: bold;*/
314}
315
316
317div.informalfigure,
318div.informalexample,
319div.informaltable,
320div.figure,
321div.table,
322div.example {
323 margin: 1em 0em;
324 padding: 1em;
325 page-break-inside: avoid;
326}
327
328
329div.informalfigure p.title b,
330div.informalexample p.title b,
331div.informaltable p.title b,
332div.figure p.title b,
333div.example p.title b,
334div.table p.title b{
335 padding-top: 0em;
336 margin-top: 0em;
337 font-size: 100%;
338 font-weight: normal;
339}
340
341.mediaobject .caption,
342.mediaobject .caption p {
343 text-align: center;
344 font-size: 80%;
345 padding-top: 0.5em;
346 padding-bottom: 0.5em;
347}
348
349.epigraph {
350 padding-left: 55%;
351 margin-bottom: 1em;
352}
353
354.epigraph p {
355 text-align: left;
356}
357
358.epigraph .quote {
359 font-style: italic;
360}
361.epigraph .attribution {
362 font-style: normal;
363 text-align: right;
364}
365
366span.application {
367 font-style: italic;
368}
369
370.programlisting {
371 font-family: monospace;
372 font-size: 80%;
373 white-space: pre;
374 margin: 1.33em 0em;
375 padding: 1.33em;
376}
377
378.tip,
379.warning,
380.caution,
381.note {
382 margin-top: 1em;
383 margin-bottom: 1em;
384
385}
386
387/* force full width of table within div */
388.tip table,
389.warning table,
390.caution table,
391.note table {
392 border: none;
393 width: 100%;
394}
395
396
397.tip table th,
398.warning table th,
399.caution table th,
400.note table th {
401 padding: 0.8em 0.0em 0.0em 0.0em;
402 margin : 0em 0em 0em 0em;
403}
404
405.tip p,
406.warning p,
407.caution p,
408.note p {
409 margin-top: 0.5em;
410 margin-bottom: 0.5em;
411 padding-right: 1em;
412 text-align: left;
413}
414
415.acronym {
416 text-transform: uppercase;
417}
418
419b.keycap,
420.keycap {
421 padding: 0.09em 0.3em;
422 margin: 0em;
423}
424
425.itemizedlist li {
426 clear: none;
427}
428
429.filename {
430 font-size: medium;
431 font-family: Courier, monospace;
432}
433
434
435div.navheader, div.heading{
436 position: absolute;
437 left: 0em;
438 top: 0em;
439 width: 100%;
440 background-color: #cdf;
441 width: 100%;
442}
443
444div.navfooter, div.footing{
445 position: fixed;
446 left: 0em;
447 bottom: 0em;
448 background-color: #eee;
449 width: 100%;
450}
451
452
453div.navheader td,
454div.navfooter td {
455 font-size: 66%;
456}
457
458div.navheader table th {
459 /*font-family: Georgia, Times, serif;*/
460 /*font-size: x-large;*/
461 font-size: 80%;
462}
463
464div.navheader table {
465 border-left: 0em;
466 border-right: 0em;
467 border-top: 0em;
468 width: 100%;
469}
470
471div.navfooter table {
472 border-left: 0em;
473 border-right: 0em;
474 border-bottom: 0em;
475 width: 100%;
476}
477
478div.navheader table td a,
479div.navfooter table td a {
480 color: #777;
481 text-decoration: none;
482}
483
484/* normal text in the footer */
485div.navfooter table td {
486 color: black;
487}
488
489div.navheader table td a:visited,
490div.navfooter table td a:visited {
491 color: #444;
492}
493
494
495/* links in header and footer */
496div.navheader table td a:hover,
497div.navfooter table td a:hover {
498 text-decoration: underline;
499 background-color: transparent;
500 color: #33a;
501}
502
503div.navheader hr,
504div.navfooter hr {
505 display: none;
506}
507
508
509.qandaset tr.question td p {
510 margin: 0em 0em 1em 0em;
511 padding: 0em 0em 0em 0em;
512}
513
514.qandaset tr.answer td p {
515 margin: 0em 0em 1em 0em;
516 padding: 0em 0em 0em 0em;
517}
518.answer td {
519 padding-bottom: 1.5em;
520}
521
522.emphasis {
523 font-weight: bold;
524}
525
526
527 /************* /
528 / decorations /
529/ *************/
530
531.titlepage {
532}
533
534.part .title {
535}
536
537.subtitle {
538 border: none;
539}
540
541/*
542h1 {
543 border: none;
544}
545
546h2 {
547 border-top: solid 0.2em;
548 border-bottom: solid 0.06em;
549}
550
551h3 {
552 border-top: 0em;
553 border-bottom: solid 0.06em;
554}
555
556h4 {
557 border: 0em;
558 border-bottom: solid 0.06em;
559}
560
561h5 {
562 border: 0em;
563}
564*/
565
566.programlisting {
567 border: solid 1px;
568}
569
570div.figure,
571div.table,
572div.informalfigure,
573div.informaltable,
574div.informalexample,
575div.example {
576 border: 1px solid;
577}
578
579
580
581.tip,
582.warning,
583.caution,
584.note {
585 border: 1px solid;
586}
587
588.tip table th,
589.warning table th,
590.caution table th,
591.note table th {
592 border-bottom: 1px solid;
593}
594
595.question td {
596 border-top: 1px solid black;
597}
598
599.answer {
600}
601
602
603b.keycap,
604.keycap {
605 border: 1px solid;
606}
607
608
609div.navheader, div.heading{
610 border-bottom: 1px solid;
611}
612
613
614div.navfooter, div.footing{
615 border-top: 1px solid;
616}
617
618 /********* /
619 / colors /
620/ *********/
621
622body {
623 color: #333;
624 background: white;
625}
626
627a {
628 background: transparent;
629}
630
631a:hover {
632 background-color: #dedede;
633}
634
635
636h1,
637h2,
638h3,
639h4,
640h5,
641h6,
642h7,
643h8 {
644 background-color: transparent;
645}
646
647hr {
648 border-color: #aaa;
649}
650
651
652.tip, .warning, .caution, .note {
653 border-color: #fff;
654}
655
656
657.tip table th,
658.warning table th,
659.caution table th,
660.note table th {
661 border-bottom-color: #fff;
662}
663
664
665.warning {
666 background-color: #f0f0f2;
667}
668
669.caution {
670 background-color: #f0f0f2;
671}
672
673.tip {
674 background-color: #f0f0f2;
675}
676
677.note {
678 background-color: #f0f0f2;
679}
680
681.glossary dl dt,
682.variablelist dl dt,
683.variablelist dl dt span.term {
684 color: #044;
685}
686
687div.figure,
688div.table,
689div.example,
690div.informalfigure,
691div.informaltable,
692div.informalexample {
693 border-color: #aaa;
694}
695
696pre.programlisting {
697 color: black;
698 background-color: #fff;
699 border-color: #aaa;
700 border-width: 2px;
701}
702
703.guimenu,
704.guilabel,
705.guimenuitem {
706 background-color: #eee;
707}
708
709
710b.keycap,
711.keycap {
712 background-color: #eee;
713 border-color: #999;
714}
715
716
717div.navheader {
718 border-color: black;
719}
720
721
722div.navfooter {
723 border-color: black;
724}
725
726
727 /*********** /
728 / graphics /
729/ ***********/
730
731/*
732body {
733 background-image: url("images/body_bg.jpg");
734 background-attachment: fixed;
735}
736
737.navheader,
738.note,
739.tip {
740 background-image: url("images/note_bg.jpg");
741 background-attachment: fixed;
742}
743
744.warning,
745.caution {
746 background-image: url("images/warning_bg.jpg");
747 background-attachment: fixed;
748}
749
750.figure,
751.informalfigure,
752.example,
753.informalexample,
754.table,
755.informaltable {
756 background-image: url("images/figure_bg.jpg");
757 background-attachment: fixed;
758}
759
760*/
761h1,
762h2,
763h3,
764h4,
765h5,
766h6,
767h7{
768}
769
770/*
771Example of how to stick an image as part of the title.
772
773div.article .titlepage .title
774{
775 background-image: url("figures/white-on-black.png");
776 background-position: center;
777 background-repeat: repeat-x;
778}
779*/
780
781div.preface .titlepage .title,
782div.colophon .title,
783div.chapter .titlepage .title,
784div.article .titlepage .title
785{
786}
787
788div.section div.section .titlepage .title,
789div.sect2 .titlepage .title {
790 background: none;
791}
792
793
794h1.title {
795 background-color: transparent;
796 background-image: url("figures/poky-title.png");
797 background-repeat: no-repeat;
798 height: 256px;
799 text-indent: -9000px;
800 overflow:hidden;
801}
802
803h2.subtitle {
804 background-color: transparent;
805 text-indent: -9000px;
806 overflow:hidden;
807 width: 0px;
808 display: none;
809}
810
811 /*************************************** /
812 / pippin.gimp.org specific alterations /
813/ ***************************************/
814
815/*
816div.heading, div.navheader {
817 color: #777;
818 font-size: 80%;
819 padding: 0;
820 margin: 0;
821 text-align: left;
822 position: absolute;
823 top: 0px;
824 left: 0px;
825 width: 100%;
826 height: 50px;
827 background: url('/gfx/heading_bg.png') transparent;
828 background-repeat: repeat-x;
829 background-attachment: fixed;
830 border: none;
831}
832
833div.heading a {
834 color: #444;
835}
836
837div.footing, div.navfooter {
838 border: none;
839 color: #ddd;
840 font-size: 80%;
841 text-align:right;
842
843 width: 100%;
844 padding-top: 10px;
845 position: absolute;
846 bottom: 0px;
847 left: 0px;
848
849 background: url('/gfx/footing_bg.png') transparent;
850}
851*/
852
853
854
855 /****************** /
856 / nasty ie tweaks /
857/ ******************/
858
859/*
860div.heading, div.navheader {
861 width:expression(document.body.clientWidth + "px");
862}
863
864div.footing, div.navfooter {
865 width:expression(document.body.clientWidth + "px");
866 margin-left:expression("-5em");
867}
868body {
869 padding:expression("4em 5em 0em 5em");
870}
871*/
872
873 /**************************************** /
874 / mozilla vendor specific css extensions /
875/ ****************************************/
876/*
877div.navfooter, div.footing{
878 -moz-opacity: 0.8em;
879}
880
881div.figure,
882div.table,
883div.informalfigure,
884div.informaltable,
885div.informalexample,
886div.example,
887.tip,
888.warning,
889.caution,
890.note {
891 -moz-border-radius: 0.5em;
892}
893
894b.keycap,
895.keycap {
896 -moz-border-radius: 0.3em;
897}
898*/
899
900table tr td table tr td {
901 display: none;
902}
903
904
905hr {
906 display: none;
907}
908
909table {
910 border: 0em;
911}
912
913 .photo {
914 float: right;
915 margin-left: 1.5em;
916 margin-bottom: 1.5em;
917 margin-top: 0em;
918 max-width: 17em;
919 border: 1px solid gray;
920 padding: 3px;
921 background: white;
922}
923 .seperator {
924 padding-top: 2em;
925 clear: both;
926 }
927
928 #validators {
929 margin-top: 5em;
930 text-align: right;
931 color: #777;
932 }
933 @media print {
934 body {
935 font-size: 8pt;
936 }
937 .noprint {
938 display: none;
939 }
940 }
941
942
943.tip,
944.note {
945 background: #f0f0f2;
946 color: #333;
947 padding: 20px;
948 margin: 20px;
949}
950
951.tip h3,
952.note h3 {
953 padding: 0em;
954 margin: 0em;
955 font-size: 2em;
956 font-weight: bold;
957 color: #333;
958}
959
960.tip a,
961.note a {
962 color: #333;
963 text-decoration: underline;
964}
965
966.footnote {
967 font-size: small;
968 color: #333;
969}
970
971/* Changes the announcement text */
972.tip h3,
973.warning h3,
974.caution h3,
975.note h3 {
976 font-size:large;
977 color: #00557D;
978}
979
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
new file mode 100644
index 0000000000..f3211f84ed
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,5888 @@
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<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ALLOW_EMPTY'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FILES'>F</link>
25<!-- <link linkend='var-glossary-g'>G</link> -->
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-IMAGE_BASENAME'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LAYERDEPENDS'>L</link>
31 <link linkend='var-MACHINE'>M</link>
32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_BINCONFIG_EXTRA_MANGLE'>O</link>
34 <link linkend='var-P'>P</link>
35<!-- <link linkend='var-glossary-q'>Q</link> -->
36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39 <link linkend='var-UBOOT_ENTRYPOINT'>U</link>
40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WARN_QA'>W</link>
42<!-- <link linkend='var-glossary-x'>X</link> -->
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
50 <glossdef>
51 <para>
52 Specifies if an output package should still be produced if it is empty.
53 By default, BitBake does not produce empty packages.
54 This default behavior can cause issues when there is an
55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
56 some other runtime hard-requirement on the existence of the package.
57 </para>
58
59 <para>
60 Like all package-controlling variables, you must always use them in
61 conjunction with a package name override.
62 Here is an example:
63 <literallayout class='monospaced'>
64 ALLOW_EMPTY_${PN} = "1"
65 </literallayout>
66 </para>
67 </glossdef>
68 </glossentry>
69
70 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
71 <glossdef>
72 <para>
73 Lists commands in a package that need an alternative
74 binary naming scheme.
75 Sometimes the same command is provided in multiple packages.
76 When this occurs, the OpenEmbedded build system needs to
77 use the alternatives system to create a different binary
78 naming scheme so the commands can co-exist.
79 </para>
80
81 <para>
82 To use the variable, list out the package's commands
83 that also exist as part of another package.
84 For example, if the <filename>busybox</filename> package
85 has four commands that also exist as part of another
86 package, you identify them as follows:
87 <literallayout class='monospaced'>
88 ALTERNATIVE_busybox = "sh sed test bracket"
89 </literallayout>
90 For more information on the alternatives system, see the
91 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
92 section.
93 </para>
94 </glossdef>
95 </glossentry>
96
97 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
98 <glossdef>
99 <para>
100 Used by the alternatives system to map duplicated commands
101 to actual locations.
102 For example, if the <filename>bracket</filename> command
103 provided by the <filename>busybox</filename> package is
104 duplicated through another package, you must use the
105 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
106 specify the actual location:
107 <literallayout class='monospaced'>
108 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
109 </literallayout>
110 In this example, the binary for the
111 <filename>bracket</filename> command (i.e.
112 <filename>[</filename>) from the
113 <filename>busybox</filename> package resides in
114 <filename>/usr/bin/</filename>.
115 <note>
116 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
117 defined, it defaults to
118 <filename>${bindir}/&lt;name&gt;</filename>.
119 </note>
120 </para>
121
122 <para>
123 For more information on the alternatives system, see the
124 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
125 section.
126 </para>
127 </glossdef>
128 </glossentry>
129
130 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
131 <glossdef>
132 <para>
133 Used by the alternatives system to create default
134 priorities for duplicated commands.
135 You can use the variable to create a single default
136 regardless of the command name or package, a default for
137 specific duplicated commands regardless of the package, or
138 a default for specific commands tied to particular packages.
139 Here are the available syntax forms:
140 <literallayout class='monospaced'>
141 ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
142 ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
143 ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
144 </literallayout>
145 </para>
146
147 <para>
148 For more information on the alternatives system, see the
149 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
150 section.
151 </para>
152 </glossdef>
153 </glossentry>
154
155 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
156 <glossdef>
157 <para>
158 Used by the alternatives system to create default link
159 locations for duplicated commands.
160 You can use the variable to create a single default
161 location for all duplicated commands regardless of the
162 command name or package, a default for
163 specific duplicated commands regardless of the package, or
164 a default for specific commands tied to particular packages.
165 Here are the available syntax forms:
166 <literallayout class='monospaced'>
167 ALTERNATIVE_TARGET = "&lt;target&gt;"
168 ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
169 ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
170 </literallayout>
171 <note>
172 <para>
173 If <filename>ALTERNATIVE_TARGET</filename> is not
174 defined, it inherits the value from the
175 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
176 variable.
177 </para>
178
179 <para>
180 If <filename>ALTERNATIVE_LINK_NAME</filename> and
181 <filename>ALTERNATIVE_TARGET</filename> are the
182 same, the target for
183 <filename>ALTERNATIVE_TARGET</filename>
184 has "<filename>.{BPN}</filename>" appended to it.
185 </para>
186
187 <para>
188 Finally, if the file referenced has not been
189 renamed, the alternatives system will rename it to
190 avoid the need to rename alternative files in the
191 <filename>do_install</filename> task while
192 retaining support for the command if necessary.
193 </para>
194 </note>
195 </para>
196
197 <para>
198 For more information on the alternatives system, see the
199 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
200 section.
201 </para>
202 </glossdef>
203 </glossentry>
204
205 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
206 <glossdef>
207 <para>The email address used to contact the original author
208 or authors in order to send patches and forward bugs.</para>
209 </glossdef>
210 </glossentry>
211
212 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
213 <glossdef>
214 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
215 is set to the value of this variable, it specifies to use the latest
216 source revision in the repository.
217 Here is an example:
218 <literallayout class='monospaced'>
219 SRCREV = "${AUTOREV}"
220 </literallayout>
221 </para>
222 </glossdef>
223 </glossentry>
224
225 </glossdiv>
226
227 <glossdiv id='var-glossary-b'><title>B</title>
228
229 <glossentry id='var-B'><glossterm>B</glossterm>
230 <glossdef>
231 <para>
232 The directory within the
233 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
234 in which the OpenEmbedded build system places generated
235 objects during a recipe's build process.
236 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
237 directory:
238 <literallayout class='monospaced'>
239 B = "${WORKDIR}/${BPN}/{PV}/"
240 </literallayout>
241 You can separate the (<filename>S</filename>) directory
242 and the directory pointed to by the <filename>B</filename>
243 variable.
244 Most Autotools-based recipes support separating these
245 directories.
246 The build system defaults to using separate directories for
247 <filename>gcc</filename> and some kernel recipes.
248 </para>
249 </glossdef>
250 </glossentry>
251
252 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
253 <glossdef>
254 <para>
255 Lists "recommended-only" packages to not install.
256 Recommended-only packages are packages installed only
257 through the
258 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
259 variable.
260 You can prevent any of these "recommended" packages from
261 being installed by listing them with the
262 <filename>BAD_RECOMMENDATIONS</filename> variable:
263 <literallayout class='monospaced'>
264 BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
265 </literallayout>
266 You can set this variable globally in your
267 <filename>local.conf</filename> file or you can attach it to
268 a specific image recipe by using the recipe name override:
269 <literallayout class='monospaced'>
270 BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
271 </literallayout>
272 </para>
273
274 <para>
275 It is important to realize that if you choose to not install
276 packages using this variable and some other packages are
277 dependent on them (i.e. listed in a recipe's
278 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
279 variable), the OpenEmbedded build system ignores your
280 request and will install the packages to avoid dependency
281 errors.
282 </para>
283
284 <para>
285 Support for this variable exists only when using the
286 IPK and RPM packaging backend.
287 Support does not exist for DEB.
288 </para>
289
290 <para>
291 See the
292 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
293 and the
294 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
295 variables for related information.
296 </para>
297 </glossdef>
298 </glossentry>
299
300 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
301 <glossdef>
302 <para>
303 Defines how BitBake handles situations where an append
304 file (<filename>.bbappend</filename>) has no
305 corresponding recipe file (<filename>.bb</filename>).
306 This condition often occurs when layers get out of sync
307 (e.g. <filename>oe-core</filename> bumps a
308 recipe version and the old recipe no longer exists and the
309 other layer has not been updated to the new version
310 of the recipe yet).
311 </para>
312
313 <para>
314 The default fatal behavior is safest because it is
315 the sane reaction given something is out of sync.
316 It is important to realize when your changes are no longer
317 being applied.
318 </para>
319
320 <para>
321 You can change the default behavior by setting this
322 variable to "1" in the <filename>local.conf</filename>
323 file in the
324 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
325 as follows:
326 <literallayout class='monospaced'>
327 BB_DANGLINGAPPENDS_WARNONLY = "1"
328 </literallayout>
329 </para>
330 </glossdef>
331 </glossentry>
332
333 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
334 <glossdef>
335 <para>
336 Monitors disk space and available inodes during the build
337 and allows you to control the build based on these
338 parameters.
339 </para>
340
341 <para>
342 Disk space monitoring is disabled by default.
343 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
344 variable to your <filename>conf/local.conf</filename> file found in the
345 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
346 Use the following form:
347 <literallayout class='monospaced'>
348 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
349
350 where:
351
352 &lt;action&gt; is:
353 ABORT: Immediately abort the build when
354 a threshold is broken.
355 STOPTASKS: Stop the build after the currently
356 executing tasks have finished when
357 a threshold is broken.
358 WARN: Issue a warning but continue the
359 build when a threshold is broken.
360 Subsequent warnings are issued as
361 defined by the
362 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
363 which must be defined in the
364 conf/local.conf file.
365
366 &lt;dir&gt; is:
367 Any directory you choose. You can specify one or
368 more directories to monitor by separating the
369 groupings with a space. If two directories are
370 on the same device, only the first directory
371 is monitored.
372
373 &lt;threshold&gt; is:
374 Either the minimum available disk space,
375 the minimum number of free inodes, or
376 both. You must specify at least one. To
377 omit one or the other, simply omit the value.
378 Specify the threshold using G, M, K for Gbytes,
379 Mbytes, and Kbytes, respectively. If you do
380 not specify G, M, or K, Kbytes is assumed by
381 default. Do not use GB, MB, or KB.
382 </literallayout>
383 </para>
384
385 <para>
386 Here are some examples:
387 <literallayout class='monospaced'>
388 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
389 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
390 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
391 </literallayout>
392 The first example works only if you also provide
393 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
394 in the <filename>conf/local.conf</filename>.
395 This example causes the build system to immediately
396 abort when either the disk space in <filename>${TMPDIR}</filename> drops
397 below 1 Gbyte or the available free inodes drops below
398 100 Kbytes.
399 Because two directories are provided with the variable, the
400 build system also issue a
401 warning when the disk space in the
402 <filename>${SSTATE_DIR}</filename> directory drops
403 below 1 Gbyte or the number of free inodes drops
404 below 100 Kbytes.
405 Subsequent warnings are issued during intervals as
406 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
407 variable.
408 </para>
409
410 <para>
411 The second example stops the build after all currently
412 executing tasks complete when the minimum disk space
413 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
414 directory drops below 1 Gbyte.
415 No disk monitoring occurs for the free inodes in this case.
416 </para>
417
418 <para>
419 The final example immediately aborts the build when the
420 number of free inodes in the <filename>${TMPDIR}</filename> directory
421 drops below 100 Kbytes.
422 No disk space monitoring for the directory itself occurs
423 in this case.
424 </para>
425 </glossdef>
426 </glossentry>
427
428 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
429 <glossdef>
430 <para>
431 Defines the disk space and free inode warning intervals.
432 To set these intervals, define the variable in your
433 <filename>conf/local.conf</filename> file in the
434 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
435 </para>
436
437 <para>
438 If you are going to use the
439 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
440 also use the
441 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
442 and define its action as "WARN".
443 During the build, subsequent warnings are issued each time
444 disk space or number of free inodes further reduces by
445 the respective interval.
446 </para>
447
448 <para>
449 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
450 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
451 the "WARN" action, the disk monitoring interval defaults to
452 the following:
453 <literallayout class='monospaced'>
454 BB_DISKMON_WARNINTERVAL = "50M,5K"
455 </literallayout>
456 </para>
457
458 <para>
459 When specifying the variable in your configuration file,
460 use the following form:
461 <literallayout class='monospaced'>
462 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
463
464 where:
465
466 &lt;disk_space_interval&gt; is:
467 An interval of memory expressed in either
468 G, M, or K for Gbytes, Mbytes, or Kbytes,
469 respectively. You cannot use GB, MB, or KB.
470
471 &lt;disk_inode_interval&gt; is:
472 An interval of free inodes expressed in either
473 G, M, or K for Gbytes, Mbytes, or Kbytes,
474 respectively. You cannot use GB, MB, or KB.
475 </literallayout>
476 </para>
477
478 <para>
479 Here is an example:
480 <literallayout class='monospaced'>
481 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
482 BB_DISKMON_WARNINTERVAL = "50M,5K"
483 </literallayout>
484 These variables cause the OpenEmbedded build system to
485 issue subsequent warnings each time the available
486 disk space further reduces by 50 Mbytes or the number
487 of free inodes further reduces by 5 Kbytes in the
488 <filename>${SSTATE_DIR}</filename> directory.
489 Subsequent warnings based on the interval occur each time
490 a respective interval is reached beyond the initial warning
491 (i.e. 1 Gbytes and 100 Kbytes).
492 </para>
493 </glossdef>
494 </glossentry>
495
496 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
497 <glossdef>
498 <para>
499 Causes tarballs of the Git repositories to be placed in the
500 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
501 directory.
502 For performance reasons, creating and placing tarballs of
503 the Git repositories is not the default action by the
504 OpenEmbedded build system.
505 <literallayout class='monospaced'>
506 BB_Generate_MIRROR_TARBALLS = "1"
507 </literallayout>
508 Set this variable in your <filename>local.conf</filename>
509 file in the
510 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
511 </para>
512 </glossdef>
513 </glossentry>
514
515 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
516 <glossdef>
517 <para>The maximum number of tasks BitBake should run in parallel at any one time.
518 If your host development system supports multiple cores a good rule of thumb
519 is to set this variable to twice the number of cores.</para>
520 </glossdef>
521 </glossentry>
522
523 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
524 <glossdef>
525 <para>
526 Allows you to extend a recipe so that it builds variants of the software.
527 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
528 which is a copy of Quilt built to run on the build system;
529 "crosses" such as <filename>gcc-cross</filename>,
530 which is a compiler built to run on the build machine but produces binaries
531 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
532 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
533 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
534 </para>
535
536 <para>
537 To build a different variant of the recipe with a minimal amount of code, it usually
538 is as simple as adding the following to your recipe:
539 <literallayout class='monospaced'>
540 BBCLASSEXTEND =+ "native nativesdk"
541 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
542 </literallayout>
543 </para>
544 </glossdef>
545 </glossentry>
546
547 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
548 <glossdef>
549 <para>Lists the names of configured layers.
550 These names are used to find the other <filename>BBFILE_*</filename>
551 variables.
552 Typically, each layer will append its name to this variable in its
553 <filename>conf/layer.conf</filename> file.
554 </para>
555 </glossdef>
556 </glossentry>
557
558 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
559 <glossdef>
560 <para>Variable that expands to match files from
561 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
562 in a particular layer.
563 This variable is used in the <filename>conf/layer.conf</filename> file and must
564 be suffixed with the name of the specific layer (e.g.
565 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
566 </glossdef>
567 </glossentry>
568
569 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
570 <glossdef>
571 <para>Assigns the priority for recipe files in each layer.</para>
572 <para>This variable is useful in situations where the same recipe appears in
573 more than one layer.
574 Setting this variable allows you to prioritize a
575 layer against other layers that contain the same recipe - effectively
576 letting you control the precedence for the multiple layers.
577 The precedence established through this variable stands regardless of a
578 recipe's version
579 (<link linkend='var-PV'><filename>PV</filename></link> variable).
580 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
581 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
582 lower precedence.</para>
583 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
584 precedence.
585 For example, the value 6 has a higher precedence than the value 5.
586 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
587 dependencies (see the
588 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
589 more information.
590 The default priority, if unspecified
591 for a layer with no dependencies, is the lowest defined priority + 1
592 (or 1 if no priorities are defined).</para>
593 <tip>
594 You can use the command <filename>bitbake-layers show_layers</filename> to list
595 all configured layers along with their priorities.
596 </tip>
597 </glossdef>
598 </glossentry>
599
600 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
601 <glossdef>
602 <para>List of recipe files used by BitBake to build software.</para>
603 </glossdef>
604 </glossentry>
605
606 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
607 <glossdef>
608 <para>Variable that controls how BitBake displays logs on build failure.</para>
609 </glossdef>
610 </glossentry>
611
612 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
613 <glossdef>
614 <para>Lists the layers to enable during the build.
615 This variable is defined in the <filename>bblayers.conf</filename> configuration
616 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
617 Here is an example:
618 <literallayout class='monospaced'>
619 BBLAYERS = " \
620 /home/scottrif/poky/meta \
621 /home/scottrif/poky/meta-yocto \
622 /home/scottrif/poky/meta-yocto-bsp \
623 /home/scottrif/poky/meta-mykernel \
624 "
625
626 BBLAYERS_NON_REMOVABLE ?= " \
627 /home/scottrif/poky/meta \
628 /home/scottrif/poky/meta-yocto \
629 "
630 </literallayout>
631 This example enables four layers, one of which is a custom, user-defined layer
632 named <filename>meta-mykernel</filename>.
633 </para>
634 </glossdef>
635 </glossentry>
636
637 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
638 <glossdef>
639Core layer for images cannot be removed
640 <para>Lists core layers that cannot be removed from the
641 <filename>bblayers.conf</filename> file.
642 In order for BitBake to build your image, your
643 <filename>bblayers.conf</filename> file must include the
644 <filename>meta</filename> and <filename>meta-yocto</filename>
645 core layers.
646 Here is an example that shows these two layers listed in
647 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
648 <literallayout class='monospaced'>
649 BBLAYERS = " \
650 /home/scottrif/poky/meta \
651 /home/scottrif/poky/meta-yocto \
652 /home/scottrif/poky/meta-yocto-bsp \
653 /home/scottrif/poky/meta-mykernel \
654 "
655
656 BBLAYERS_NON_REMOVABLE ?= " \
657 /home/scottrif/poky/meta \
658 /home/scottrif/poky/meta-yocto \
659 "
660 </literallayout>
661 </para>
662 </glossdef>
663 </glossentry>
664
665 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
666 <glossdef>
667 <para>
668 Prevents BitBake from processing recipes and recipe
669 append files.
670 Use the <filename>BBMASK</filename> variable from within the
671 <filename>conf/local.conf</filename> file found
672 in the
673 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
674 </para>
675
676 <para>
677 You can use the <filename>BBMASK</filename> variable
678 to "hide" these <filename>.bb</filename> and
679 <filename>.bbappend</filename> files.
680 BitBake ignores any recipe or recipe append files that
681 match the expression.
682 It is as if BitBake does not see them at all.
683 Consequently, matching files are not parsed or otherwise
684 used by BitBake.</para>
685 <para>
686 The value you provide is passed to Python's regular
687 expression compiler.
688 The expression is compared against the full paths to
689 the files.
690 For complete syntax information, see Python's
691 documentation at
692 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
693 </para>
694
695 <para>
696 The following example uses a complete regular expression
697 to tell BitBake to ignore all recipe and recipe append
698 files in the <filename>/meta-ti/recipes-misc/</filename>
699 directory:
700 <literallayout class='monospaced'>
701 BBMASK = "/meta-ti/recipes-misc/"
702 </literallayout>
703 If you want to mask out multiple directories or recipes,
704 use the vertical bar to separate the regular expression
705 fragments.
706 This next example masks out multiple directories and
707 individual recipes:
708 <literallayout class='monospaced'>
709 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
710 BBMASK .= "|.*meta-oe/recipes-support/"
711 BBMASK .= "|.*openldap"
712 BBMASK .= "|.*opencv"
713 BBMASK .= "|.*lzma"
714 </literallayout>
715 Notice how the vertical bar is used to append the fragments.
716 <note>
717 When specifying a directory name, use the trailing
718 slash character to ensure you match just that directory
719 name.
720 </note>
721 </para>
722 </glossdef>
723 </glossentry>
724
725 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
726 <glossdef>
727 <para>
728 Used by BitBake to locate
729 <filename>.bbclass</filename> and configuration files.
730 This variable is analogous to the
731 <filename>PATH</filename> variable.
732 <note>
733 If you run BitBake from a directory outside of the
734 <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
735 you must be sure to set
736 <filename>BBPATH</filename> to point to the
737 Build Directory.
738 Set the variable as you would any environment variable
739 and then run BitBake:
740 <literallayout class='monospaced'>
741 $ BBPATH = "&lt;build_directory&gt;"
742 $ export BBPATH
743 $ bitbake &lt;target&gt;
744 </literallayout>
745 </note>
746 </para>
747 </glossdef>
748 </glossentry>
749
750 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
751 <glossdef>
752 <para>
753 Points to the server that runs memory-resident BitBake.
754 This variable is set by the
755 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
756 setup script and should not be hand-edited.
757 The variable is only used when you employ memory-resident
758 BitBake.
759 The setup script exports the value as follows:
760 <literallayout class='monospaced'>
761 export BBSERVER=localhost:$port
762 </literallayout>
763 For more information on how the
764 <filename>BBSERVER</filename> is used, see the
765 <filename>oe-init-build-env-memres</filename> script, which
766 is located in the
767 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
768 </para>
769 </glossdef>
770 </glossentry>
771
772 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
773 <glossdef>
774 <para>
775 When inheriting <filename>binconfig.bbclass</filename>
776 from a recipe, this variable specifies a wildcard for
777 configuration scripts that need editing.
778 The scripts are edited to correct any paths that have been
779 set up during compilation so that they are correct for
780 use when installed into the sysroot and called by the
781 build processes of other recipes.
782 </para>
783
784 <para>
785 For more information on how this variable works, see
786 <filename>meta/classes/binconfig.bbclass</filename> in the
787 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
788 You can also find general information on the class in the
789 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
790 section.
791 </para>
792 </glossdef>
793 </glossentry>
794
795 <glossentry id='var-BP'><glossterm>BP</glossterm>
796 <glossdef>
797 <para>The base recipe name and version but without any special
798 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
799 and so forth).
800 <filename>BP</filename> is comprised of the following:
801 <literallayout class="monospaced">
802 ${BPN}-${PV}
803 </literallayout></para>
804 </glossdef>
805 </glossentry>
806
807 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
808 <glossdef>
809 <para>The bare name of the recipe.
810 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
811 but removes common suffixes such as "-native" and "-cross" as well
812 as removes common prefixes such as multilib's "lib64-" and "lib32-".
813 The exact list of suffixes removed is specified by the
814 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
815 The exact list of prefixes removed is specified by the
816 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
817 Prefixes are removed for <filename>multilib</filename>
818 and <filename>nativesdk</filename> cases.</para>
819 </glossdef>
820 </glossentry>
821
822 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
823 <glossdef>
824 <para>
825 Points to the location of the
826 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
827 You can define this directory indirectly through the
828 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
829 and
830 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
831 scripts by passing in a Build Directory path when you run
832 the scripts.
833 If you run the scripts and do not provide a Build Directory
834 path, the <filename>BUILDDIR</filename> defaults to
835 <filename>build</filename> in the current directory.
836 </para>
837 </glossdef>
838 </glossentry>
839
840 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
841 <glossdef>
842 <para>
843 For the BusyBox recipe, specifies whether to split the
844 output executable file into two parts: one for features
845 that require <filename>setuid root</filename>, and one for
846 the remaining features (i.e. those that do not require
847 <filename>setuid root</filename>).
848 </para>
849
850 <para>
851 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
852 defaults to "1", which results in a single output
853 executable file.
854 Set the variable to "0" to split the output file.
855 </para>
856 </glossdef>
857 </glossentry>
858
859 </glossdiv>
860
861 <glossdiv id='var-glossary-c'><title>C</title>
862
863 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
864 <glossdef>
865 <para>
866 Flags passed to the C compiler for the target system.
867 This variable evaluates to the same as
868 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
869 </para>
870 </glossdef>
871 </glossentry>
872
873 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
874 <glossdef>
875 <para>A set of features common between
876 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
877 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
878 See the glossary descriptions for these variables for more information.</para>
879 </glossdef>
880 </glossentry>
881
882 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
883 <glossdef>
884 <para>
885 Points to <filename>meta/files/common-licenses</filename>
886 in the
887 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
888 which is where generic license files reside.
889 </para>
890 </glossdef>
891 </glossentry>
892
893 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
894 <glossdef>
895 <para>A regular expression that resolves to one or more hosts
896 (when the recipe is native) or one or more targets (when
897 the recipe is non-native) with which a recipe is compatible.
898 The regular expression is matched against
899 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
900 You can use the variable to stop recipes from being built
901 for classes of systems with which the recipes are not
902 compatible.
903 Stopping these builds is particularly useful with kernels.
904 The variable also helps to increase parsing speed
905 since the build system skips parsing recipes not
906 compatible with the current system.</para>
907 </glossdef>
908 </glossentry>
909
910 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
911 <glossdef>
912 <para>A regular expression that resolves to one or more
913 target machines with which a recipe is compatible.
914 The regular expression is matched against
915 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
916 You can use the variable to stop recipes from being built
917 for machines with which the recipes are not compatible.
918 Stopping these builds is particularly useful with kernels.
919 The variable also helps to increase parsing speed
920 since the build system skips parsing recipes not
921 compatible with the current machine.</para>
922 </glossdef>
923 </glossentry>
924
925 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
926 <glossdef>
927 <para>
928 Defines wildcards to match when installing a list of
929 complementary packages for all the packages explicitly
930 (or implicitly) installed in an image.
931 The resulting list of complementary packages is associated
932 with an item that can be added to
933 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
934 An example usage of this is the "dev-pkgs" item that when
935 added to <filename>IMAGE_FEATURES</filename> will
936 install -dev packages (containing headers and other
937 development files) for every package in the image.
938 </para>
939
940 <para>
941 To add a new feature item pointing to a wildcard, use a
942 variable flag to specify the feature item name and
943 use the value to specify the wildcard.
944 Here is an example:
945 <literallayout class='monospaced'>
946 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
947 </literallayout>
948 </para>
949 </glossdef>
950 </glossentry>
951
952 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
953 <glossdef>
954 <para>
955 Identifies editable or configurable files that are part of a package.
956 If the Package Management System (PMS) is being used to update
957 packages on the target system, it is possible that
958 configuration files you have changed after the original installation
959 and that you now want to remain unchanged are overwritten.
960 In other words, editable files might exist in the package that you do not
961 want reset as part of the package update process.
962 You can use the <filename>CONFFILES</filename> variable to list the files in the
963 package that you wish to prevent the PMS from overwriting during this update process.
964 </para>
965
966 <para>
967 To use the <filename>CONFFILES</filename> variable, provide a package name
968 override that identifies the resulting package.
969 Then, provide a space-separated list of files.
970 Here is an example:
971 <literallayout class='monospaced'>
972 CONFFILES_${PN} += "${sysconfdir}/file1 \
973 ${sysconfdir}/file2 ${sysconfdir}/file3"
974 </literallayout>
975 </para>
976
977 <para>
978 A relationship exists between the <filename>CONFFILES</filename> and
979 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
980 The files listed within <filename>CONFFILES</filename> must be a subset of
981 the files listed within <filename>FILES</filename>.
982 Because the configuration files you provide with <filename>CONFFILES</filename>
983 are simply being identified so that the PMS will not overwrite them,
984 it makes sense that
985 the files must already be included as part of the package through the
986 <filename>FILES</filename> variable.
987 </para>
988
989 <note>
990 When specifying paths as part of the <filename>CONFFILES</filename> variable,
991 it is good practice to use appropriate path variables.
992 For example, <filename>${sysconfdir}</filename> rather than
993 <filename>/etc</filename> or <filename>${bindir}</filename> rather
994 than <filename>/usr/bin</filename>.
995 You can find a list of these variables at the top of the
996 <filename>/meta/conf/bitbake.conf</filename> file in the
997 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
998 </note>
999 </glossdef>
1000 </glossentry>
1001
1002 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
1003 <glossdef>
1004 <para>
1005 A list of files that contains <filename>autoconf</filename> test results relevant
1006 to the current build.
1007 This variable is used by the Autotools utilities when running
1008 <filename>configure</filename>.
1009 </para>
1010 </glossdef>
1011 </glossentry>
1012
1013 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
1014 <glossdef>
1015 <para>
1016 Specifies the list of packages to be added to the image.
1017 You should only set this variable in the
1018 <filename>local.conf</filename> configuration file found
1019 in the
1020 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1021 </para>
1022
1023 <para>
1024 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
1025 </para>
1026 </glossdef>
1027 </glossentry>
1028
1029 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
1030 <glossdef>
1031 <para>
1032 Specifies the parent directory of the OpenEmbedded
1033 Core Metadata layer (i.e. <filename>/meta</filename>).
1034 </para>
1035
1036 <para>
1037 It is an important distinction that
1038 <filename>COREBASE</filename> points to the parent of this
1039 layer and not the layer itself.
1040 Consider an example where you have cloned the Poky Git
1041 repository and retained the <filename>poky</filename>
1042 name for your local copy of the repository.
1043 In this case, <filename>COREBASE</filename> points to
1044 the <filename>poky</filename> folder because it is the
1045 parent directory of the <filename>poky/meta</filename>
1046 layer.
1047 </para>
1048 </glossdef>
1049 </glossentry>
1050
1051 </glossdiv>
1052
1053 <glossdiv id='var-glossary-d'><title>D</title>
1054
1055 <glossentry id='var-D'><glossterm>D</glossterm>
1056 <glossdef>
1057 <para>The destination directory.</para>
1058 </glossdef>
1059 </glossentry>
1060
1061 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
1062 <glossdef>
1063 <para>
1064 The date and time on which the current build started.
1065 The format is suitable for timestamps.
1066 </para>
1067 </glossdef>
1068 </glossentry>
1069
1070 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
1071 <glossdef>
1072 <para>
1073 Specifies to build packages with debugging information.
1074 This influences the value of the
1075 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
1076 variable.
1077 </para>
1078 </glossdef>
1079 </glossentry>
1080
1081 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
1082 <glossdef>
1083 <para>
1084 The options to pass in
1085 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1086 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
1087 a system for debugging.
1088 This variable defaults to "-O -fno-omit-frame-pointer -g".
1089 </para>
1090 </glossdef>
1091 </glossentry>
1092
1093 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1094 <glossdef>
1095 <para>
1096 Specifies a weak bias for recipe selection priority.
1097 </para>
1098 <para>
1099 The most common usage of this is variable is to set
1100 it to "-1" within a recipe for a development version of a
1101 piece of software.
1102 Using the variable in this way causes the stable version
1103 of the recipe to build by default in the absence of
1104 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1105 being used to build the development version.
1106 </para>
1107 <note>
1108 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1109 is weak and is overridden by
1110 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1111 if the that variable is different between two layers
1112 that contain different versions of the same recipe.
1113 </note>
1114 </glossdef>
1115 </glossentry>
1116
1117 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1118 <glossdef>
1119 <para>
1120 Lists a recipe's build-time dependencies
1121 (i.e. other recipe files).
1122 The system ensures that all the dependencies listed
1123 have been built and have their contents in the appropriate
1124 sysroots before the recipe's configure task is executed.
1125 </para>
1126
1127 <para>
1128 Consider this simple example for two recipes named "a" and
1129 "b" that produce similarly named packages.
1130 In this example, the <filename>DEPENDS</filename>
1131 statement appears in the "a" recipe:
1132 <literallayout class='monospaced'>
1133 DEPENDS = "b"
1134 </literallayout>
1135 Here, the dependency is such that the
1136 <filename>do_configure</filename> task for recipe "a"
1137 depends on the <filename>do_populate_sysroot</filename>
1138 task of recipe "b".
1139 This means anything that recipe "b" puts into sysroot
1140 is available when recipe "a" is configuring itself.
1141 </para>
1142
1143 <para>
1144 For information on runtime dependencies, see the
1145 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1146 variable.
1147 </para>
1148 </glossdef>
1149 </glossentry>
1150
1151 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
1152 <glossdef>
1153 <para>
1154 Points to the general area that the OpenEmbedded build
1155 system uses to place images, packages, SDKs and other output
1156 files that are ready to be used outside of the build system.
1157 By default, this directory resides within the
1158 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1159 as <filename>tmp/deploy</filename>.
1160 </para>
1161
1162 <para>
1163 For more information on the structure of the Build
1164 Directory, see
1165 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1166 section.
1167 For more detail on the contents of the
1168 <filename>deploy</filename> directory, see the
1169 "<link linkend='images-dev-environment'>Images</link>" and
1170 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1171 sections.
1172 </para>
1173 </glossdef>
1174 </glossentry>
1175
1176 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
1177 <glossdef>
1178 <para>
1179 Points to the area that the OpenEmbedded build system uses
1180 to place images and other associated output files that are
1181 ready to be deployed onto the target machine.
1182 The directory is machine-specific as it contains the
1183 <filename>${MACHINE}</filename> name.
1184 By default, this directory resides within the
1185 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1186 as <filename>tmp/deploy/images/${MACHINE}/</filename>.
1187 </para>
1188
1189 <para>
1190 For more information on the structure of the Build
1191 Directory, see
1192 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1193 section.
1194 For more detail on the contents of the
1195 <filename>deploy</filename> directory, see the
1196 "<link linkend='images-dev-environment'>Images</link>" and
1197 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1198 sections.
1199 </para>
1200 </glossdef>
1201 </glossentry>
1202
1203 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1204 <glossdef>
1205 <para>The package description used by package managers.
1206 If not set, <filename>DESCRIPTION</filename> takes
1207 the value of the
1208 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
1209 variable.
1210 </para>
1211 </glossdef>
1212 </glossentry>
1213
1214 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
1215 <glossdef>
1216 <para>
1217 The short name of the distribution.
1218 This variable corresponds to a file with the
1219 extension <filename>.conf</filename>
1220 located in a <filename>conf/distro</filename> directory
1221 within the
1222 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
1223 that contains the distribution configuration.
1224 The value must not contain spaces, and is typically all lower-case.
1225 </para>
1226 <para>
1227 If the variable is blank, a set of default configuration
1228 will be used, which is specified
1229 within <filename>meta/conf/distro/defaultsetup.conf</filename>.
1230 </para>
1231 </glossdef>
1232 </glossentry>
1233
1234 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
1235 <glossdef>
1236 <para>
1237 Specifies a list of distro-specific packages to add to all images.
1238 This variable takes affect through
1239 <filename>packagegroup-base</filename> so the
1240 variable only really applies to the more full-featured
1241 images that include <filename>packagegroup-base</filename>.
1242 You can use this variable to keep distro policy out of
1243 generic images.
1244 As with all other distro variables, you set this variable
1245 in the distro <filename>.conf</filename> file.
1246 </para>
1247 </glossdef>
1248 </glossentry>
1249
1250 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
1251 <glossdef>
1252 <para>
1253 Specifies a list of distro-specific packages to add to all images
1254 if the packages exist.
1255 The packages might not exist or be empty (e.g. kernel modules).
1256 The list of packages are automatically installed but you can
1257 remove them.
1258 </para>
1259 </glossdef>
1260 </glossentry>
1261
1262 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
1263 <glossdef>
1264 <para>The features enabled for the distribution.
1265 For a list of supported features that ship with the
1266 Yocto Project, see the
1267 "<link linkend='ref-features-distro'>Distro</link>"
1268 section.
1269 </para>
1270 </glossdef>
1271 </glossentry>
1272
1273 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
1274 <glossdef>
1275 <para>Features to be added to
1276 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
1277 if not also present in
1278 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1279 </para>
1280
1281 <para>
1282 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1283 It is not intended to be user-configurable.
1284 It is best to just reference the variable to see which distro features are
1285 being backfilled for all distro configurations.
1286 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1287 more information.
1288 </para>
1289 </glossdef>
1290 </glossentry>
1291
1292 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
1293 <glossdef>
1294 <para>Features from
1295 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
1296 that should not be backfilled (i.e. added to
1297 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
1298 during the build.
1299 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
1300 more information.
1301 </para>
1302 </glossdef>
1303 </glossentry>
1304
1305 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
1306 <glossdef>
1307 <para>The long name of the distribution.</para>
1308 </glossdef>
1309 </glossentry>
1310
1311 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
1312 <glossdef>
1313 <para>Alias names used for the recipe in various Linux distributions.</para>
1314 <para>See the
1315 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
1316 a Package Name Alias</ulink>" section in the Yocto Project Development
1317 Manual for more information.</para>
1318 </glossdef>
1319 </glossentry>
1320
1321 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
1322 <glossdef>
1323 <para>the version of the distribution.</para>
1324 </glossdef>
1325 </glossentry>
1326
1327 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
1328 <glossdef>
1329 <para>
1330 This variable lists overrides specific to the current
1331 distribution.
1332 By default, the variable list includes the value of the
1333 <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
1334 variable.
1335 You can extend the variable to apply any variable overrides
1336 you want as part of the distribution and are not
1337 already in <filename>OVERRIDES</filename> through
1338 some other means.
1339 </para>
1340 </glossdef>
1341 </glossentry>
1342
1343 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1344 <glossdef>
1345 <para>
1346 The central download directory used by the build process to
1347 store downloads.
1348 By default, <filename>DL_DIR</filename> gets files
1349 suitable for mirroring for everything except Git
1350 repositories.
1351 If you want tarballs of Git repositories, use the
1352 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1353 variable.
1354 </para>
1355
1356 <para>
1357 You can set this directory by defining the
1358 <filename>DL_DIR</filename> variable in the
1359 <filename>/conf/local.conf</filename> file.
1360 This directory is self-maintaining and you should not have
1361 to touch it.
1362 By default, the directory is <filename>downloads</filename>
1363 in the
1364 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1365 <literallayout class='monospaced'>
1366 #DL_DIR ?= "${TOPDIR}/downloads"
1367 </literallayout>
1368 To specify a different download directory, simply remove
1369 the comment from the line and provide your directory.
1370 </para>
1371
1372 <para>
1373 During a first build, the system downloads many different
1374 source code tarballs from various upstream projects.
1375 Downloading can take a while, particularly if your network
1376 connection is slow.
1377 Tarballs are all stored in the directory defined by
1378 <filename>DL_DIR</filename> and the build system looks there
1379 first to find source tarballs.
1380 <note>
1381 When wiping and rebuilding, you can preserve this
1382 directory to speed up this part of subsequent
1383 builds.
1384 </note>
1385 </para>
1386
1387 <para>
1388 You can safely share this directory between multiple builds
1389 on the same development machine.
1390 For additional information on how the build process gets
1391 source files when working behind a firewall or proxy server,
1392 see this specific question in the
1393 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
1394 chapter.
1395 </para>
1396 </glossdef>
1397
1398 </glossentry>
1399 </glossdiv>
1400
1401 <glossdiv id='var-glossary-e'><title>E</title>
1402
1403 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
1404 <glossdef>
1405 <para></para>
1406 <para>Variable that controls which locales for
1407 <filename>eglibc</filename> are generated during the
1408 build (useful if the target device has 64Mbytes
1409 of RAM or less).</para>
1410 </glossdef>
1411 </glossentry>
1412
1413 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
1414 <glossdef>
1415 <para>
1416 Specifies the quality assurance checks whose failures are
1417 reported as errors by the OpenEmbedded build system.
1418 You set this variable in your distribution configuration
1419 file.
1420 For a list of the checks you can control with this variable,
1421 see the
1422 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1423 section.
1424 </para>
1425 </glossdef>
1426 </glossentry>
1427
1428 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1429 <glossdef>
1430 <para>
1431 Directs BitBake to exclude a recipe from world builds (i.e.
1432 <filename>bitbake world</filename>).
1433 During world builds, BitBake locates, parses and builds all
1434 recipes found in every layer exposed in the
1435 <filename>bblayers.conf</filename> configuration file.
1436 </para>
1437
1438 <para>
1439 To exclude a recipe from a world build using this variable,
1440 set the variable to "1" in the recipe.
1441 </para>
1442
1443 <note>
1444 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1445 may still be built during a world build in order to satisfy
1446 dependencies of other recipes.
1447 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1448 only ensures that the recipe is not explicitly added
1449 to the list of build targets in a world build.
1450 </note>
1451 </glossdef>
1452 </glossentry>
1453
1454 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
1455 <glossdef>
1456 <para>
1457 Used with file and pathnames to create a prefix for a recipe's
1458 version based on the recipe's
1459 <link linkend='var-PE'><filename>PE</filename></link> value.
1460 If <filename>PE</filename> is set and greater than zero for a recipe,
1461 <filename>EXTENDPE</filename> becomes that value (e.g if
1462 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
1463 becomes "1_").
1464 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
1465 zero, <filename>EXTENDPE</filename> becomes "".</para>
1466 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
1467 variable for an example.
1468 </para>
1469 </glossdef>
1470 </glossentry>
1471
1472 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
1473 <glossdef>
1474 <para>
1475 The full package version specification as it appears on the
1476 final packages produced by a recipe.
1477 The variable's value is normally used to fix a runtime
1478 dependency to the exact same version of another package
1479 in the same recipe:
1480 <literallayout class='monospaced'>
1481 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
1482 </literallayout>
1483 </para>
1484
1485 <para>
1486 The dependency relationships are intended to force the
1487 package manager to upgrade these types of packages in
1488 lock-step.
1489 </para>
1490 </glossdef>
1491 </glossentry>
1492
1493 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
1494 <glossdef>
1495 <para>
1496 If <filename>externalsrc.bbclass</filename> is inherited,
1497 this variable points to the source tree, which is
1498 outside of the OpenEmbedded build system.
1499 When set, this variable sets the
1500 <link linkend='var-S'><filename>S</filename></link>
1501 variable, which is what the OpenEmbedded build system uses
1502 to locate unpacked recipe source code.
1503 </para>
1504
1505 <para>
1506 For more information on
1507 <filename>externalsrc.bbclass</filename>, see the
1508 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
1509 section.
1510 You can also find information on how to use this variable
1511 in the
1512 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
1513 section in the Yocto Project Development Manual.
1514 </para>
1515 </glossdef>
1516 </glossentry>
1517
1518 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
1519 <glossdef>
1520 <para>
1521 If <filename>externalsrc.bbclass</filename> is inherited,
1522 this variable points to the directory in which the recipe's
1523 source code is built,
1524 which is outside of the OpenEmbedded build system.
1525 When set, this variable sets the
1526 <link linkend='var-B'><filename>B</filename></link>
1527 variable, which is what the OpenEmbedded build system uses
1528 to locate the Build Directory.
1529 </para>
1530
1531 <para>
1532 For more information on
1533 <filename>externalsrc.bbclass</filename>, see the
1534 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
1535 section.
1536 You can also find information on how to use this variable
1537 in the
1538 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
1539 section in the Yocto Project Development Manual.
1540 </para>
1541 </glossdef>
1542 </glossentry>
1543
1544 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
1545 <glossdef>
1546 <para>
1547 The list of additional features to include in an image.
1548 Typically, you configure this variable in your
1549 <filename>local.conf</filename> file, which is found in the
1550 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1551 Although you can use this variable from within a recipe,
1552 best practices dictate that you do not.
1553 <note>
1554 To enable primary features from within the image
1555 recipe, use the
1556 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
1557 variable.
1558 </note>
1559 </para>
1560
1561 <para>
1562 Here are some examples of features you can add:
1563 <literallayout class='monospaced'>
1564"dbg-pkgs" - Adds -dbg packages for all installed packages
1565 including symbol information for debugging and
1566 profiling.
1567
1568"debug-tweaks" - Makes an image suitable for development.
1569 For example, ssh root access has a blank
1570 password. You should remove this feature
1571 before you produce a production image.
1572
1573"dev-pkgs" - Adds -dev packages for all installed packages.
1574 This is useful if you want to develop against
1575 the libraries in the image.
1576
1577"read-only-rootfs" - Creates an image whose root
1578 filesystem is read-only. See the
1579 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
1580 section in the Yocto Project
1581 Development Manual for more
1582 information
1583
1584"tools-debug" - Adds debugging tools such as gdb and
1585 strace.
1586
1587"tools-profile" - Adds profiling tools such as oprofile,
1588 exmap, lttng and valgrind (x86 only).
1589
1590"tools-sdk" - Adds development tools such as gcc, make,
1591 pkgconfig and so forth.
1592
1593"tools-testapps" - Adds useful testing tools such as
1594 ts_print, aplay, arecord and so
1595 forth.
1596
1597 </literallayout>
1598 </para>
1599
1600 <para>
1601 For a complete list of image features that ships with the
1602 Yocto Project, see the
1603 "<link linkend="ref-features-image">Images</link>"
1604 section.
1605 </para>
1606
1607 <para>
1608 For an example that shows how to customize your image by
1609 using this variable, see the
1610 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
1611 section in the Yocto Project Development Manual.
1612 </para>
1613 </glossdef>
1614 </glossentry>
1615
1616 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
1617 <glossdef>
1618 <para>A list of recipes to build that do not provide packages
1619 for installing into the root filesystem.
1620 </para>
1621 <para>Sometimes a recipe is required to build the final image but is not
1622 needed in the root filesystem.
1623 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
1624 list these recipes and thus, specify the dependencies.
1625 A typical example is a required bootloader in a machine configuration.
1626 </para>
1627 <note>
1628 To add packages to the root filesystem, see the various
1629 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
1630 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
1631 variables.
1632 </note>
1633 </glossdef>
1634 </glossentry>
1635
1636 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
1637 <glossdef>
1638 <para>Additional <filename>cmake</filename> options.</para>
1639 </glossdef>
1640 </glossentry>
1641
1642 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
1643 <glossdef>
1644 <para>Additional <filename>configure</filename> script options.</para>
1645 </glossdef>
1646 </glossentry>
1647
1648 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
1649 <glossdef>
1650 <para>Additional GNU <filename>make</filename> options.</para>
1651 </glossdef>
1652 </glossentry>
1653
1654 </glossdiv>
1655
1656 <glossdiv id='var-glossary-f'><title>F</title>
1657
1658 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
1659 <glossdef>
1660 <para>
1661 The list of directories or files that are placed in packages.
1662 </para>
1663
1664 <para>
1665 To use the <filename>FILES</filename> variable, provide a package name
1666 override that identifies the resulting package.
1667 Then, provide a space-separated list of files or paths that identifies the
1668 files you want included as part of the resulting package.
1669 Here is an example:
1670 <literallayout class='monospaced'>
1671 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
1672 </literallayout>
1673 </para>
1674
1675 <note>
1676 When specifying paths as part of the <filename>FILES</filename> variable,
1677 it is good practice to use appropriate path variables.
1678 For example, <filename>${sysconfdir}</filename> rather than
1679 <filename>/etc</filename> or <filename>${bindir}</filename> rather
1680 than <filename>/usr/bin</filename>.
1681 You can find a list of these variables at the top of the
1682 <filename>/meta/conf/bitbake.conf</filename> file in the
1683 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1684 </note>
1685
1686 <para>
1687 If some of the files you provide with the <filename>FILES</filename> variable
1688 are editable and you know they should not be
1689 overwritten during the package update process by the Package Management
1690 System (PMS), you can identify these files so that the PMS will not
1691 overwrite them.
1692 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
1693 variable for information on how to identify these files to the PMS.
1694 </para>
1695
1696 </glossdef>
1697 </glossentry>
1698
1699 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
1700 <glossdef>
1701 <para>
1702 Extends the search path the OpenEmbedded build system uses
1703 when looking for files and patches as it processes recipes
1704 and append files.
1705 The default directories BitBake uses when it processes
1706 recipes are initially defined by the
1707 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
1708 variable.
1709 You can extend <filename>FILESPATH</filename> variable
1710 by using <filename>FILESEXTRAPATHS</filename>.
1711 </para>
1712
1713 <para>
1714 Best practices dictate that you accomplish this by using
1715 <filename>FILESEXTRAPATHS</filename> from within a
1716 <filename>.bbappend</filename> file and that you prepend
1717 paths as follows:
1718 <literallayout class='monospaced'>
1719 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1720 </literallayout>
1721 In the above example, the build system first looks for files
1722 in a directory that has the same name as the corresponding
1723 append file.
1724 <note>
1725 <para>When extending <filename>FILESEXTRAPATHS</filename>,
1726 be sure to use the immediate expansion
1727 (<filename>:=</filename>) operator.
1728 Immediate expansion makes sure that BitBake evaluates
1729 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
1730 at the time the directive is encountered rather than at
1731 some later time when expansion might result in a
1732 directory that does not contain the files you need.
1733 </para>
1734 <para>Also, include the trailing separating colon
1735 character if you are prepending.
1736 The trailing colon character is necessary because you
1737 are directing BitBake to extend the path by prepending
1738 directories to the search path.</para>
1739 </note>
1740 Here is another common use:
1741 <literallayout class='monospaced'>
1742 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1743 </literallayout>
1744 In this example, the build system extends the
1745 <filename>FILESPATH</filename> variable to include a
1746 directory named <filename>files</filename> that is in the
1747 same directory as the corresponding append file.
1748 </para>
1749
1750 <para>
1751 Here is a final example that specifically adds three paths:
1752 <literallayout class='monospaced'>
1753 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
1754 </literallayout>
1755 </para>
1756
1757 <para>
1758 By prepending paths in <filename>.bbappend</filename>
1759 files, you allow multiple append files that reside in
1760 different layers but are used for the same recipe to
1761 correctly extend the path.
1762 </para>
1763 </glossdef>
1764 </glossentry>
1765
1766 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
1767 <glossdef>
1768 <para>
1769 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1770 used by the OpenEmbedded build system for creating
1771 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
1772 You can find more information on how overrides are handled
1773 in the BitBake Manual that is located at
1774 <filename>bitbake/doc/manual</filename> in the
1775 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1776 </para>
1777
1778 <para>
1779 By default, the <filename>FILESOVERRIDES</filename>
1780 variable is defined as:
1781 <literallayout class='monospaced'>
1782 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
1783 </literallayout>
1784
1785 <note>
1786 Do not hand-edit the <filename>FILESOVERRIDES</filename>
1787 variable.
1788 The values match up with expected overrides and are
1789 used in an expected manner by the build system.
1790 </note>
1791 </para>
1792 </glossdef>
1793 </glossentry>
1794
1795 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1796 <glossdef>
1797 <para>
1798 The default set of directories the OpenEmbedded build system
1799 uses when searching for patches and files.
1800 During the build process, BitBake searches each directory in
1801 <filename>FILESPATH</filename> in the specified order when
1802 looking for files and patches specified by each
1803 <filename>file://</filename> URI in a recipe.
1804 </para>
1805
1806 <para>
1807 The default value for the <filename>FILESPATH</filename>
1808 variable is defined in the <filename>base.bbclass</filename>
1809 class found in <filename>meta/classes</filename> in the
1810 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
1811 <literallayout class='monospaced'>
1812 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
1813 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
1814 </literallayout>
1815 <note>
1816 Do not hand-edit the <filename>FILESPATH</filename>
1817 variable.
1818 If you want the build system to look in directories
1819 other than the defaults, extend the
1820 <filename>FILESPATH</filename> variable by using the
1821 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
1822 variable.
1823 </note>
1824 Be aware that the default <filename>FILESPATH</filename>
1825 directories do not map to directories in custom layers
1826 where append files (<filename>.bbappend</filename>)
1827 are used.
1828 If you want the build system to find patches or files
1829 that reside with your append files, you need to extend
1830 the <filename>FILESPATH</filename> variable by using
1831 the
1832 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
1833 variable.
1834 </para>
1835 </glossdef>
1836 </glossentry>
1837
1838 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
1839 <glossdef>
1840 <para>Allows you to define your own file permissions settings table as part of
1841 your configuration for the packaging process.
1842 For example, suppose you need a consistent set of custom permissions for
1843 a set of groups and users across an entire work project.
1844 It is best to do this in the packages themselves but this is not always
1845 possible.
1846 </para>
1847 <para>
1848 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
1849 is located in the <filename>meta/files</filename> folder in the
1850 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1851 If you create your own file permissions setting table, you should place it in your
1852 layer or the distros layer.
1853 </para>
1854 <para>
1855 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
1856 <filename>conf/local.conf</filename> file, which is found in the
1857 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
1858 point to your custom <filename>fs-perms.txt</filename>.
1859 You can specify more than a single file permissions setting table.
1860 The paths you specify to these files must be defined within the
1861 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
1862 </para>
1863 <para>
1864 For guidance on how to create your own file permissions settings table file,
1865 examine the existing <filename>fs-perms.txt</filename>.
1866 </para>
1867 </glossdef>
1868 </glossentry>
1869
1870 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
1871 <glossdef>
1872 <para>
1873 The options to pass in
1874 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1875 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
1876 when compiling an optimized system.
1877 This variable defaults to
1878 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
1879 </para>
1880 </glossdef>
1881 </glossentry>
1882
1883 </glossdiv>
1884
1885<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
1886<!-- </glossdiv>-->
1887
1888 <glossdiv id='var-glossary-h'><title>H</title>
1889
1890 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1891 <glossdef>
1892 <para>Website where more information about the software the recipe is building
1893 can be found.</para>
1894 </glossdef>
1895 </glossentry>
1896
1897 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
1898 <glossdef>
1899 <para>
1900 Specifies the system, including the architecture and the
1901 operating system, for with the build is occurring
1902 in the context of the current
1903 recipe.
1904 The OpenEmbedded build system automatically sets this
1905 variable.
1906 You do not need to set the variable yourself.
1907 </para>
1908
1909 <para>
1910 Here are two examples:
1911 <itemizedlist>
1912 <listitem><para>Given a native recipe on a 32-bit
1913 x86 machine running Linux, the value is
1914 "i686-linux".
1915 </para></listitem>
1916 <listitem><para>Given a recipe being built for a
1917 little-endian MIPS target running Linux,
1918 the value might be "mipsel-linux".
1919 </para></listitem>
1920 </itemizedlist>
1921 </para>
1922 </glossdef>
1923 </glossentry>
1924
1925 </glossdiv>
1926
1927 <glossdiv id='var-glossary-i'><title>I</title>
1928
1929 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
1930 <glossdef>
1931 <para>
1932 The base name of image output files.
1933 This variable defaults to the recipe name
1934 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
1935 </para>
1936 </glossdef>
1937 </glossentry>
1938
1939 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
1940 <glossdef>
1941 <para>
1942 A list of classes that all images should inherit.
1943 You typically use this variable to specify the list of
1944 classes that register the different types of images
1945 the OpenEmbedded build system creates.
1946 </para>
1947
1948 <para>
1949 The default value for <filename>IMAGE_CLASSES</filename> is
1950 <filename>image_types</filename>.
1951 You can set this variable in your
1952 <filename>local.conf</filename> or in a distribution
1953 configuration file.
1954 </para>
1955
1956 <para>
1957 For more information, see
1958 <filename>meta/classes/image_types.bbclass</filename> in the
1959 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1960 </para>
1961 </glossdef>
1962 </glossentry>
1963
1964 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
1965 <glossdef>
1966 <para>
1967 The primary list of features to include in an image.
1968 Typically, you configure this variable in an image recipe.
1969 Although you can use this variable from your
1970 <filename>local.conf</filename> file, which is found in the
1971 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
1972 best practices dictate that you do not.
1973 <note>
1974 To enable extra features from outside the image recipe,
1975 use the
1976 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
1977 </note>
1978 For a list of image features that ships with the Yocto
1979 Project, see the
1980 "<link linkend="ref-features-image">Images</link>"
1981 section.
1982 </para>
1983
1984 <para>
1985 For example that shows how to customize your image by
1986 using this variable, see the
1987 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
1988 section in the Yocto Project Development Manual.
1989 </para>
1990 </glossdef>
1991 </glossentry>
1992
1993 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
1994 <glossdef>
1995 <para>
1996 Specifies the formats the OpenEmbedded build system uses
1997 during the build when creating the root filesystem.
1998 For example, setting <filename>IMAGE_FSTYPES</filename>
1999 as follows causes the build system to create root
2000 filesystems using two formats: <filename>.ext3</filename>
2001 and <filename>tar.bz2</filename>:
2002 <literallayout class='monospaced'>
2003 IMAGE_FSTYPES = "ext3 tar.bz2"
2004 </literallayout>
2005 For the complete list of supported image formats from which
2006 you can choose, see
2007 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
2008 </para>
2009 </glossdef>
2010 </glossentry>
2011
2012 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
2013 <glossdef>
2014 <para>
2015 Specifies the packages to install into an image.
2016 The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
2017 recipe and you should use it with care to avoid ordering issues.
2018 </para>
2019
2020 <para>
2021 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
2022 packages to install into an image through <filename>image.bbclass</filename>.
2023 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
2024 that can take
2025 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
2026 and turn these into auto-generated entries in
2027 <filename>IMAGE_INSTALL</filename> in addition to its default contents.
2028 </para>
2029
2030 <para>
2031 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
2032 operator from the <filename>/conf/local.conf</filename> file or from within
2033 an image recipe is not recommended as it can cause ordering issues.
2034 Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
2035 to a default value using the <filename>?=</filename> operator, using a
2036 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
2037 will result in unexpected behavior when used in
2038 <filename>/conf/local.conf</filename>.
2039 Furthermore, the same operation from with an image recipe may or may not
2040 succeed depending on the specific situation.
2041 In both these cases, the behavior is contrary to how most users expect
2042 the <filename>+=</filename> operator to work.
2043 </para>
2044
2045 <para>
2046 When you use this variable, it is best to use it as follows:
2047 <literallayout class='monospaced'>
2048 IMAGE_INSTALL_append = " package-name"
2049 </literallayout>
2050 Be sure to include the space between the quotation character and the start of the
2051 package name.
2052 </para>
2053 </glossdef>
2054 </glossentry>
2055
2056 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
2057 <glossdef>
2058 <para>
2059 Specifies the list of locales to install into the image
2060 during the root filesystem construction process.
2061 The OpenEmbedded build system automatically splits locale
2062 files, which are used for localization, into separate
2063 packages.
2064 Setting the <filename>IMAGE_LINGUAS</filename> variable
2065 ensures that any locale packages that correspond to packages
2066 already selected for installation into the image are also
2067 installed.
2068 Here is an example:
2069 <literallayout class='monospaced'>
2070 IMAGE_LINGUAS = "pt-br de-de"
2071 </literallayout>
2072 In this example, the build system ensures any Brazilian
2073 Portuguese and German locale files that correspond to
2074 packages in the image are installed (i.e.
2075 <filename>*-locale-pt-br</filename>
2076 and <filename>*-locale-de-de</filename> as well as
2077 <filename>*-locale-pt</filename>
2078 and <filename>*-locale-de</filename>, since some software
2079 packages only provide locale files by language and not by
2080 country-specific language).
2081 </para>
2082 </glossdef>
2083 </glossentry>
2084
2085 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
2086 <glossdef>
2087 <para>
2088 The name of the output image files minus the extension.
2089 This variable is derived using the
2090 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
2091 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
2092 and
2093 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
2094 variables:
2095 <literallayout class='monospaced'>
2096 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
2097 </literallayout>
2098 </para>
2099 </glossdef>
2100 </glossentry>
2101
2102 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
2103 <glossdef>
2104 <para>
2105 Defines a multiplier that the build system applies to the initial image
2106 size for cases when the multiplier times the returned disk usage value
2107 for the image is greater than the sum of
2108 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
2109 and
2110 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
2111 The result of the multiplier applied to the initial image size creates
2112 free disk space in the image as overhead.
2113 By default, the build process uses a multiplier of 1.3 for this variable.
2114 This default value results in 30% free disk space added to the image when this
2115 method is used to determine the final generated image size.
2116 You should be aware that post install scripts and the package management
2117 system uses disk space inside this overhead area.
2118 Consequently, the multiplier does not produce an image with
2119 all the theoretical free disk space.
2120 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
2121 for information on how the build system determines the overall image size.
2122 </para>
2123
2124 <para>
2125 The default 30% free disk space typically gives the image enough room to boot
2126 and allows for basic post installs while still leaving a small amount of
2127 free disk space.
2128 If 30% free space is inadequate, you can increase the default value.
2129 For example, the following setting gives you 50% free space added to the image:
2130 <literallayout class='monospaced'>
2131 IMAGE_OVERHEAD_FACTOR = "1.5"
2132 </literallayout>
2133 </para>
2134
2135 <para>
2136 Alternatively, you can ensure a specific amount of free disk space is added
2137 to the image by using
2138 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
2139 the variable.
2140 </para>
2141 </glossdef>
2142 </glossentry>
2143
2144 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
2145 <glossdef>
2146 <para>
2147 Added by classes to run post processing commands once the
2148 OpenEmbedded build system has created the image.
2149 You can specify shell commands separated by semicolons:
2150 <literallayout class='monospaced'>
2151 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
2152 </literallayout>
2153 If you need to pass the path to the root filesystem within
2154 the command, you can use
2155 <filename>${IMAGE_ROOTFS}</filename>, which points to
2156 the root filesystem image.
2157 </para>
2158 </glossdef>
2159 </glossentry>
2160
2161 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
2162 <glossdef>
2163 <para>
2164 The location of the root filesystem while it is under
2165 construction (i.e. during <filename>do_rootfs</filename>).
2166 This variable is not configurable.
2167 Do not change it.
2168 </para>
2169 </glossdef>
2170 </glossentry>
2171
2172 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
2173 <glossdef>
2174 <para>
2175 Defines additional free disk space created in the image in Kbytes.
2176 By default, this variable is set to "0".
2177 This free disk space is added to the image after the build system determines
2178 the image size as described in
2179 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
2180 </para>
2181
2182 <para>
2183 This variable is particularly useful when you want to ensure that a
2184 specific amount of free disk space is available on a device after an image
2185 is installed and running.
2186 For example, to be sure 5 Gbytes of free disk space is available, set the
2187 variable as follows:
2188 <literallayout class='monospaced'>
2189 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
2190 </literallayout>
2191 </para>
2192 </glossdef>
2193 </glossentry>
2194
2195 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
2196 <glossdef>
2197 <para>
2198 Defines the size in Kbytes for the generated image.
2199 The OpenEmbedded build system determines the final size for the generated
2200 image using an algorithm that takes into account the initial disk space used
2201 for the generated image, a requested size for the image, and requested
2202 additional free disk space to be added to the image.
2203 Programatically, the build system determines the final size of the
2204 generated image as follows:
2205 <literallayout class='monospaced'>
2206 if (image-du * overhead) &lt; rootfs-size:
2207 internal-rootfs-size = rootfs-size + xspace
2208 else:
2209 internal-rootfs-size = (image-du * overhead) + xspace
2210
2211 where:
2212
2213 image-du = Returned value of the du command on
2214 the image.
2215
2216 overhead = IMAGE_OVERHEAD_FACTOR
2217
2218 rootfs-size = IMAGE_ROOTFS_SIZE
2219
2220 internal-rootfs-size = Initial root filesystem
2221 size before any modifications.
2222
2223 xspace = IMAGE_ROOTFS_EXTRA_SPACE
2224 </literallayout>
2225 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
2226 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
2227 variables for related information.
2228<!-- In the above example, <filename>overhead</filename> is defined by the
2229 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
2230 variable, <filename>xspace</filename> is defined by the
2231 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
2232 variable, and <filename>du</filename> is the results of the disk usage command
2233 on the initially generated image. -->
2234 </para>
2235 </glossdef>
2236 </glossentry>
2237
2238 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
2239 <glossdef>
2240 <para>
2241 Specifies the complete list of supported image types
2242 by default:
2243 <literallayout class='monospaced'>
2244 jffs2
2245 sum.jffs2
2246 cramfs
2247 ext2
2248 ext2.gz
2249 ext2.bz2
2250 ext3
2251 ext3.gz
2252 ext2.lzma
2253 btrfs
2254 live
2255 squashfs
2256 squashfs-xz
2257 ubi
2258 ubifs
2259 tar
2260 tar.gz
2261 tar.bz2
2262 tar.xz
2263 cpio
2264 cpio.gz
2265 cpio.xz
2266 cpio.lzma
2267 vmdk
2268 elf
2269 </literallayout>
2270 For more information on how these types of images, see
2271 <filename>meta/classes/image_types*.bbclass</filename>
2272 in the
2273 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2274 </para>
2275 </glossdef>
2276 </glossentry>
2277
2278 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
2279 <glossdef>
2280 <para>Helps define the recipe revision for recipes that share
2281 a common <filename>include</filename> file.
2282 You can think of this variable as part of the recipe revision
2283 as set from within an include file.</para>
2284 <para>Suppose, for example, you have a set of recipes that
2285 are used across several projects.
2286 And, within each of those recipes the revision
2287 (its <link linkend='var-PR'><filename>PR</filename></link>
2288 value) is set accordingly.
2289 In this case, when the revision of those recipes changes,
2290 the burden is on you to find all those recipes and
2291 be sure that they get changed to reflect the updated
2292 version of the recipe.
2293 In this scenario, it can get complicated when recipes
2294 that are used in many places and provide common functionality
2295 are upgraded to a new revision.</para>
2296 <para>A more efficient way of dealing with this situation is
2297 to set the <filename>INC_PR</filename> variable inside
2298 the <filename>include</filename> files that the recipes
2299 share and then expand the <filename>INC_PR</filename>
2300 variable within the recipes to help
2301 define the recipe revision.
2302 </para>
2303 <para>
2304 The following provides an example that shows how to use
2305 the <filename>INC_PR</filename> variable
2306 given a common <filename>include</filename> file that
2307 defines the variable.
2308 Once the variable is defined in the
2309 <filename>include</filename> file, you can use the
2310 variable to set the <filename>PR</filename> values in
2311 each recipe.
2312 You will notice that when you set a recipe's
2313 <filename>PR</filename> you can provide more granular
2314 revisioning by appending values to the
2315 <filename>INC_PR</filename> variable:
2316 <literallayout class='monospaced'>
2317recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
2318recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
2319recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
2320recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2321 </literallayout>
2322 The first line of the example establishes the baseline
2323 revision to be used for all recipes that use the
2324 <filename>include</filename> file.
2325 The remaining lines in the example are from individual
2326 recipes and show how the <filename>PR</filename> value
2327 is set.</para>
2328 </glossdef>
2329 </glossentry>
2330
2331 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
2332 <glossdef>
2333 <para>
2334 Specifies a space-separated list of license names
2335 (as they would appear in
2336 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
2337 that should be excluded from the build.
2338 Recipes that provide no alternatives to listed incompatible
2339 licenses are not built.
2340 Packages that are individually licensed with the specified
2341 incompatible licenses will be deleted.
2342 </para>
2343
2344 <note>
2345 This functionality is only regularly tested using
2346 the following setting:
2347 <literallayout class='monospaced'>
2348 INCOMPATIBLE_LICENSE = "GPLv3"
2349 </literallayout>
2350 Although you can use other settings, you might be required
2351 to remove dependencies on or provide alternatives to
2352 components that are required to produce a functional system
2353 image.
2354 </note>
2355 </glossdef>
2356 </glossentry>
2357
2358 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
2359 <glossdef>
2360 <para>
2361 Prevents the default dependencies, namely the C compiler
2362 and standard C library (libc), from being added to
2363 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
2364 This variable is usually used within recipes that do not
2365 require any compilation using the C compiler.
2366 </para>
2367
2368 <para>
2369 Set the variable to "1" to prevent the default dependencies
2370 from being added.
2371 </para>
2372 </glossdef>
2373 </glossentry>
2374
2375 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
2376 <glossdef>
2377 <para>
2378 If set to "1", causes the build to not strip binaries in resulting packages.
2379 </para>
2380 </glossdef>
2381 </glossentry>
2382
2383 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
2384 <glossdef>
2385 <para>
2386 Causes the named class to be inherited at
2387 this point during parsing.
2388 The variable is only valid in configuration files.
2389 </para>
2390 </glossdef>
2391 </glossentry>
2392
2393 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
2394 <glossdef>
2395 <para>
2396 Defines the format for the output image of an initial
2397 RAM disk (initramfs), which is used during boot.
2398 Supported formats are the same as those supported by the
2399 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
2400 variable.
2401 </para>
2402 </glossdef>
2403 </glossentry>
2404
2405 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
2406 <glossdef>
2407 <para>
2408 The filename of the initscript as installed to <filename>${etcdir}/init.d</filename>.
2409 </para>
2410 <para>
2411 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
2412 The variable is Mandatory.
2413 </para>
2414 </glossdef>
2415 </glossentry>
2416
2417 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
2418 <glossdef>
2419 <para>
2420 A list of the packages that contain initscripts.
2421 If multiple packages are specified, you need to append the package name
2422 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
2423 <para>
2424 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
2425 The variable is optional and defaults to the
2426 <link linkend='var-PN'><filename>PN</filename></link> variable.
2427 </para>
2428 </glossdef>
2429 </glossentry>
2430
2431 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
2432 <glossdef>
2433 <para>
2434 Specifies the options to pass to <filename>update-rc.d</filename>.
2435 Here is an example:
2436 <literallayout class='monospaced'>
2437 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
2438 </literallayout>
2439 In this example, the script has a runlevel of 99,
2440 starts the script in initlevels 2 and 5, and
2441 stops the script in levels 0, 1 and 6.
2442 </para>
2443 <para>
2444 The variable is mandatory and is used in recipes when using
2445 <filename>update-rc.d.bbclass</filename>.
2446 </para>
2447 </glossdef>
2448 </glossentry>
2449
2450 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
2451 <glossdef>
2452 <para>
2453 Specifies the QA checks to skip for a specific package
2454 within a recipe.
2455 For example, to skip the check for symbolic link
2456 <filename>.so</filename> files in the main package of a
2457 recipe, add the following to the recipe.
2458 The package name override must be used, which in this
2459 example is <filename>${PN}</filename>:
2460 <literallayout class='monospaced'>
2461 INSANE_SKIP_${PN} += "dev-so"
2462 </literallayout>
2463 </para>
2464 <para>
2465 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
2466 section for a list of the valid QA checks you can
2467 specify using this variable.
2468 </para>
2469 </glossdef>
2470 </glossentry>
2471
2472 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
2473 <glossdef>
2474 <para>
2475 When the IPK backend is in use and package management
2476 is enabled on the target, you can use this variable to
2477 set up <filename>opkg</filename> in the target image
2478 to point to package feeds on a nominated server.
2479 Once the feed is established, you can perform
2480 installations or upgrades using the package manager
2481 at runtime.
2482 </para>
2483 </glossdef>
2484 </glossentry>
2485
2486<!--
2487 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
2488 <glossdef>
2489 <para>
2490 An environment variable that defines the directory where
2491 post installation hooks are installed for the
2492 post install environment.
2493 This variable is fixed as follows:
2494 <literallayout class='monospaced'>
2495 ${WORKDIR}/intercept_scripts
2496 </literallayout>
2497 </para>
2498
2499 <para>
2500 After installation of a target's root filesystem,
2501 post installation scripts, which are essentially bash scripts,
2502 are all executed just a single time.
2503 Limiting execution of these scripts minimizes installation
2504 time that would be lengthened due to certain packages
2505 triggering redundant operations.
2506 For example, consider the installation of font packages
2507 as a common example.
2508 Without limiting the execution of post installation scripts,
2509 all font directories would be rescanned to create the
2510 cache after each individual font package was installed.
2511 </para>
2512
2513 <para>
2514 Do not edit the <filename>INTERCEPT_DIR</filename>
2515 variable.
2516 </para>
2517 </glossdef>
2518 </glossentry>
2519-->
2520
2521 </glossdiv>
2522
2523<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
2524<!-- </glossdiv>-->
2525
2526 <glossdiv id='var-glossary-k'><title>K</title>
2527
2528 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
2529 <glossdef>
2530 <para>
2531 Defines the kernel architecture used when assembling
2532 the configuration.
2533 Architectures supported for this release are:
2534 <literallayout class='monospaced'>
2535 powerpc
2536 i386
2537 x86_64
2538 arm
2539 qemu
2540 mips
2541 </literallayout>
2542 </para>
2543
2544 <para>
2545 You define the <filename>KARCH</filename> variable in the
2546 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
2547 </para>
2548 </glossdef>
2549 </glossentry>
2550
2551 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
2552 <glossdef>
2553 <para>
2554 A regular expression used by the build process to explicitly identify the kernel
2555 branch that is validated, patched and configured during a build.
2556 The <filename>KBRANCH</filename> variable is optional.
2557 You can use it to trigger checks to ensure the exact kernel branch you want is
2558 being used by the build process.
2559 </para>
2560
2561 <para>
2562 Values for this variable are set in the kernel's recipe file and the kernel's
2563 append file.
2564 For example, if you are using the Yocto Project kernel that is based on the
2565 Linux 3.4 kernel, the kernel recipe file is the
2566 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file.
2567 Following is the default value for <filename>KBRANCH</filename> and the default
2568 override for the architectures the Yocto Project supports:
2569 <literallayout class='monospaced'>
2570 KBRANCH_DEFAULT = "standard/base"
2571 KBRANCH = "${KBRANCH_DEFAULT}"
2572 </literallayout>
2573 This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git
2574 repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
2575 </para>
2576
2577 <para>
2578 This variable is also used from the kernel's append file to identify the kernel
2579 branch specific to a particular machine or target hardware.
2580 The kernel's append file is located in the BSP layer for a given machine.
2581 For example, the kernel append file for the Crown Bay BSP is in the
2582 <filename>meta-intel</filename> Git repository and is named
2583 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>.
2584 Here are the related statements from the append file:
2585 <literallayout class='monospaced'>
2586 COMPATIBLE_MACHINE_crownbay = "crownbay"
2587 KMACHINE_crownbay = "crownbay"
2588 KBRANCH_crownbay = "standard/crownbay"
2589
2590 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
2591 KMACHINE_crownbay-noemgd = "crownbay"
2592 KBRANCH_crownbay-noemgd = "standard/crownbay"
2593 </literallayout>
2594 The <filename>KBRANCH_*</filename> statements identify the kernel branch to
2595 use when building for the Crown Bay BSP.
2596 In this case there are two identical statements: one for each type of
2597 Crown Bay machine.
2598 </para>
2599 </glossdef>
2600 </glossentry>
2601
2602 <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
2603 <glossdef>
2604 <para>
2605 Defines the Linux kernel source repository's default
2606 branch used to build the Linux kernel.
2607 The <filename>KBRANCH_DEFAULT</filename> value is
2608 the default value for
2609 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
2610 Unless you specify otherwise,
2611 <filename>KBRANCH_DEFAULT</filename> initializes to
2612 "master".
2613 </para>
2614 </glossdef>
2615 </glossentry>
2616
2617 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
2618 <glossdef>
2619 <para>
2620 Specifies additional <filename>make</filename>
2621 command-line arguments the OpenEmbedded build system
2622 passes on when compiling the kernel.
2623 </para>
2624 </glossdef>
2625 </glossentry>
2626
2627 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
2628 <glossdef>
2629 <para>Includes additional metadata from the Yocto Project kernel Git repository.
2630 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
2631 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
2632 is provided through
2633 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
2634 and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
2635 You can use the <filename>KERNEL_FEATURES</filename> variable to further
2636 add metadata for all BSPs.</para>
2637 <para>The metadata you add through this variable includes config fragments and
2638 features descriptions,
2639 which usually includes patches as well as config fragments.
2640 You typically override the <filename>KERNEL_FEATURES</filename> variable
2641 for a specific machine.
2642 In this way, you can provide validated, but optional, sets of kernel
2643 configurations and features.</para>
2644 <para>For example, the following adds <filename>netfilter</filename> to all
2645 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
2646 machine:
2647 <literallayout class='monospaced'>
2648 # Add netfilter to all linux-yocto kernels
2649 KERNEL_FEATURES="features/netfilter"
2650
2651 # Add sound support to the qemux86 machine
2652 KERNEL_FEATURES_append_qemux86=" cfg/sound"
2653 </literallayout></para>
2654 </glossdef>
2655 </glossentry>
2656
2657 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
2658 <glossdef>
2659 <para>The type of kernel to build for a device, usually set by the
2660 machine configuration files and defaults to "zImage".
2661 This variable is used
2662 when building the kernel and is passed to <filename>make</filename> as the target to
2663 build.</para>
2664 </glossdef>
2665 </glossentry>
2666
2667 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
2668 <glossdef>
2669 <para>
2670 The location of the kernel sources.
2671 This variable is set to the value of the
2672 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
2673 within the <filename>module.bbclass</filename> class.
2674 For information on how this variable is used, see the
2675 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
2676 section.
2677 </para>
2678
2679 <para>
2680 The <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
2681 variable is identical to the <filename>KERNEL_PATH</filename>
2682 variable.
2683 </para>
2684 </glossdef>
2685 </glossentry>
2686
2687 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
2688 <glossdef>
2689 <para>
2690 The location of the kernel sources.
2691 This variable is set to the value of the
2692 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
2693 within the <filename>module.bbclass</filename> class.
2694 For information on how this variable is used, see the
2695 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
2696 section.
2697 </para>
2698
2699 <para>
2700 The <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
2701 variable is identical to the <filename>KERNEL_SRC</filename>
2702 variable.
2703 </para>
2704 </glossdef>
2705 </glossentry>
2706
2707 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
2708 <glossdef>
2709 <para>
2710 Provides a short description of a configuration fragment.
2711 You use this variable in the <filename>.scc</filename>
2712 file that describes a configuration fragment file.
2713 Here is the variable used in a file named
2714 <filename>smp.scc</filename> to describe SMP being
2715 enabled:
2716 <literallayout class='monospaced'>
2717 define KFEATURE_DESCRIPTION "Enable SMP"
2718 </literallayout>
2719 </para>
2720 </glossdef>
2721 </glossentry>
2722
2723 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
2724 <glossdef>
2725 <para>
2726 The machine as known by the kernel.
2727 Sometimes the machine name used by the kernel does not match the machine name
2728 used by the OpenEmbedded build system.
2729 For example, the machine name that the OpenEmbedded build system understands as
2730 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
2731 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
2732 For cases like these, the <filename>KMACHINE</filename> variable maps the
2733 kernel machine name to the OpenEmbedded build system machine name.
2734 </para>
2735
2736 <para>
2737 Kernel machine names are initially defined in the
2738 Yocto Linux Kernel's <filename>meta</filename> branch.
2739 From the <filename>meta</filename> branch, look in
2740 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
2741 For example, from the <filename>meta</filename> branch in the
2742 <filename>linux-yocto-3.0</filename> kernel, the
2743 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
2744 has the following:
2745 <literallayout class='monospaced'>
2746 define KMACHINE cedartrail
2747 define KTYPE standard
2748 define KARCH i386
2749
2750 include ktypes/standard
2751 branch cedartrail
2752
2753 include cedartrail.scc
2754 </literallayout>
2755 You can see that the kernel understands the machine name for
2756 the Cedar Trail Board Support Package (BSP) as
2757 <filename>cedartrail</filename>.
2758 </para>
2759
2760 <para>
2761 If you look in the Cedar Trail BSP layer in the
2762 <filename>meta-intel</filename>
2763 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
2764 at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
2765 you will find the following statements among others:
2766 <literallayout class='monospaced'>
2767 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
2768 KMACHINE_cedartrail = "cedartrail"
2769 KBRANCH_cedartrail = "yocto/standard/cedartrail"
2770 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
2771 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
2772
2773 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
2774 KMACHINE_cedartrail-nopvr = "cedartrail"
2775 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
2776 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
2777 </literallayout>
2778 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
2779 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
2780 names.
2781 </para>
2782
2783 <para>
2784 This append file uses two <filename>KMACHINE</filename> statements.
2785 The first is not really necessary but does ensure that the machine known to the
2786 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
2787 in the kernel also known as <filename>cedartrail</filename>:
2788 <literallayout class='monospaced'>
2789 KMACHINE_cedartrail = "cedartrail"
2790 </literallayout>
2791 </para>
2792
2793 <para>
2794 The second statement is a good example of why the <filename>KMACHINE</filename> variable
2795 is needed.
2796 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
2797 machine name to refer to the Cedar Trail BSP that does not support the proprietary
2798 PowerVR driver.
2799 The kernel, however, uses the machine name <filename>cedartrail</filename>.
2800 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
2801 the kernel's <filename>cedartrail</filename> name:
2802 <literallayout class='monospaced'>
2803 KMACHINE_cedartrail-nopvr = "cedartrail"
2804 </literallayout>
2805 </para>
2806
2807 <para>
2808 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
2809 Project kernel machine names and the OpenEmbedded machine names.
2810 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
2811 name you use is different than that used in the kernel.
2812 </para>
2813 </glossdef>
2814 </glossentry>
2815
2816 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
2817 <glossdef>
2818 <para>
2819 Defines the kernel type to be used in assembling the
2820 configuration.
2821 The linux-yocto recipes define "standard", "tiny",
2822 and "preempt-rt" kernel types.
2823 See the
2824 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
2825 section in the Yocto Project Linux Kernel Development
2826 Manual for more information on kernel types.
2827 </para>
2828
2829 <para>
2830 You define the <filename>KTYPE</filename> variable in the
2831 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
2832 The value you use must match the value used for the
2833 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
2834 value used by the kernel recipe.
2835 </para>
2836 </glossdef>
2837 </glossentry>
2838 </glossdiv>
2839
2840 <glossdiv id='var-glossary-l'><title>L</title>
2841
2842 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
2843 <glossdef>
2844 <para>Lists the layers that this recipe depends upon, separated by spaces.
2845 Optionally, you can specify a specific layer version for a dependency
2846 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
2847 to be compared against
2848 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
2849 in this case).
2850 An error will be produced if any dependency is missing or
2851 the version numbers do not match exactly (if specified).
2852 This variable is used in the <filename>conf/layer.conf</filename> file
2853 and must be suffixed with the name of the specific layer (e.g.
2854 <filename>LAYERDEPENDS_mylayer</filename>).</para>
2855 </glossdef>
2856 </glossentry>
2857
2858 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
2859 <glossdef>
2860 <para>When used inside the <filename>layer.conf</filename> configuration
2861 file, this variable provides the path of the current layer.
2862 This variable is not available outside of <filename>layer.conf</filename>
2863 and references are expanded immediately when parsing of the file completes.</para>
2864 </glossdef>
2865 </glossentry>
2866
2867 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
2868 <glossdef>
2869 <para>Optionally specifies the version of a layer as a single number.
2870 You can use this within
2871 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
2872 for another layer in order to depend on a specific version
2873 of the layer.
2874 This variable is used in the <filename>conf/layer.conf</filename> file
2875 and must be suffixed with the name of the specific layer (e.g.
2876 <filename>LAYERVERSION_mylayer</filename>).</para>
2877 </glossdef>
2878 </glossentry>
2879
2880 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
2881 <glossdef>
2882 <para>Checksums of the license text in the recipe source code.</para>
2883 <para>This variable tracks changes in license text of the source
2884 code files.
2885 If the license text is changed, it will trigger a build
2886 failure, which gives the developer an opportunity to review any
2887 license change.</para>
2888 <para>
2889 This variable must be defined for all recipes (unless
2890 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2891 is set to "CLOSED")</para>
2892 <para>For more information, see the
2893 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
2894 Tracking License Changes</link> section</para>
2895 </glossdef>
2896 </glossentry>
2897
2898 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
2899 <glossdef>
2900 <para>
2901 The list of source licenses for the recipe.
2902 Follow these rules:
2903 <itemizedlist>
2904 <listitem><para>Do not use spaces within individual
2905 license names.</para></listitem>
2906 <listitem><para>Separate license names using
2907 | (pipe) when there is a choice between licenses.
2908 </para></listitem>
2909 <listitem><para>Separate license names using
2910 &amp; (ampersand) when multiple licenses exist
2911 that cover different parts of the source.
2912 </para></listitem>
2913 <listitem><para>You can use spaces between license
2914 names.</para></listitem>
2915 </itemizedlist>
2916 </para>
2917
2918 <para>
2919 Here are some examples:
2920 <literallayout class='monospaced'>
2921 LICENSE = "LGPLv2.1 | GPLv3"
2922 LICENSE = "MPL-1 &amp; LGPLv2.1"
2923 LICENSE = "GPLv2+"
2924 </literallayout>
2925 The first example is from the recipes for Qt, which the user
2926 may choose to distribute under either the LGPL version
2927 2.1 or GPL version 3.
2928 The second example is from Cairo where two licenses cover
2929 different parts of the source code.
2930 The final example is from <filename>sysstat</filename>,
2931 which presents a single license.
2932 </para>
2933
2934 <para>
2935 You can also specify licenses on a per-package basis to
2936 handle situations where components of the output have
2937 different licenses.
2938 For example, a piece of software whose code is
2939 licensed under GPLv2 but has accompanying documentation
2940 licensed under the GNU Free Documentation License 1.2 could
2941 be specified as follows:
2942 <literallayout class='monospaced'>
2943 LICENSE = "GFDL-1.2 &amp; GPLv2"
2944 LICENSE_${PN} = "GPLv2"
2945 LICENSE_${PN}-doc = "GFDL-1.2"
2946 </literallayout>
2947 </para>
2948 </glossdef>
2949 </glossentry>
2950
2951 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
2952 <glossdef>
2953 <para>Path to additional licenses used during the build.
2954 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
2955 to define the directory that holds common license text used during the build.
2956 The <filename>LICENSE_PATH</filename> variable allows you to extend that
2957 location to other areas that have additional licenses:
2958 <literallayout class='monospaced'>
2959 LICENSE_PATH += "/path/to/additional/common/licenses"
2960 </literallayout></para>
2961 </glossdef>
2962 </glossentry>
2963
2964 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
2965 <glossdef>
2966 <para>
2967 Defines the kernel type to be used in assembling the
2968 configuration.
2969 The linux-yocto recipes define "standard", "tiny", and
2970 "preempt-rt" kernel types.
2971 See the
2972 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
2973 section in the Yocto Project Linux Kernel Development
2974 Manual for more information on kernel types.
2975 </para>
2976
2977 <para>
2978 If you do not specify a
2979 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
2980 "standard".
2981 Together with
2982 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
2983 the <filename>LINUX_KERNEL_TYPE</filename> variable
2984 defines the search
2985 arguments used by the kernel tools to find the appropriate
2986 description within the kernel
2987 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
2988 with which to build out the sources and configuration.
2989 </para>
2990 </glossdef>
2991 </glossentry>
2992
2993 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
2994 <glossdef>
2995 <para>The Linux version from <filename>kernel.org</filename>
2996 on which the Linux kernel image being built using the
2997 OpenEmbedded build system is based.
2998 You define this variable in the kernel recipe.
2999 For example, the <filename>linux-yocto-3.4.bb</filename>
3000 kernel recipe found in
3001 <filename>meta/recipes-kernel/linux</filename>
3002 defines the variables as follows:
3003 <literallayout class='monospaced'>
3004 LINUX_VERSION ?= "3.4.24"
3005 </literallayout>
3006 The <filename>LINUX_VERSION</filename> variable is used to
3007 define <link linkend='var-PV'><filename>PV</filename></link>
3008 for the recipe:
3009 <literallayout class='monospaced'>
3010 PV = "${LINUX_VERSION}+git${SRCPV}"
3011 </literallayout></para>
3012 </glossdef>
3013 </glossentry>
3014
3015 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
3016 <glossdef>
3017 <para>A string extension compiled into the version
3018 string of the Linux kernel built with the OpenEmbedded
3019 build system.
3020 You define this variable in the kernel recipe.
3021 For example, the linux-yocto kernel recipes all define
3022 the variable as follows:
3023 <literallayout class='monospaced'>
3024 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
3025 </literallayout>
3026 Defining this variable essentially sets the
3027 Linux kernel configuration item
3028 <filename>CONFIG_LOCALVERSION</filename>, which is visible
3029 through the <filename>uname</filename> command.
3030 Here is an example that shows the extension assuming it
3031 was set as previously shown:
3032 <literallayout class='monospaced'>
3033 $ uname -r
3034 3.7.0-rc8-custom
3035 </literallayout>
3036 </para>
3037 </glossdef>
3038 </glossentry>
3039
3040 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
3041 <glossdef>
3042 <para>
3043 Specifies the directory to which the OpenEmbedded build
3044 system writes overall log files.
3045 The default directory is <filename>${TMPDIR}/log</filename>.
3046 </para>
3047 <para>
3048 For the directory containing logs specific to each task,
3049 see the <link linkend='var-T'><filename>T</filename></link>
3050 variable.
3051 </para>
3052 </glossdef>
3053 </glossentry>
3054
3055 </glossdiv>
3056
3057 <glossdiv id='var-glossary-m'><title>M</title>
3058
3059 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
3060 <glossdef>
3061 <para>
3062 Specifies the target device for which the image is built.
3063 You define <filename>MACHINE</filename> in the
3064 <filename>local.conf</filename> file found in the
3065 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
3066 By default, <filename>MACHINE</filename> is set to
3067 "qemux86", which is an x86-based architecture machine to
3068 be emulated using QEMU:
3069 <literallayout class='monospaced'>
3070 MACHINE ?= "qemux86"
3071 </literallayout>
3072 The variable corresponds to a machine configuration file of the
3073 same name, through which machine-specific configurations are set.
3074 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
3075 exists the corresponding <filename>qemux86.conf</filename> machine
3076 configuration file, which can be found in the
3077 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3078 in <filename>meta/conf/machine</filename>.
3079 </para>
3080
3081 <para>
3082 The list of machines supported by the Yocto Project as
3083 shipped include the following:
3084 <literallayout class='monospaced'>
3085 MACHINE ?= "qemuarm"
3086 MACHINE ?= "qemumips"
3087 MACHINE ?= "qemuppc"
3088 MACHINE ?= "qemux86"
3089 MACHINE ?= "qemux86-64"
3090 MACHINE ?= "genericx86"
3091 MACHINE ?= "beagleboard"
3092 MACHINE ?= "mpc8315e-rdb"
3093 MACHINE ?= "routerstationpro"
3094 </literallayout>
3095 The last four are Yocto Project reference hardware boards, which
3096 are provided in the <filename>meta-yocto-bsp</filename> layer.
3097 <note>Adding additional Board Support Package (BSP) layers
3098 to your configuration adds new possible settings for
3099 <filename>MACHINE</filename>.
3100 </note>
3101 </para>
3102 </glossdef>
3103 </glossentry>
3104
3105 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
3106 <glossdef>
3107 <para></para>
3108 <para>
3109 A list of required machine-specific packages to install as part of
3110 the image being built.
3111 The build process depends on these packages being present.
3112 Furthermore, because this is a "machine essential" variable, the list of
3113 packages are essential for the machine to boot.
3114 The impact of this variable affects images based on
3115 <filename>packagegroup-core-boot</filename>,
3116 including the <filename>core-image-minimal</filename> image.
3117 </para>
3118 <para>
3119 This variable is similar to the
3120 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
3121 variable with the exception that the image being built has a build
3122 dependency on the variable's list of packages.
3123 In other words, the image will not build if a file in this list is not found.
3124 </para>
3125 <para>
3126 As an example, suppose the machine for which you are building requires
3127 <filename>example-init</filename> to be run during boot to initialize the hardware.
3128 In this case, you would use the following in the machine's
3129 <filename>.conf</filename> configuration file:
3130 <literallayout class='monospaced'>
3131 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
3132 </literallayout>
3133 </para>
3134 </glossdef>
3135 </glossentry>
3136
3137 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
3138 <glossdef>
3139 <para></para>
3140 <para>
3141 A list of recommended machine-specific packages to install as part of
3142 the image being built.
3143 The build process does not depend on these packages being present.
3144 However, because this is a "machine essential" variable, the list of
3145 packages are essential for the machine to boot.
3146 The impact of this variable affects images based on
3147 <filename>packagegroup-core-boot</filename>,
3148 including the <filename>core-image-minimal</filename> image.
3149 </para>
3150 <para>
3151 This variable is similar to the
3152 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
3153 variable with the exception that the image being built does not have a build
3154 dependency on the variable's list of packages.
3155 In other words, the image will still build if a package in this list is not found.
3156 Typically, this variable is used to handle essential kernel modules, whose
3157 functionality may be selected to be built into the kernel rather than as a module,
3158 in which case a package will not be produced.
3159 </para>
3160 <para>
3161 Consider an example where you have a custom kernel where a specific touchscreen
3162 driver is required for the machine to be usable.
3163 However, the driver can be built as a module or
3164 into the kernel depending on the kernel configuration.
3165 If the driver is built as a module, you want it to be installed.
3166 But, when the driver is built into the kernel, you still want the
3167 build to succeed.
3168 This variable sets up a "recommends" relationship so that in the latter case,
3169 the build will not fail due to the missing package.
3170 To accomplish this, assuming the package for the module was called
3171 <filename>kernel-module-ab123</filename>, you would use the
3172 following in the machine's <filename>.conf</filename> configuration
3173 file:
3174 <literallayout class='monospaced'>
3175 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
3176 </literallayout>
3177 </para>
3178 <para>
3179 Some examples of these machine essentials are flash, screen, keyboard, mouse,
3180 or touchscreen drivers (depending on the machine).
3181 </para>
3182 </glossdef>
3183 </glossentry>
3184
3185 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
3186 <glossdef>
3187 <para>
3188 A list of machine-specific packages to install as part of the
3189 image being built that are not essential for the machine to boot.
3190 However, the build process for more fully-featured images
3191 depends on the packages being present.
3192 </para>
3193 <para>
3194 This variable affects all images based on
3195 <filename>packagegroup-base</filename>, which does not include the
3196 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
3197 images.
3198 </para>
3199 <para>
3200 The variable is similar to the
3201 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
3202 variable with the exception that the image being built has a build
3203 dependency on the variable's list of packages.
3204 In other words, the image will not build if a file in this list is not found.
3205 </para>
3206 <para>
3207 An example is a machine that has WiFi capability but is not
3208 essential for the machine to boot the image.
3209 However, if you are building a more fully-featured image, you want to enable
3210 the WiFi.
3211 The package containing the firmware for the WiFi hardware is always
3212 expected to exist, so it is acceptable for the build process to depend upon
3213 finding the package.
3214 In this case, assuming the package for the firmware was called
3215 <filename>wifidriver-firmware</filename>, you would use the following in the
3216 <filename>.conf</filename> file for the machine:
3217 <literallayout class='monospaced'>
3218 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
3219 </literallayout>
3220 </para>
3221 </glossdef>
3222 </glossentry>
3223
3224 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
3225 <glossdef>
3226 <para></para>
3227 <para>
3228 A list of machine-specific packages to install as part of the
3229 image being built that are not essential for booting the machine.
3230 The image being built has no build dependency on this list of packages.
3231 </para>
3232 <para>
3233 This variable affects only images based on
3234 <filename>packagegroup-base</filename>, which does not include the
3235 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
3236 images.
3237 </para>
3238 <para>
3239 This variable is similar to the
3240 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
3241 variable with the exception that the image being built does not have a build
3242 dependency on the variable's list of packages.
3243 In other words, the image will build if a file in this list is not found.
3244 </para>
3245 <para>
3246 An example is a machine that has WiFi capability but is not essential
3247 For the machine to boot the image.
3248 However, if you are building a more fully-featured image, you want to enable
3249 WiFi.
3250 In this case, the package containing the WiFi kernel module will not be produced
3251 if the WiFi driver is built into the kernel, in which case you still want the
3252 build to succeed instead of failing as a result of the package not being found.
3253 To accomplish this, assuming the package for the module was called
3254 <filename>kernel-module-examplewifi</filename>, you would use the
3255 following in the <filename>.conf</filename> file for the machine:
3256 <literallayout class='monospaced'>
3257 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
3258 </literallayout>
3259 </para>
3260 </glossdef>
3261 </glossentry>
3262
3263 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
3264 <glossdef>
3265 <para>Specifies the list of hardware features the
3266 <link linkend='var-MACHINE'>MACHINE</link> supports.
3267 For example, including the "bluetooth" feature causes the
3268 <filename>bluez</filename> bluetooth daemon to be built and
3269 added to the image.
3270 It also causes the <filename>connman</filename> recipe
3271 to look at <filename>MACHINE_FEATURES</filename> and when it
3272 finds "bluetooth" there it enables the bluetooth
3273 support in ConnMan.
3274 </para>
3275
3276 <para>
3277 For a list of features supported by the Yocto Project as shipped,
3278 see the "<link linkend='ref-features-machine'>Machine</link>" section.
3279 </para>
3280 </glossdef>
3281 </glossentry>
3282
3283 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
3284 <glossdef>
3285 <para>Features to be added to
3286 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
3287 if not also present in
3288 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
3289 </para>
3290
3291 <para>
3292 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
3293 It is not intended to be user-configurable.
3294 It is best to just reference the variable to see which machine features are
3295 being backfilled for all machine configurations.
3296 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
3297 more information.
3298 </para>
3299 </glossdef>
3300 </glossentry>
3301
3302 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
3303 <glossdef>
3304 <para>Features from
3305 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
3306 that should not be backfilled (i.e. added to
3307 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
3308 during the build.
3309 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
3310 more information.
3311 </para>
3312 </glossdef>
3313 </glossentry>
3314
3315 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
3316 <glossdef>
3317 <para>
3318 Lists overrides specific to the current machine.
3319 By default, this list includes the value
3320 of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
3321 You can extend the list to apply variable overrides for
3322 classes of machines.
3323 For example, all QEMU emulated machines (e.g. qemuarm,
3324 qemux86, and so forth) include a common file named
3325 <filename>meta/conf/machine/include/qemu.inc</filename>
3326 that prepends <filename>MACHINEOVERRIDES</filename> with
3327 the following variable override:
3328 <literallayout class='monospaced'>
3329 MACHINEOVERRIDES =. "qemuall:"
3330 </literallayout>
3331 Applying an override like <filename>qemuall</filename>
3332 affects all QEMU emulated machines elsewhere.
3333 Here is an example from the
3334 <filename>connman-conf</filename> recipe:
3335 <literallayout class='monospaced'>
3336 SRC_URI_append_qemuall = "file://wired.config \
3337 file://wired-setup \
3338 "
3339 </literallayout>
3340 </para>
3341 </glossdef>
3342 </glossentry>
3343
3344 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
3345 <glossdef>
3346 <para>The email address of the distribution maintainer.</para>
3347 </glossdef>
3348 </glossentry>
3349
3350 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
3351 <glossdef>
3352 <para>
3353 Specifies additional paths from which the OpenEmbedded
3354 build system gets source code.
3355 When the build system searches for source code, it first
3356 tries the local download directory.
3357 If that location fails, the build system tries locations
3358 defined by
3359 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
3360 the upstream source, and then locations specified by
3361 <filename>MIRRORS</filename> in that order.
3362 </para>
3363
3364 <para>
3365 Assuming your distribution
3366 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
3367 is "poky", the default value for
3368 <filename>MIRRORS</filename> is defined in the
3369 <filename>conf/distro/poky.conf</filename> file in the
3370 <filename>meta-yocto</filename> Git repository.
3371 </para>
3372 </glossdef>
3373 </glossentry>
3374
3375 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
3376 <glossdef>
3377 <para>
3378 Specifies a prefix has been added to
3379 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
3380 of a recipe or package, such as a Multilib version.
3381 The variable is used in places where the prefix needs to be
3382 added to or removed from a the name (e.g. the
3383 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
3384 <filename>MLPREFIX</filename> gets set when a prefix has been
3385 added to <filename>PN</filename>.
3386 </para>
3387 </glossdef>
3388 </glossentry>
3389
3390 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
3391 <glossdef>
3392 <para>
3393 Controls creation of the <filename>modules-*.tgz</filename>
3394 file.
3395 Set this variable to "0" to disable creation of this
3396 file, which contains all of the kernel modules resulting
3397 from a kernel build.
3398 </para>
3399 </glossdef>
3400 </glossentry>
3401
3402 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
3403 <glossdef>
3404 <para>
3405 Separates files for different machines such that you can build
3406 for multiple target machines using the same output directories.
3407 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
3408 for an example.
3409 </para>
3410 </glossdef>
3411 </glossentry>
3412
3413 </glossdiv>
3414
3415 <glossdiv id='var-glossary-n'><title>N</title>
3416
3417 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
3418 <glossdef>
3419 <para>
3420 A string identifying the host distribution.
3421 Strings consist of the host distributor ID
3422 followed by the release, as reported by the
3423 <filename>lsb_release</filename> tool
3424 or as read from <filename>/etc/lsb-release</filename>.
3425 For example, when running a build on Ubuntu 12.10, the value
3426 is "Ubuntu-12.10".
3427 If this information is unable to be determined, the value
3428 resolves to "Unknown".
3429 </para>
3430 <para>
3431 This variable is used by default to isolate native shared
3432 state packages for different distributions (e.g. to avoid
3433 problems with <filename>glibc</filename> version
3434 incompatibilities).
3435 Additionally, the variable is checked against
3436 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
3437 if that variable is set.
3438 </para>
3439 </glossdef>
3440 </glossentry>
3441
3442 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
3443 <glossdef>
3444 <para>
3445 Prevents installation of all "recommended-only" packages.
3446 Recommended-only packages are packages installed only
3447 through the
3448 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
3449 variable).
3450 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
3451 to "1" turns this feature on:
3452 <literallayout class='monospaced'>
3453 NO_RECOMMENDATIONS = "1"
3454 </literallayout>
3455 You can set this variable globally in your
3456 <filename>local.conf</filename> file or you can attach it to
3457 a specific image recipe by using the recipe name override:
3458 <literallayout class='monospaced'>
3459 NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
3460 </literallayout>
3461 </para>
3462
3463 <para>
3464 It is important to realize that if you choose to not install
3465 packages using this variable and some other packages are
3466 dependent on them (i.e. listed in a recipe's
3467 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3468 variable), the OpenEmbedded build system ignores your
3469 request and will install the packages to avoid dependency
3470 errors.
3471 <note>
3472 Some recommended packages might be required for certain
3473 system functionality, such as kernel modules.
3474 It is up to you to add packages with
3475 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
3476 variable.
3477 </note>
3478 </para>
3479
3480 <para>
3481 Support for this variable exists only when using the
3482 IPK and RPM packaging backend.
3483 Support does not exist for DEB.
3484 </para>
3485
3486 <para>
3487 See the
3488 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
3489 and the
3490 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
3491 variables for related information.
3492 </para>
3493 </glossdef>
3494 </glossentry>
3495 </glossdiv>
3496
3497 <glossdiv id='var-glossary-o'><title>O</title>
3498
3499 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
3500 <glossdef>
3501 <para>
3502 When a recipe inherits the
3503 <filename>binconfig.bbclass</filename> class, this variable
3504 specifies additional arguments passed to the "sed" command.
3505 The sed command alters any paths in configuration scripts
3506 that have been set up during compilation.
3507 Inheriting this class results in all paths in these scripts
3508 being changed to point into the
3509 <filename>sysroots/</filename> directory so that all builds
3510 that use the script will use the correct directories
3511 for the cross compiling layout.
3512 </para>
3513
3514 <para>
3515 See the <filename>meta/classes/binconfig.bbclass</filename>
3516 in the
3517 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3518 for details on how this class applies these additional
3519 sed command arguments.
3520 For general information on the
3521 <filename>binconfig.bbclass</filename> class, see the
3522 "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
3523 section.
3524 </para>
3525 </glossdef>
3526 </glossentry>
3527
3528 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
3529 <glossdef>
3530 <para>
3531 An internal variable used to tell the OpenEmbedded build
3532 system what Python modules to import for every Python
3533 function run by the system.
3534 </para>
3535
3536 <note>
3537 Do not set this variable.
3538 It is for internal use only.
3539 </note>
3540 </glossdef>
3541 </glossentry>
3542
3543 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
3544 <glossdef>
3545 <para>
3546 Controls how the OpenEmbedded build system spawns
3547 interactive terminals on the host development system
3548 (e.g. using the BitBake command with the
3549 <filename>-c devshell</filename> command-line option).
3550 For more information, see the
3551 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
3552 in the Yocto Project Development Manual.
3553 </para>
3554
3555 <para>
3556 You can use the following values for the
3557 <filename>OE_TERMINAL</filename> variable:
3558 <literallayout class='monospaced'>
3559 auto
3560 gnome
3561 xfce
3562 rxvt
3563 screen
3564 konsole
3565 none
3566 </literallayout>
3567 <note>Konsole support only works for KDE 3.x.
3568 Also, "auto" is the default behavior for
3569 <filename>OE_TERMINAL</filename></note>
3570 </para>
3571 </glossdef>
3572 </glossentry>
3573
3574 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
3575 <glossdef>
3576 <para>
3577 The directory from which the top-level build environment
3578 setup script is sourced.
3579 The Yocto Project makes two top-level build environment
3580 setup scripts available:
3581 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
3582 and
3583 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
3584 When you run one of these scripts, the
3585 <filename>OEROOT</filename> variable resolves to the
3586 directory that holds the script.
3587 </para>
3588
3589 <para>
3590 For additional information on how this variable is used,
3591 see the initialization scripts.
3592 </para>
3593 </glossdef>
3594 </glossentry>
3595
3596 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
3597 <glossdef>
3598 <para>
3599 Declares the oldest version of the Linux kernel that the
3600 produced binaries must support.
3601 This variable is passed into the build of the Embedded
3602 GNU C Library (<filename>eglibc</filename>).
3603 </para>
3604
3605 <para>
3606 The default for this variable comes from the
3607 <filename>meta/conf/bitbake.conf</filename> configuration
3608 file.
3609 You can override this default by setting the variable
3610 in a custom distribution configuration file.
3611 </para>
3612 </glossdef>
3613 </glossentry>
3614
3615 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
3616 <glossdef>
3617 <para>
3618 BitBake uses <filename>OVERRIDES</filename> to control
3619 what variables are overridden after BitBake parses
3620 recipes and configuration files.
3621 You can find more information on how overrides are handled
3622 in the BitBake Manual that is located at
3623 <filename>bitbake/doc/manual</filename> in the
3624 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3625 </para>
3626 </glossdef>
3627 </glossentry>
3628 </glossdiv>
3629
3630 <glossdiv id='var-glossary-p'><title>P</title>
3631
3632 <glossentry id='var-P'><glossterm>P</glossterm>
3633 <glossdef>
3634 <para>The recipe name and version.
3635 <filename>P</filename> is comprised of the following:
3636 <literallayout class='monospaced'>
3637 ${PN}-${PV}
3638 </literallayout></para>
3639 </glossdef>
3640 </glossentry>
3641
3642 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
3643 <glossdef>
3644 <para>The architecture of the resulting package or packages.</para>
3645 </glossdef>
3646 </glossentry>
3647
3648 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
3649 <glossdef>
3650 <para>Enables easily adding packages to
3651 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
3652 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
3653 so that the packages can pick up files that would normally be
3654 included in the default package.</para>
3655 </glossdef>
3656 </glossentry>
3657
3658 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
3659 <glossdef>
3660 <para>This variable, which is set in the <filename>local.conf</filename> configuration
3661 file found in the <filename>conf</filename> folder of the
3662 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
3663 specifies the package manager to use when packaging data.
3664 You can provide one or more arguments for the variable with the first
3665 argument being the package manager used to create images:
3666 <literallayout class='monospaced'>
3667 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
3668 </literallayout>
3669 For information on build performance effects as a result of the
3670 package manager use, see
3671 <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
3672 in this manual.
3673 </para>
3674 </glossdef>
3675 </glossentry>
3676
3677 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
3678 <glossdef>
3679 <para>
3680 Lists packages that should not be installed into an image.
3681 For example:
3682 <literallayout class='monospaced'>
3683 PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
3684 </literallayout>
3685 You can set this variable globally in your
3686 <filename>local.conf</filename> file or you can attach it to
3687 a specific image recipe by using the recipe name override:
3688 <literallayout class='monospaced'>
3689 PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
3690 </literallayout>
3691 </para>
3692
3693 <para>
3694 If you choose to not install
3695 a package using this variable and some other package is
3696 dependent on it (i.e. listed in a recipe's
3697 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3698 variable), the OpenEmbedded build system generates a fatal
3699 installation error.
3700 Because the build system halts the process with a fatal
3701 error, you can use the variable with an iterative
3702 development process to remove specific components from a
3703 system.
3704 </para>
3705
3706 <para>
3707 Support for this variable exists only when using the
3708 IPK and RPM packaging backend.
3709 Support does not exist for DEB.
3710 </para>
3711
3712 <para>
3713 See the
3714 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
3715 and the
3716 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
3717 variables for related information.
3718 </para>
3719 </glossdef>
3720 </glossentry>
3721
3722 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
3723 <glossdef>
3724 <para>Specifies the list of architectures compatible with the device CPU.
3725 This variable is useful when you build for several different devices that use
3726 miscellaneous processors such as XScale and ARM926-EJS).</para>
3727 </glossdef>
3728 </glossentry>
3729
3730 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
3731 <glossdef>
3732 <para>
3733 Defines one or more packages to include in an image when
3734 a specific item is included in
3735 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
3736 When setting the value, <filename>PACKAGE_GROUP</filename>
3737 should have the name of the feature item as an override.
3738 Here is an example:
3739 <literallayout class='monospaced'>
3740 PACKAGE_GROUP_widget = "package1 package2"
3741 </literallayout>
3742 In this example, if "widget" were added to
3743 <filename>IMAGE_FEATURES</filename>, "package1" and
3744 "package2" would be included in the image.
3745 <note>
3746 Packages installed by features defined through
3747 <filename>PACKAGE_GROUP</filename> are often package
3748 groups.
3749 While similarly named, you should not confuse the
3750 <filename>PACKAGE_GROUP</filename> variable with
3751 package groups, which are discussed elsewhere in the
3752 documentation.
3753 </note>
3754 </para>
3755 </glossdef>
3756 </glossentry>
3757
3758 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
3759 <glossdef>
3760 <para>
3761 The final list of packages passed to the package manager
3762 for installation into the image.
3763 Because the package manager controls actual installation
3764 of all packages, the list of packages passed using
3765 <filename>PACKAGE_INSTALL</filename> is not the final list
3766 of packages that are actually installed.
3767 </para>
3768
3769 <para>
3770 This variable is internal to the image construction
3771 code.
3772 Use the
3773 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
3774 variable to specify packages for installation.
3775 </para>
3776 </glossdef>
3777 </glossentry>
3778
3779 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
3780 <glossdef>
3781 <para>
3782 This variable provides a means of enabling or disabling
3783 features of a recipe on a per-recipe basis.
3784 <filename>PACKAGECONFIG</filename> blocks are defined
3785 in recipes when you specify features and then arguments
3786 that define feature behaviors.
3787 Here is the basic block structure:
3788 <literallayout class='monospaced'>
3789 PACKAGECONFIG ??= "f1 f2 f3 ..."
3790 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
3791 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
3792 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
3793 </literallayout>
3794 The <filename>PACKAGECONFIG</filename>
3795 variable itself specifies a space-separated list of the
3796 features to enable.
3797 Following the features, you can determine the behavior of
3798 each feature by providing up to four order-dependent
3799 arguments, which are separated by commas.
3800 You can omit any argument you like but must retain the
3801 separating commas.
3802 The order is important and specifies the following:
3803 <orderedlist>
3804 <listitem><para>Extra arguments
3805 that should be added to the configure script
3806 argument list
3807 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
3808 if the feature is enabled.</para></listitem>
3809 <listitem><para>Extra arguments
3810 that should be added to <filename>EXTRA_OECONF</filename>
3811 if the feature is disabled.
3812 </para></listitem>
3813 <listitem><para>Additional build dependencies
3814 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
3815 that should be added if the feature is enabled.
3816 </para></listitem>
3817 <listitem><para>Additional runtime dependencies
3818 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
3819 that should be added if the feature is enabled.
3820 </para></listitem>
3821 </orderedlist>
3822 </para>
3823
3824 <para>
3825 Consider the following
3826 <filename>PACKAGECONFIG</filename> block taken from the
3827 <filename>librsvg</filename> recipe.
3828 In this example the feature is <filename>croco</filename>,
3829 which has three arguments that determine the feature's
3830 behavior.
3831 <literallayout class='monospaced'>
3832 PACKAGECONFIG ??= "croco"
3833 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
3834 </literallayout>
3835 The <filename>--with-croco</filename> and
3836 <filename>libcroco</filename> arguments apply only if
3837 the feature is enabled.
3838 In this case, <filename>--with-croco</filename> is
3839 added to the configure script argument list and
3840 <filename>libcroco</filename> is added to
3841 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
3842 On the other hand, if the feature is disabled say through
3843 a <filename>.bbappend</filename> file in another layer, then
3844 the second argument <filename>--without-croco</filename> is
3845 added to the configure script rather than
3846 <filename>--with-croco</filename>.
3847 </para>
3848
3849 <para>
3850 The basic <filename>PACKAGECONFIG</filename> structure
3851 previously described holds true regardless of whether you
3852 are creating a block or changing a block.
3853 When creating a block, use the structure inside your
3854 recipe.
3855 </para>
3856
3857 <para>
3858 If you want to change an existing
3859 <filename>PACKAGECONFIG</filename> block, you can do so
3860 one of two ways:
3861 <itemizedlist>
3862 <listitem><para><emphasis>Append file:</emphasis>
3863 Create an append file named
3864 <filename>&lt;recipename&gt;.bbappend</filename> in your
3865 layer and override the value of
3866 <filename>PACKAGECONFIG</filename>.
3867 You can either completely override the variable:
3868 <literallayout class='monospaced'>
3869 PACKAGECONFIG="f4 f5"
3870 </literallayout>
3871 Or, you can just amended the variable:
3872 <literallayout class='monospaced'>
3873 PACKAGECONFIG_append = " f4"
3874 </literallayout></para></listitem>
3875 <listitem><para><emphasis>Configuration file:</emphasis>
3876 This method is identical to changing the block
3877 through an append file except you edit your
3878 <filename>local.conf</filename> or
3879 <filename>&lt;mydistro&gt;.conf</filename> file.
3880 As with append files previously described,
3881 you can either completely override the variable:
3882 <literallayout class='monospaced'>
3883 PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
3884 </literallayout>
3885 Or, you can just amended the variable:
3886 <literallayout class='monospaced'>
3887 PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
3888 </literallayout></para></listitem>
3889 </itemizedlist>
3890 </para>
3891 </glossdef>
3892 </glossentry>
3893
3894 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
3895 <glossdef>
3896 <para>The list of packages to be created from the recipe.
3897 The default value is the following:
3898 <literallayout class='monospaced'>
3899 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
3900 </literallayout></para>
3901 </glossdef>
3902 </glossentry>
3903
3904 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
3905 <glossdef>
3906 <para>
3907 A promise that your recipe satisfies runtime dependencies
3908 for optional modules that are found in other recipes.
3909 <filename>PACKAGES_DYNAMIC</filename>
3910 does not actually satisfy the dependencies, it only states that
3911 they should be satisfied.
3912 For example, if a hard, runtime dependency
3913 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
3914 of another package is satisfied
3915 at build time through the <filename>PACKAGES_DYNAMIC</filename>
3916 variable, but a package with the module name is never actually
3917 produced, then the other package will be broken.
3918 Thus, if you attempt to include that package in an image,
3919 you will get a dependency failure from the packaging system
3920 during <filename>do_rootfs</filename>.
3921 </para>
3922 <para>
3923 Typically, if there is a chance that such a situation can
3924 occur and the package that is not created is valid
3925 without the dependency being satisfied, then you should use
3926 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
3927 (a soft runtime dependency) instead of
3928 <filename>RDEPENDS</filename>.
3929 </para>
3930
3931 <para>
3932 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
3933 variable when you are splitting packages, see the
3934 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
3935 in the Yocto Project Development Manual.
3936 </para>
3937 </glossdef>
3938 </glossentry>
3939
3940 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
3941 <glossdef>
3942 <para>
3943 Extra options that are passed to the
3944 <filename>make</filename> command during the
3945 <filename>do_compile</filename> task in order to specify
3946 parallel compilation.
3947 This variable is usually in the form
3948 <filename>-j 4</filename>, where the number
3949 represents the maximum number of parallel threads make can
3950 run.
3951 If you development host supports multiple cores a good
3952 rule of thumb is to set this variable to twice the number
3953 of cores on the host.
3954 <note>
3955 Individual recipes might clear out this variable if
3956 the software being built has problems running its
3957 <filename>make</filename> process in parallel.
3958 </note>
3959 </para>
3960 </glossdef>
3961 </glossentry>
3962
3963 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
3964 <glossdef>
3965 <para>
3966 Extra options passed to the
3967 <filename>make install</filename> command during the
3968 <filename>do_install</filename> task in order to specify
3969 parallel installation.
3970 This variable defaults to the value of
3971 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
3972 <note>
3973 Individual recipes might clear out this variable if
3974 the software being built has problems running its
3975 <filename>make install</filename> process in parallel.
3976 </note>
3977 </para>
3978 </glossdef>
3979 </glossentry>
3980
3981
3982
3983
3984PARALLEL_MAKEINST with the description ".
3985
3986
3987
3988
3989
3990 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
3991 <glossdef>
3992 <para>
3993 Determines the action to take when a patch fails.
3994 You can set this variable to one of two values: "noop" and
3995 "user".
3996 </para>
3997
3998 <para>
3999 The default value of "noop" causes the build to simply fail
4000 when the OpenEmbedded build system cannot successfully
4001 apply a patch.
4002 Setting the value to "user" causes the build system to
4003 launch a shell and places you in the right location so that
4004 you can manually resolve the conflicts.
4005 </para>
4006
4007 <para>
4008 Set this variable in your
4009 <filename>local.conf</filename> file.
4010 </para>
4011 </glossdef>
4012 </glossentry>
4013
4014 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
4015 <glossdef>
4016 <para>
4017 Specifies the utility used to apply patches for a recipe
4018 during <filename>do_patch</filename>.
4019 You can specify one of three utilities: "patch", "quilt", or
4020 "git".
4021 The default utility used is "quilt" except for the
4022 quilt-native recipe itself.
4023 Because the quilt tool is not available at the
4024 time quilt-native is being patched, it uses "patch".
4025 </para>
4026
4027 <para>
4028 If you wish to use an alternative patching tool, set the
4029 variable in the recipe using one of the following:
4030 <literallayout class='monospaced'>
4031 PATCHTOOL = "patch"
4032 PATCHTOOL = "quilt"
4033 PATCHTOOL = "git"
4034 </literallayout>
4035 </para>
4036 </glossdef>
4037 </glossentry>
4038
4039 <glossentry id='var-PE'><glossterm>PE</glossterm>
4040 <glossdef>
4041 <para>
4042 the epoch of the recipe.
4043 By default, this variable is unset.
4044 The field is used to make upgrades possible when the
4045 versioning scheme changes in some backwards incompatible
4046 way.
4047 </para>
4048 </glossdef>
4049 </glossentry>
4050
4051 <glossentry id='var-PF'><glossterm>PF</glossterm>
4052 <glossdef>
4053 <para>Specifies the recipe or package name and includes all version and revision
4054 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
4055 <filename>bash-4.2-r1/</filename>).
4056 This variable is comprised of the following:
4057 <literallayout class='monospaced'>
4058 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
4059 </literallayout></para>
4060 </glossdef>
4061 </glossentry>
4062
4063 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
4064 <glossdef>
4065 <para>
4066 Points to the destination directory for files to be
4067 packaged before they are split into individual packages.
4068 This directory defaults to the following:
4069 <literallayout class='monospaced'>
4070 ${WORKDIR}/package
4071 </literallayout>
4072 Do not change this default.
4073 </para>
4074 </glossdef>
4075 </glossentry>
4076
4077 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
4078 <glossdef>
4079 <para>
4080 Points to a shared, global-state directory that holds data
4081 generated during the packaging process.
4082 During the packaging process, the
4083 <filename>do_packagedata</filename> task packages
4084 data for each recipe and installs it into this temporary,
4085 shared area.
4086 </para>
4087 </glossdef>
4088 </glossentry>
4089
4090 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
4091 <glossdef>
4092 <para>
4093 Points to the parent directory for files to be packaged
4094 after they have been split into individual packages.
4095 This directory defaults to the following:
4096 <literallayout class='monospaced'>
4097 ${WORKDIR}/packages-split
4098 </literallayout>
4099 Under this directory, the build system creates
4100 directories for each package specified in
4101 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
4102 Do not change this default.
4103 </para>
4104 </glossdef>
4105 </glossentry>
4106
4107 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
4108 <glossdef>
4109 <para>
4110 Points to a temporary work area used by the
4111 <filename>do_package</filename> task to write output
4112 from the <filename>do_packagedata</filename> task.
4113 The <filename>PKGDESTWORK</filename> location defaults to
4114 the following:
4115 <literallayout class='monospaced'>
4116 ${WORKDIR}/pkgdata
4117 </literallayout>
4118 The <filename>do_packagedata</filename> task then packages
4119 the data in the temporary work area and installs it into a
4120 shared directory pointed to by
4121 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
4122 </para>
4123
4124 <para>
4125 Do not change this default.
4126 </para>
4127 </glossdef>
4128 </glossentry>
4129
4130 <glossentry id='var-PN'><glossterm>PN</glossterm>
4131 <glossdef>
4132 <para>This variable can have two separate functions depending on the context: a recipe
4133 name or a resulting package name.</para>
4134 <para><filename>PN</filename> refers to a recipe name in the context of a file used
4135 by the OpenEmbedded build system as input to create a package.
4136 The name is normally extracted from the recipe file name.
4137 For example, if the recipe is named
4138 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
4139 will be "expat".</para>
4140 <para>
4141 The variable refers to a package name in the context of a file created or produced by the
4142 OpenEmbedded build system.</para>
4143 <para>If applicable, the <filename>PN</filename> variable also contains any special
4144 suffix or prefix.
4145 For example, using <filename>bash</filename> to build packages for the native
4146 machine, <filename>PN</filename> is <filename>bash-native</filename>.
4147 Using <filename>bash</filename> to build packages for the target and for Multilib,
4148 <filename>PN</filename> would be <filename>bash</filename> and
4149 <filename>lib64-bash</filename>, respectively.
4150 </para>
4151 </glossdef>
4152 </glossentry>
4153
4154 <glossentry id='var-PR'><glossterm>PR</glossterm>
4155 <glossdef>
4156 <para>The revision of the recipe.
4157 The default value for this variable is "r0".
4158 </para>
4159 </glossdef>
4160 </glossentry>
4161
4162 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
4163 <glossdef>
4164 <para>
4165 If multiple recipes provide an item, this variable
4166 determines which recipe should be given preference.
4167 You should always suffix the variable with the name of the
4168 provided item, and you should set it to the
4169 <link linkend='var-PN'><filename>PN</filename></link>
4170 of the recipe to which you want to give precedence.
4171 Here is an example:
4172 <literallayout class='monospaced'>
4173 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
4174 </literallayout>
4175 </para>
4176 </glossdef>
4177 </glossentry>
4178
4179 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
4180 <glossdef>
4181 <para>
4182 If there are multiple versions of recipes available, this
4183 variable determines which recipe should be given preference.
4184 You must always suffix the variable with the
4185 <link linkend='var-PN'><filename>PN</filename></link>
4186 you want to select, and you should set to the
4187 <link linkend='var-PV'><filename>PV</filename></link>
4188 accordingly for precedence.
4189 You can use the "<filename>%</filename>" character as a
4190 wildcard to match any number of characters, which can be
4191 useful when specifying versions that contain long revision
4192 numbers that could potentially change.
4193 Here are two examples:
4194 <literallayout class='monospaced'>
4195 PREFERRED_VERSION_python = "2.6.6"
4196 PREFERRED_VERSION_linux-yocto = "3.0+git%"
4197 </literallayout>
4198 </para>
4199 </glossdef>
4200 </glossentry>
4201
4202 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
4203 <glossdef>
4204 <para>
4205 Specifies additional paths from which the OpenEmbedded
4206 build system gets source code.
4207 When the build system searches for source code, it first
4208 tries the local download directory.
4209 If that location fails, the build system tries locations
4210 defined by <filename>PREMIRRORS</filename>, the upstream
4211 source, and then locations specified by
4212 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
4213 in that order.
4214 </para>
4215
4216 <para>
4217 Assuming your distribution
4218 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
4219 is "poky", the default value for
4220 <filename>PREMIRRORS</filename> is defined in the
4221 <filename>conf/distro/poky.conf</filename> file in the
4222 <filename>meta-yocto</filename> Git repository.
4223 </para>
4224
4225 <para>
4226 Typically, you could add a specific server for the
4227 build system to attempt before any others by adding
4228 something like the following to the
4229 <filename>local.conf</filename> configuration file in the
4230 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
4231 <literallayout class='monospaced'>
4232 PREMIRRORS_prepend = "\
4233 git://.*/.* http://www.yoctoproject.org/sources/ \n \
4234 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
4235 http://.*/.* http://www.yoctoproject.org/sources/ \n \
4236 https://.*/.* http://www.yoctoproject.org/sources/ \n"
4237 </literallayout>
4238 These changes cause the build system to intercept
4239 Git, FTP, HTTP, and HTTPS requests and direct them to
4240 the <filename>http://</filename> sources mirror.
4241 You can use <filename>file://</filename> URLs to point
4242 to local directories or network shares as well.
4243 </para>
4244 </glossdef>
4245 </glossentry>
4246
4247 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
4248 <glossdef>
4249 <para>Causes the <link linkend='var-PR'><filename>PR</filename></link>
4250 variable of <filename>.bbappend</filename> files to
4251 dynamically increment.
4252 This increment minimizes the impact of layer ordering.</para>
4253 <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist,
4254 <filename>PRINC</filename> should be self referencing.
4255 This variable defaults to 0.</para>
4256 <para>Following is an example that increments <filename>PR</filename> by two:
4257 <literallayout class='monospaced'>
4258 PRINC := "${@int(PRINC) + 2}"
4259 </literallayout>
4260 It is advisable not to use strings such as ".= '.1'" with the variable because
4261 this usage is very sensitive to layer ordering.
4262 You should avoid explicit assignments as they cannot
4263 adequately represent multiple
4264 <filename>.bbappend</filename> files.</para>
4265 </glossdef>
4266 </glossentry>
4267
4268 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
4269 <glossdef>
4270 <para>
4271 A list of aliases that a recipe also provides.
4272 These aliases are useful for satisfying dependencies of
4273 other recipes during the build (as specified by
4274 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>).
4275 <note>
4276 A recipe's own
4277 <filename><link linkend='var-PN'>PN</link></filename>
4278 is implicitly already in its
4279 <filename>PROVIDES</filename> list.
4280 </note>
4281 </para>
4282 </glossdef>
4283 </glossentry>
4284
4285 <glossentry id='var-PV'><glossterm>PV</glossterm>
4286 <glossdef>
4287 <para>The version of the recipe.
4288 The version is normally extracted from the recipe filename.
4289 For example, if the recipe is named
4290 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
4291 will be "2.0.1".
4292 <filename>PV</filename> is generally not overridden within
4293 a recipe unless it is building an unstable (i.e. development) version from a source code repository
4294 (e.g. Git or Subversion).
4295 </para>
4296 </glossdef>
4297 </glossentry>
4298
4299 </glossdiv>
4300
4301<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
4302<!-- </glossdiv>-->
4303
4304 <glossdiv id='var-glossary-r'><title>R</title>
4305
4306 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
4307 <glossdef>
4308 <para>
4309 The list of packages that conflict with packages.
4310 Note that packages will not be installed if conflicting
4311 packages are not first removed.
4312 </para>
4313
4314 <para>
4315 Like all package-controlling variables, you must always use
4316 them in conjunction with a package name override.
4317 Here is an example:
4318 <literallayout class='monospaced'>
4319 RCONFLICTS_${PN} = "another-conflicting-package-name"
4320 </literallayout>
4321 </para>
4322
4323 <para>
4324 BitBake, which the OpenEmbedded build system uses, supports
4325 specifying versioned dependencies.
4326 Although the syntax varies depending on the packaging
4327 format, BitBake hides these differences from you.
4328 Here is the general syntax to specify versions with
4329 the <filename>RCONFLICTS</filename> variable:
4330 <literallayout class='monospaced'>
4331 RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4332 </literallayout>
4333 For <filename>operator</filename>, you can specify the
4334 following:
4335 <literallayout class='monospaced'>
4336 =
4337 &lt;
4338 &gt;
4339 &lt;=
4340 &gt;=
4341 </literallayout>
4342 For example, the following sets up a dependency on version
4343 1.2 or greater of the package <filename>foo</filename>:
4344 <literallayout class='monospaced'>
4345 RCONFLICTS_${PN} = "foo (>= 1.2)"
4346 </literallayout>
4347 </para>
4348 </glossdef>
4349 </glossentry>
4350
4351 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
4352 <glossdef>
4353 <para>
4354 Lists a package's runtime dependencies (i.e. other packages)
4355 that must be installed in order for the built package to run
4356 correctly.
4357 If a package in this list cannot be found during the build,
4358 you will get a build error.
4359 </para>
4360
4361 <para>
4362 When you use the <filename>RDEPENDS</filename> variable
4363 in a recipe, you are essentially stating that the recipe's
4364 <filename>do_build</filename> task depends on the existence
4365 of a specific package.
4366 Consider this simple example for two recipes named "a" and
4367 "b" that produce similarly named packages.
4368 In this example, the <filename>RDEPENDS</filename>
4369 statement appears in the "a" recipe:
4370 <literallayout class='monospaced'>
4371 RDEPENDS_${PN} = "b"
4372 </literallayout>
4373 Here, the dependency is such that the
4374 <filename>do_build</filename> task for recipe "a" depends
4375 on the <filename>do_package_write</filename> task
4376 of recipe "b".
4377 This means the package file for "b" must be available when
4378 the output for recipe "a" has been completely built.
4379 More importantly, package "a" will be marked as depending
4380 on package "b" in a manner that is understood by the
4381 package manager in use (i.e. rpm, opkg, or dpkg).
4382 </para>
4383
4384 <para>
4385 The names of the packages you list within
4386 <filename>RDEPENDS</filename> must be the names of other
4387 packages - they cannot be recipe names.
4388 Although package names and recipe names usually match,
4389 the important point here is that you are
4390 providing package names within the
4391 <filename>RDEPENDS</filename> variable.
4392 For an example of the default list of packages created from
4393 a recipe, see the
4394 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
4395 variable.
4396 </para>
4397
4398 <para>
4399 Because the <filename>RDEPENDS</filename> variable applies
4400 to packages being built, you should always use the variable
4401 in a form with an attached package name.
4402 For example, suppose you are building a development package
4403 that depends on the <filename>perl</filename> package.
4404 In this case, you would use the following
4405 <filename>RDEPENDS</filename> statement:
4406 <literallayout class='monospaced'>
4407 RDEPENDS_${PN}-dev += "perl"
4408 </literallayout>
4409 In the example, the development package depends on
4410 the <filename>perl</filename> package.
4411 Thus, the <filename>RDEPENDS</filename> variable has the
4412 <filename>${PN}-dev</filename> package name as part of the
4413 variable.
4414 </para>
4415
4416 <para>
4417 The package name you attach to the
4418 <filename>RDEPENDS</filename> variable must appear
4419 as it would in the <filename>PACKAGES</filename>
4420 namespace before any renaming of the output package by
4421 classes like <filename>debian.bbclass</filename>.
4422 </para>
4423
4424 <para>
4425 In many cases you do not need to explicitly add
4426 runtime dependencies using
4427 <filename>RDEPENDS</filename> since some automatic
4428 handling occurs:
4429 <itemizedlist>
4430 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
4431 a runtime package contains a shared library
4432 (<filename>.so</filename>), the build
4433 processes the library in order to determine other
4434 libraries to which it is dynamically linked.
4435 The build process adds these libraries to
4436 <filename>RDEPENDS</filename> when creating the runtime
4437 package.</para></listitem>
4438 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
4439 the package ships a <filename>pkg-config</filename>
4440 information file, the build process uses this file
4441 to add items to the <filename>RDEPENDS</filename>
4442 variable to create the runtime packages.
4443 </para></listitem>
4444 </itemizedlist>
4445 </para>
4446
4447 <para>
4448 BitBake, which the OpenEmbedded build system uses, supports
4449 specifying versioned dependencies.
4450 Although the syntax varies depending on the packaging
4451 format, BitBake hides these differences from you.
4452 Here is the general syntax to specify versions with
4453 the <filename>RDEPENDS</filename> variable:
4454 <literallayout class='monospaced'>
4455 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4456 </literallayout>
4457 For <filename>operator</filename>, you can specify the
4458 following:
4459 <literallayout class='monospaced'>
4460 =
4461 &lt;
4462 &gt;
4463 &lt;=
4464 &gt;=
4465 </literallayout>
4466 For example, the following sets up a dependency on version
4467 1.2 or greater of the package <filename>foo</filename>:
4468 <literallayout class='monospaced'>
4469 RDEPENDS_${PN} = "foo (>= 1.2)"
4470 </literallayout>
4471 </para>
4472
4473 <para>
4474 For information on build-time dependencies, see the
4475 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
4476 variable.
4477 </para>
4478 </glossdef>
4479 </glossentry>
4480
4481 <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
4482 <glossdef>
4483 <para>
4484 Reclaims disk space by removing previously built
4485 versions of the same image from the
4486 <filename>images</filename> directory pointed to by the
4487 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
4488 variable.
4489 </para>
4490
4491 <para>
4492 Set this variable to "1" in your
4493 <filename>local.conf</filename> file to remove these
4494 images.
4495 </para>
4496 </glossdef>
4497 </glossentry>
4498
4499 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
4500 <glossdef>
4501 <para>
4502 With <filename>rm_work</filename> enabled, this
4503 variable specifies a list of recipes whose work directories
4504 should not be removed.
4505 See the "<link linkend='ref-classes-rm-work'>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></link>"
4506 section for more details.
4507 </para>
4508 </glossdef>
4509 </glossentry>
4510
4511 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
4512 <glossdef>
4513 <para>
4514 Added by classes to run post processing commands once the
4515 OpenEmbedded build system has created the root filesystem.
4516 You can specify shell commands separated by semicolons:
4517 <literallayout class='monospaced'>
4518 ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
4519 </literallayout>
4520 If you need to pass the path to the root filesystem within
4521 the command, you can use
4522 <filename>${IMAGE_ROOTFS}</filename>, which points to
4523 the root filesystem image.
4524 </para>
4525 </glossdef>
4526 </glossentry>
4527
4528 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
4529 <glossdef>
4530 <para>
4531 A list of package name aliases that a package also provides.
4532 These aliases are useful for satisfying runtime dependencies
4533 of other packages both during the build and on the target
4534 (as specified by
4535 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
4536 <note>
4537 A package's own name is implicitly already in its
4538 <filename>RPROVIDES</filename> list.
4539 </note>
4540 </para>
4541 <para>
4542 As with all package-controlling variables, you must always
4543 use the variable in conjunction with a package name override.
4544 Here is an example:
4545 <literallayout class='monospaced'>
4546 RPROVIDES_${PN} = "widget-abi-2"
4547 </literallayout>
4548 </para>
4549 </glossdef>
4550 </glossentry>
4551
4552 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
4553 <glossdef>
4554 <para>
4555 A list of packages that extends the usability of a package
4556 being built.
4557 The package being built does not depend on this list of
4558 packages in order to successfully build, but needs them for
4559 the extended usability.
4560 To specify runtime dependencies for packages, see the
4561 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
4562 variable.
4563 </para>
4564
4565 <para>
4566 The OpenEmbedded build process automatically installs the
4567 list of packages as part of the built package.
4568 However, you can remove these packages later if you want.
4569 If, during the build, a package from the
4570 <filename>RRECOMMENDS</filename> list cannot be
4571 found, the build process continues without an error.
4572 </para>
4573
4574 <para>
4575 You can also prevent packages in the list from being
4576 installed by using several variables.
4577 See the
4578 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
4579 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
4580 and
4581 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
4582 variables for more information.
4583 </para>
4584
4585 <para>
4586 Because the <filename>RRECOMMENDS</filename> variable
4587 applies to packages being built, you should always attach
4588 an override to the variable to specify the particular
4589 package whose usability is being extended.
4590 For example, suppose you are building a development package
4591 that is extended to support wireless functionality.
4592 In this case, you would use the following:
4593 <literallayout class='monospaced'>
4594 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
4595 </literallayout>
4596 In the example, the package name
4597 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
4598 must appear as it would in the
4599 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
4600 namespace before any renaming of the output package by
4601 classes such as <filename>debian.bbclass</filename>.
4602 </para>
4603
4604 <para>
4605 BitBake, which the OpenEmbedded build system uses, supports
4606 specifying versioned recommends.
4607 Although the syntax varies depending on the packaging
4608 format, BitBake hides these differences from you.
4609 Here is the general syntax to specify versions with
4610 the <filename>RRECOMMENDS</filename> variable:
4611 <literallayout class='monospaced'>
4612 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4613 </literallayout>
4614 For <filename>operator</filename>, you can specify the
4615 following:
4616 <literallayout class='monospaced'>
4617 =
4618 &lt;
4619 &gt;
4620 &lt;=
4621 &gt;=
4622 </literallayout>
4623 For example, the following sets up a recommend on version
4624 1.2 or greater of the package <filename>foo</filename>:
4625 <literallayout class='monospaced'>
4626 RRECOMMENDS_${PN} = "foo (>= 1.2)"
4627 </literallayout>
4628 </para>
4629 </glossdef>
4630 </glossentry>
4631
4632 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
4633 <glossdef>
4634 <para>
4635 A list of packages replaced by a package.
4636 The package manager uses this variable to determine which
4637 package should be installed to replace other package(s)
4638 during an upgrade.
4639 In order to also have the other package(s) removed at the
4640 same time, you must add the name of the other
4641 package to the
4642 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
4643 </para>
4644 <para>
4645 As with all package-controlling variables, you must use
4646 this variable in conjunction with a package name
4647 override.
4648 Here is an example:
4649 <literallayout class='monospaced'>
4650 RREPLACES_${PN} = "other-package-being-replaced"
4651 </literallayout>
4652 </para>
4653
4654 <para>
4655 BitBake, which the OpenEmbedded build system uses, supports
4656 specifying versioned replacements.
4657 Although the syntax varies depending on the packaging
4658 format, BitBake hides these differences from you.
4659 Here is the general syntax to specify versions with
4660 the <filename>RREPLACES</filename> variable:
4661 <literallayout class='monospaced'>
4662 RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4663 </literallayout>
4664 For <filename>operator</filename>, you can specify the
4665 following:
4666 <literallayout class='monospaced'>
4667 =
4668 &lt;
4669 &gt;
4670 &lt;=
4671 &gt;=
4672 </literallayout>
4673 For example, the following sets up a replacement using
4674 version 1.2 or greater of the package
4675 <filename>foo</filename>:
4676 <literallayout class='monospaced'>
4677 RREPLACES_${PN} = "foo (>= 1.2)"
4678 </literallayout>
4679 </para>
4680 </glossdef>
4681 </glossentry>
4682
4683 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
4684 <glossdef>
4685 <para>
4686 A list of additional packages that you can suggest for
4687 installation by the package manager at the time a package
4688 is installed.
4689 Not all package managers support this functionality.
4690 </para>
4691 <para>
4692 As with all package-controlling variables, you must always
4693 use this variable in conjunction with a package name
4694 override.
4695 Here is an example:
4696 <literallayout class='monospaced'>
4697 RSUGGESTS_${PN} = "useful-package another-package"
4698 </literallayout>
4699 </para>
4700 </glossdef>
4701 </glossentry>
4702
4703 </glossdiv>
4704
4705 <glossdiv id='var-glossary-s'><title>S</title>
4706
4707 <glossentry id='var-S'><glossterm>S</glossterm>
4708 <glossdef>
4709 <para>
4710 The location in the
4711 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
4712 where unpacked recipe source code resides.
4713 This location is within the working directory
4714 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
4715 which is not static.
4716 The unpacked source location depends on the recipe name
4717 (<filename><link linkend='var-PN'>PN</link></filename>) and
4718 recipe version
4719 (<filename><link linkend='var-PV'>PV</link></filename>) as
4720 follows:
4721 <literallayout class='monospaced'>
4722 ${WORKDIR}/${PN}-${PV}
4723 </literallayout>
4724 As an example, assume a
4725 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4726 top-level folder named <filename>poky</filename> and a
4727 default Build Directory at <filename>poky/build</filename>.
4728 In this case, the working directory the build system uses
4729 to keep the unpacked recipe for <filename>db</filename>
4730 is the following:
4731 <literallayout class='monospaced'>
4732 ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
4733 </literallayout>
4734 </para>
4735 </glossdef>
4736 </glossentry>
4737
4738 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
4739 <glossdef>
4740 <para>
4741 A list of the host distribution identifiers that the
4742 build system has been tested against.
4743 Identifiers consist of the host distributor ID
4744 followed by the release,
4745 as reported by the <filename>lsb_release</filename> tool
4746 or as read from <filename>/etc/lsb-release</filename>.
4747 Separate the list items with explicit newline
4748 characters (<filename>\n</filename>).
4749 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
4750 and the current value of
4751 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
4752 does not appear in the list, then the build system reports
4753 a warning that indicates the current host distribution has
4754 not been tested as a build host.
4755 </para>
4756 </glossdef>
4757 </glossentry>
4758
4759 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
4760 <glossdef>
4761 <para>
4762 The target architecture for the SDK.
4763 Typically, you do not directly set this variable.
4764 Instead, use
4765 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
4766 </para>
4767 </glossdef>
4768 </glossentry>
4769
4770 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
4771 <glossdef>
4772 <para>
4773 The base name for SDK output files.
4774 The name is derived from the
4775 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
4776 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
4777 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
4778 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
4779 and
4780 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
4781 variables:
4782 <literallayout class='monospaced'>
4783 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
4784 </literallayout>
4785 </para>
4786 </glossdef>
4787 </glossentry>
4788
4789 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
4790 <glossdef>
4791 <para>Equivalent to
4792 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
4793 However, this variable applies to the SDK generated from an
4794 image using the following command:
4795 <literallayout class='monospaced'>
4796 $ bitbake -c populate_sdk imagename
4797 </literallayout>
4798 </para>
4799 </glossdef>
4800 </glossentry>
4801
4802 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
4803 <glossdef>
4804 <para>
4805 The architecture of the machine that runs Application
4806 Development Toolkit (ADT) items.
4807 In other words, packages are built so that they will run
4808 on the target you specify with the argument.
4809 This implies that you can build out ADT/SDK items that
4810 run on an architecture other than that of your build host.
4811 For example, you can use an x86_64-based build host to
4812 create packages that will run on an i686-based
4813 SDK Machine.
4814 </para>
4815
4816 <para>
4817 You can use "i686" and "x86_64" as possible values for this
4818 variable.
4819 The variable defaults to "i686" and is set in the
4820 <filename>local.conf</filename> file in the
4821 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
4822 <literallayout class='monospaced'>
4823 SDKMACHINE ?= "i686"
4824 </literallayout>
4825 </para>
4826 </glossdef>
4827 </glossentry>
4828
4829 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
4830 <glossdef>
4831 <para>The section in which packages should be categorized.
4832 Package management utilities can make use of this variable.</para>
4833 </glossdef>
4834 </glossentry>
4835
4836 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
4837 <glossdef>
4838 <para>
4839 The variable takes the value of
4840 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
4841 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
4842 In this case the value of
4843 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
4844 </para>
4845 </glossdef>
4846 </glossentry>
4847
4848 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
4849 <glossdef>
4850 <para>
4851 Defines a serial console (TTY) to enable using getty.
4852 Provide a value that specifies the baud rate followed by
4853 the TTY device name separated by a space.
4854 You cannot specify more than one TTY device:
4855 <literallayout class='monospaced'>
4856 SERIAL_CONSOLE = "115200 ttyS0"
4857 </literallayout>
4858 <note>
4859 The <filename>SERIAL_CONSOLE</filename> variable
4860 is deprecated.
4861 Please use the
4862 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
4863 variable.
4864 </note>
4865 </para>
4866 </glossdef>
4867 </glossentry>
4868
4869 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
4870 <glossdef>
4871 <para>
4872 Defines the serial consoles (TTYs) to enable using getty.
4873 Provide a value that specifies the baud rate followed by
4874 the TTY device name separated by a semicolon.
4875 Use spaces to separate multiple devices:
4876 <literallayout class='monospaced'>
4877 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
4878 </literallayout>
4879 </para>
4880 </glossdef>
4881 </glossentry>
4882
4883 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
4884 <glossdef>
4885 <para>
4886 Similar to
4887 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
4888 except the device is checked for existence before attempting
4889 to enable it.
4890 This variable is currently only supported with SysVinit
4891 (i.e. not with systemd).
4892 </para>
4893 </glossdef>
4894 </glossentry>
4895
4896 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
4897 <glossdef>
4898 <para>
4899 A list of recipe dependencies that should not be used to
4900 determine signatures of tasks from one recipe when they
4901 depend on tasks from another recipe.
4902 For example:
4903 <literallayout class='monospaced'>
4904 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
4905 </literallayout>
4906 In this example, <filename>intone</filename> depends on
4907 <filename>mplayer2</filename>.
4908 </para>
4909
4910 <para>
4911 Use of this variable is one mechanism to remove dependencies
4912 that affect task signatures and thus force rebuilds when a
4913 recipe changes.
4914 <caution>
4915 If you add an inappropriate dependency for a recipe
4916 relationship, the software might break during
4917 runtime if the interface of the second recipe was
4918 changed after the first recipe had been built.
4919 </caution>
4920 </para>
4921 </glossdef>
4922 </glossentry>
4923
4924 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
4925 <glossdef>
4926 <para>
4927 A list of recipes that are completely stable and will
4928 never change.
4929 The ABI for the recipes in the list are presented by
4930 output from the tasks run to build the recipe.
4931 Use of this variable is one way to remove dependencies from
4932 one recipe on another that affect task signatures and
4933 thus force rebuilds when the recipe changes.
4934 <caution>
4935 If you add an inappropriate variable to this list,
4936 the software might break at runtime if the
4937 interface of the recipe was changed after the other
4938 had been built.
4939 </caution>
4940 </para>
4941 </glossdef>
4942 </glossentry>
4943
4944 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
4945 <glossdef>
4946 <para>
4947 Specifies the number of bits for the target system CPU.
4948 The value should be either "32" or "64".
4949 </para>
4950 </glossdef>
4951 </glossentry>
4952
4953 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
4954 <glossdef>
4955 <para>
4956 Specifies the endian byte order of the target system.
4957 The value should be either "le" for little-endian or "be" for big-endian.
4958 </para>
4959 </glossdef>
4960 </glossentry>
4961
4962 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
4963 <glossdef>
4964 <para>
4965 Groups together machines based upon the same family
4966 of SOC (System On Chip).
4967 You typically set this variable in a common
4968 <filename>.inc</filename> file that you include in the
4969 configuration files of all the machines.
4970 <note>
4971 You must include
4972 <filename>conf/machine/include/soc-family.inc</filename>
4973 for this variable to appear in
4974 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
4975 </note>
4976 </para>
4977 </glossdef>
4978 </glossentry>
4979
4980 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
4981 <glossdef>
4982 <para>
4983 Defines the suffix for shared libraries used on the
4984 target platform.
4985 By default, this suffix is ".so.*" for all Linux-based
4986 systems and is defined in the
4987 <filename>meta/conf/bitbake.conf</filename> configuration
4988 file.
4989 </para>
4990
4991 <para>
4992 You will see this variable referenced in the default values
4993 of <filename>FILES_${PN}</filename>.
4994 </para>
4995 </glossdef>
4996 </glossentry>
4997
4998 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
4999 <glossdef>
5000 <para>
5001 Defines the suffix for the development symbolic link
5002 (symlink) for shared libraries on the target platform.
5003 By default, this suffix is ".so" for Linux-based
5004 systems and is defined in the
5005 <filename>meta/conf/bitbake.conf</filename> configuration
5006 file.
5007 </para>
5008
5009 <para>
5010 You will see this variable referenced in the default values
5011 of <filename>FILES_${PN}-dev</filename>.
5012 </para>
5013 </glossdef>
5014 </glossentry>
5015
5016 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
5017 <glossdef>
5018 <para>
5019 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
5020 OpenEmbedded build system to create variants of recipes or packages.
5021 The list specifies the prefixes to strip off during certain circumstances
5022 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
5023 </para>
5024 </glossdef>
5025 </glossentry>
5026
5027 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
5028 <glossdef>
5029 <para>The list of source files - local or remote.
5030 This variable tells the OpenEmbedded build system which bits
5031 to pull in for the build and how to pull them in.
5032 For example, if the recipe or append file only needs to
5033 fetch a tarball from the Internet, the recipe or
5034 append file uses a single <filename>SRC_URI</filename>
5035 entry.
5036 On the other hand, if the recipe or append file needs to
5037 fetch a tarball, apply two patches, and include a custom
5038 file, the recipe or append file would include four
5039 instances of the variable.</para>
5040 <para>The following list explains the available URI protocols:
5041 <itemizedlist>
5042 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
5043 Fetches files, which are usually files shipped with
5044 the
5045 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
5046 from the local machine.
5047 The path is relative to the
5048 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
5049 variable.
5050 Thus, the build system searches, in order, from the
5051 following directories, which are assumed to be a
5052 subdirectories of the directory in which the
5053 recipe file (<filename>.bb</filename>) or
5054 append file (<filename>.bbappend</filename>)
5055 resides:
5056 <itemizedlist>
5057 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
5058 The base recipe name without any special
5059 suffix or version numbers.
5060 </para></listitem>
5061 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
5062 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
5063 The base recipe name and version but without
5064 any special package name suffix.
5065 </para></listitem>
5066 <listitem><para><emphasis>files -</emphasis>
5067 Files within a directory, which is named
5068 <filename>files</filename> and is also
5069 alongside the recipe or append file.
5070 </para></listitem>
5071 </itemizedlist>
5072 <note>
5073 If you want the build system to pick up files
5074 specified through a
5075 <filename>SRC_URI</filename>
5076 statement from your append file, you need to be
5077 sure to extend the
5078 <filename>FILESPATH</filename>
5079 variable by also using the
5080 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
5081 variable from within your append file.
5082 </note>
5083 </para></listitem>
5084 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
5085 Bazaar revision control repository.</para></listitem>
5086 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
5087 Git revision control repository.</para></listitem>
5088 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
5089 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
5090 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
5091 a repo (Git) repository.</para></listitem>
5092 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
5093 an SVK revision control repository.</para></listitem>
5094 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
5095 the Internet using <filename>http</filename>.</para></listitem>
5096 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
5097 from the Internet using <filename>https</filename>.</para></listitem>
5098 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
5099 from the Internet using <filename>ftp</filename>.</para></listitem>
5100 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
5101 a CVS revision control repository.</para></listitem>
5102 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
5103 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
5104 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
5105 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
5106 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
5107 a secure shell.</para></listitem>
5108 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
5109 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
5110 </itemizedlist>
5111 </para>
5112 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
5113 Here are standard options:
5114 <itemizedlist>
5115 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
5116 the patch or not.
5117 The default action is to apply the patch.</para></listitem>
5118 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
5119 striplevel to use when applying the patch.
5120 The default level is 1.</para></listitem>
5121 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
5122 the directory in which the patch should be applied.
5123 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
5124 </para></listitem>
5125 </itemizedlist>
5126 </para>
5127 <para>Here are options specific to recipes building code from a revision control system:
5128 <itemizedlist>
5129 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
5130 Apply the patch only if
5131 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
5132 is equal to or greater than <filename>mindate</filename>.
5133 </para></listitem>
5134 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
5135 Apply the patch only if <filename>SRCDATE</filename>
5136 is not later than <filename>mindate</filename>.
5137 </para></listitem>
5138 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
5139 Apply the patch only if <filename>SRCREV</filename>
5140 is equal to or greater than <filename>minrev</filename>.
5141 </para></listitem>
5142 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
5143 Apply the patch only if <filename>SRCREV</filename>
5144 is not later than <filename>maxrev</filename>.
5145 </para></listitem>
5146 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
5147 Apply the patch only if <filename>SRCREV</filename>
5148 is equal to <filename>rev</filename>.
5149 </para></listitem>
5150 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
5151 Apply the patch only if <filename>SRCREV</filename>
5152 is not equal to <filename>rev</filename>.
5153 </para></listitem>
5154 </itemizedlist>
5155 </para>
5156 <para>Here are some additional options worth mentioning:
5157 <itemizedlist>
5158 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
5159 whether or not to unpack the file if it is an archive.
5160 The default action is to unpack the file.</para></listitem>
5161 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
5162 (or extracts its contents) into the specified
5163 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
5164 This option is useful for unusual tarballs or other archives that
5165 do not have their files already in a subdirectory within the archive.
5166 </para></listitem>
5167 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
5168 name to be used for association with <filename>SRC_URI</filename> checksums
5169 when you have more than one file specified in <filename>SRC_URI</filename>.
5170 </para></listitem>
5171 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
5172 the filename used when storing the downloaded file.</para></listitem>
5173 </itemizedlist>
5174 </para>
5175 </glossdef>
5176 </glossentry>
5177
5178 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
5179 <glossdef>
5180 <para></para>
5181 <para>
5182 By default, the OpenEmbedded build system automatically detects whether
5183 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
5184 contains files that are machine-specific.
5185 If so, the build system automatically changes
5186 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
5187 Setting this variable to "0" disables this behavior.
5188 </para>
5189 </glossdef>
5190 </glossentry>
5191
5192 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
5193 <glossdef>
5194 <para>
5195 The date of the source code used to build the package.
5196 This variable applies only if the source was fetched from a Source Code Manager (SCM).
5197 </para>
5198 </glossdef>
5199 </glossentry>
5200
5201 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
5202 <glossdef>
5203 <para>
5204 Returns the version string of the current package.
5205 This string is used to help define the value of
5206 <link linkend='var-PV'><filename>PV</filename></link>.
5207 </para>
5208
5209 <para>
5210 The <filename>SRCPV</filename> variable is defined in the
5211 <filename>meta/conf/bitbake.conf</filename> configuration
5212 file in the
5213 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
5214 as follows:
5215 <literallayout class='monospaced'>
5216 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
5217 </literallayout>
5218 </para>
5219
5220 <para>
5221 Recipes that need to define <filename>PV</filename> do so
5222 with the help of the <filename>SRCPV</filename>.
5223 For example, the <filename>ofono</filename> recipe
5224 (<filename>ofono_git.bb</filename>) located in
5225 <filename>meta/recipes-connectivity</filename> in the
5226 Source Directory defines <filename>PV</filename> as
5227 follows:
5228 <literallayout class='monospaced'>
5229 PV = "1.5.0+git${SRCPV}"
5230 </literallayout>
5231 </para>
5232 </glossdef>
5233 </glossentry>
5234
5235 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
5236 <glossdef>
5237 <para>
5238 The revision of the source code used to build the package.
5239 This variable applies to Subversion, Git, Mercurial and Bazaar
5240 only.
5241 Note that if you wish to build a fixed revision and you wish
5242 to avoid performing a query on the remote repository every time
5243 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
5244 full revision identifier and not just a tag.
5245 </para>
5246 </glossdef>
5247 </glossentry>
5248
5249 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
5250 <glossdef>
5251 <para>The directory for the shared state cache.</para>
5252 </glossdef>
5253 </glossentry>
5254
5255 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
5256 <glossdef>
5257 <para>
5258 Configures the OpenEmbedded build system to search other
5259 mirror locations for prebuilt cache data objects before
5260 building out the data.
5261 This variable works like fetcher
5262 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
5263 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
5264 and points to the cache locations to check for the shared
5265 objects.
5266 </para>
5267
5268 <para>
5269 You can specify a filesystem directory or a remote URL such
5270 as HTTP or FTP.
5271 The locations you specify need to contain the shared state
5272 cache (sstate-cache) results from previous builds.
5273 The sstate-cache you point to can also be from builds on
5274 other machines.
5275 </para>
5276
5277 <para>
5278 If a mirror uses the same structure as
5279 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
5280 you need to add
5281 "PATH" at the end as shown in the examples below.
5282 The build system substitutes the correct path within the
5283 directory structure.
5284 <literallayout class='monospaced'>
5285 SSTATE_MIRRORS ?= "\
5286 file://.* http://someserver.tld/share/sstate/PATH \n \
5287 file://.* file:///some/local/dir/sstate/PATH"
5288 </literallayout>
5289 </para>
5290 </glossdef>
5291 </glossentry>
5292
5293 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
5294 <glossdef>
5295 <para>
5296 The directory with kernel headers that are required to build out-of-tree
5297 modules.
5298 </para>
5299 </glossdef>
5300 </glossentry>
5301
5302 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
5303 <glossdef>
5304 <para>
5305 Specifies the base path used to create recipe stamp files.
5306 The path to an actual stamp file is constructed by evaluating this
5307 string and then appending additional information.
5308 Currently, the default assignment for <filename>STAMP</filename>
5309 as set in the <filename>meta/conf/bitbake.conf</filename> file
5310 is:
5311 <literallayout class='monospaced'>
5312 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
5313 </literallayout>
5314 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
5315 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
5316 <link linkend='var-PN'><filename>PN</filename></link>,
5317 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
5318 <link linkend='var-PV'><filename>PV</filename></link>, and
5319 <link linkend='var-PR'><filename>PR</filename></link> for related variable
5320 information.
5321 </para>
5322 </glossdef>
5323 </glossentry>
5324
5325 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
5326 <glossdef>
5327 <para>
5328 Specifies the base directory in which the OpenEmbedded
5329 build system places stamps.
5330 The default directory is
5331 <filename>${TMPDIR}/stamps</filename>.
5332 </para>
5333 </glossdef>
5334 </glossentry>
5335
5336 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
5337 <glossdef>
5338 <para>The short (72 characters or less) summary of the binary package for packaging
5339 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
5340 <filename>dpkg</filename>.
5341 By default, <filename>SUMMARY</filename> is used to define
5342 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
5343 variable if <filename>DESCRIPTION</filename> is not set
5344 in the recipe.
5345 </para>
5346 </glossdef>
5347 </glossentry>
5348
5349 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
5350 <glossdef>
5351 <para>
5352 A list of functions to execute after files are staged into
5353 the sysroot.
5354 These functions are usually used to apply additional
5355 processing on the staged files, or to stage additional
5356 files.
5357 </para>
5358 </glossdef>
5359 </glossentry>
5360
5361 </glossdiv>
5362
5363 <glossdiv id='var-glossary-t'><title>T</title>
5364
5365 <glossentry id='var-T'><glossterm>T</glossterm>
5366 <glossdef>
5367 <para>This variable points to a directory were BitBake places
5368 temporary files, which consist mostly of task logs and
5369 scripts, when building a particular recipe.
5370 The variable is typically set as follows:
5371 <literallayout class='monospaced'>
5372 T = "${WORKDIR}/temp"
5373 </literallayout>
5374 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
5375 is the directory into which BitBake unpacks and builds the
5376 recipe.
5377 The default <filename>bitbake.conf</filename> file sets this variable.</para>
5378 <para>The <filename>T</filename> variable is not to be confused with
5379 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
5380 which points to the root of the directory tree where BitBake
5381 places the output of an entire build.
5382 </para>
5383 </glossdef>
5384 </glossentry>
5385
5386 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
5387 <glossdef>
5388 <para>
5389 The target machine's architecture.
5390 The OpenEmbedded build system supports many
5391 architectures.
5392 Here is an example list of architectures supported.
5393 This list is by no means complete as the architecture
5394 is configurable:
5395 <literallayout class='monospaced'>
5396 arm
5397 i586
5398 x86_64
5399 powerpc
5400 powerpc64
5401 mips
5402 mipsel
5403 </literallayout>
5404 </para>
5405 </glossdef>
5406 </glossentry>
5407
5408 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
5409 <glossdef>
5410 <para>
5411 Flags passed to the C compiler for the target system.
5412 This variable evaluates to the same as
5413 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
5414 </para>
5415 </glossdef>
5416 </glossentry>
5417
5418
5419 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
5420 <glossdef>
5421 <para>Specifies the method for handling FPU code.
5422 For FPU-less targets, which include most ARM CPUs, the variable must be
5423 set to "soft".
5424 If not, the kernel emulation gets used, which results in a performance penalty.</para>
5425 </glossdef>
5426 </glossentry>
5427
5428 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
5429 <glossdef>
5430 <para>Specifies the target's operating system.
5431 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
5432 to "linux-uclibc" for <filename>uclibc</filename>.
5433 For ARM/EABI targets, there are also "linux-gnueabi" and
5434 "linux-uclibc-gnueabi" values possible.</para>
5435 </glossdef>
5436 </glossentry>
5437
5438 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
5439 <glossdef>
5440 <para>
5441 Specifies which variant of the GNU standard C library (<filename>libc</filename>)
5442 to use during the build process.
5443 This variable replaces <filename>POKYLIBC</filename>, which is no longer
5444 supported.
5445 </para>
5446 <para>
5447 You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
5448 <note>
5449 This release of the Yocto Project does not support the
5450 <filename>glibc</filename> implementation of <filename>libc</filename>.
5451 </note>
5452 </para>
5453 </glossdef>
5454 </glossentry>
5455
5456 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
5457 <glossdef>
5458 <para>
5459 The toolchain selector.
5460 This variable replaces <filename>POKYMODE</filename>, which is no longer
5461 supported.
5462 </para>
5463 <para>
5464 The <filename>TCMODE</filename> variable selects the external toolchain
5465 built using the OpenEmbedded build system or a few supported combinations of
5466 the upstream GCC or CodeSourcery Labs toolchain.
5467 The variable identifies the <filename>tcmode-*</filename> files used in
5468 the <filename>meta/conf/distro/include</filename> directory, which is found in the
5469 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5470 </para>
5471 <para>
5472 By default, <filename>TCMODE</filename> is set to "default", which
5473 chooses the <filename>tcmode-default.inc</filename> file.
5474 The variable is similar to
5475 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
5476 the variant of the GNU standard C library (<filename>libc</filename>)
5477 used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
5478 </para>
5479 </glossdef>
5480 </glossentry>
5481
5482 <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
5483 <glossdef>
5484 <para>
5485 Automatically runs the series of automated tests for
5486 images when an image is successfully built.
5487 <note>
5488 Currently, there is only support for running these tests
5489 under QEMU.
5490 </note>
5491 These tests are written in Python making use of the
5492 <filename>unittest</filename> module, and the majority of
5493 them run commands on the target system over
5494 <filename>ssh</filename>.
5495 You can set this variable to "1" in your
5496 <filename>local.conf</filename> file in the
5497 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
5498 to have the OpenEmbedded build system automatically run
5499 these tests after an image successfully builds:
5500 <literallayout class='monospaced'>
5501 TEST_IMAGE = "1"
5502 </literallayout>
5503 For more information on enabling, running, and writing
5504 these tests, see the
5505 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5506 section in the Yocto Project Development Manual and the
5507 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
5508 section.
5509 </para>
5510 </glossdef>
5511 </glossentry>
5512
5513 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
5514 <glossdef>
5515 <para>
5516 The time in seconds allowed for an image to boot before
5517 automated runtime tests begin to run against an
5518 image.
5519 The default timeout period to allow the boot process to
5520 reach the login prompt is 500 seconds.
5521 You can specify a different value in the
5522 <filename>local.conf</filename> file.
5523 </para>
5524
5525 <para>
5526 For more information on testing images, see the
5527 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5528 section in the Yocto Project Development Manual.
5529 </para>
5530 </glossdef>
5531 </glossentry>
5532
5533 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
5534 <glossdef>
5535 <para>
5536 An ordered list of tests (modules) to run against
5537 an image when performing automated runtime testing.
5538 </para>
5539
5540 <para>
5541 The OpenEmbedded build system provides a core set of tests
5542 that can be used against images.
5543 <note>
5544 Currently, there is only support for running these tests
5545 under QEMU.
5546 </note>
5547 Tests include <filename>ping</filename>,
5548 <filename>ssh</filename>, <filename>df</filename> among
5549 others.
5550 You can add your own tests to the list of tests by
5551 appending <filename>TEST_SUITES</filename> as follows:
5552 <literallayout class='monospaced'>
5553 TEST_SUITES_append = " mytest"
5554 </literallayout>
5555 Alternatively, you can provide the "auto" option to
5556 have all applicable tests run against the image.
5557 <literallayout class='monospaced'>
5558 TEST_SUITES_append = " auto"
5559 </literallayout>
5560 Using this option causes the build system to automatically
5561 run tests that are applicable to the image.
5562 Tests that are not applicable are skipped.
5563 </para>
5564
5565 <para>
5566 The order in which tests are run is important.
5567 Tests that depend on another test must appear later in the
5568 list than the test on which they depend.
5569 For example, if you append the list of tests with two
5570 tests (<filename>test_A</filename> and
5571 <filename>test_B</filename>) where
5572 <filename>test_B</filename> is dependent on
5573 <filename>test_A</filename>, then you must order the tests
5574 as follows:
5575 <literallayout class='monospaced'>
5576 TEST_SUITES = " test_A test_B"
5577 </literallayout>
5578 </para>
5579
5580 <para>
5581 For more information on testing images, see the
5582 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5583 section in the Yocto Project Development Manual.
5584 </para>
5585 </glossdef>
5586 </glossentry>
5587
5588 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
5589 <glossdef>
5590 <para>
5591 The directory in which the file BitBake is currently
5592 parsing is located.
5593 Do not manually set this variable.
5594 </para>
5595 </glossdef>
5596 </glossentry>
5597
5598 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
5599 <glossdef>
5600 <para>
5601 This variable is the base directory the OpenEmbedded
5602 build system uses for all build output and intermediate
5603 files (other than the shared state cache).
5604 By default, the <filename>TMPDIR</filename> variable points
5605 to <filename>tmp</filename> within the
5606 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
5607 </para>
5608
5609 <para>
5610 If you want to establish this directory in a location other
5611 than the default, you can uncomment and edit the following
5612 statement in the
5613 <filename>conf/local.conf</filename> file in the
5614 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
5615 <literallayout class='monospaced'>
5616 #TMPDIR = "${TOPDIR}/tmp"
5617 </literallayout>
5618 </para>
5619 </glossdef>
5620 </glossentry>
5621
5622 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
5623 <glossdef>
5624 <para>
5625 This variable lists packages the OpenEmbedded build system
5626 uses when building an SDK, which contains a
5627 cross-development environment.
5628 The packages specified by this variable are part of the
5629 toolchain set that runs on the
5630 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
5631 and each package should usually have the prefix
5632 "nativesdk-".
5633 When building an SDK using
5634 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
5635 a default list of packages is set in this variable, but
5636 you can add additional packages to the list.
5637 </para>
5638
5639 <para>
5640 For background information on cross-development toolchains
5641 in the Yocto Project development environment, see the
5642 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
5643 section.
5644 For information on setting up a cross-development
5645 environment, see the
5646 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
5647 section in the Yocto Project Application Developer's Guide.
5648 </para>
5649 </glossdef>
5650 </glossentry>
5651
5652 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
5653 <glossdef>
5654 <para>
5655 This variable lists packages the OpenEmbedded build system
5656 uses when it creates the target part of an SDK
5657 (i.e. the part built for the target hardware), which
5658 includes libraries and headers.
5659 </para>
5660
5661 <para>
5662 For background information on cross-development toolchains
5663 in the Yocto Project development environment, see the
5664 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
5665 section.
5666 For information on setting up a cross-development
5667 environment, see the
5668 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
5669 section in the Yocto Project Application Developer's Guide.
5670 </para>
5671 </glossdef>
5672 </glossentry>
5673
5674 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
5675 <glossdef>
5676 <para>
5677 This variable points to the
5678 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
5679 BitBake automatically sets this variable.
5680 </para>
5681 </glossdef>
5682 </glossentry>
5683
5684 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
5685 <glossdef>
5686 <para>
5687 A sanitized version of
5688 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
5689 This variable is used where the architecture is needed in
5690 a value where underscores are not allowed, for example
5691 within package filenames.
5692 In this case, dash characters replace any underscore
5693 characters used in TARGET_ARCH.
5694 </para>
5695
5696 <para>
5697 Do not edit this variable.
5698 </para>
5699 </glossdef>
5700 </glossentry>
5701
5702 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
5703 <glossdef>
5704 <para>
5705 The package architecture understood by the packaging
5706 system to define the architecture, ABI, and tuning of
5707 output packages.
5708 </para>
5709 </glossdef>
5710 </glossentry>
5711
5712 </glossdiv>
5713
5714 <glossdiv id='var-glossary-u'><title>U</title>
5715
5716 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
5717 <glossdef>
5718 <para>
5719 Specifies the entry point for the U-Boot image.
5720 During U-Boot image creation, the
5721 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
5722 as a command-line parameter to the
5723 <filename>uboot-mkimage</filename> utility.
5724 </para>
5725 </glossdef>
5726 </glossentry>
5727
5728 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
5729 <glossdef>
5730 <para>
5731 Specifies the load address for the U-Boot image.
5732 During U-Boot image creation, the
5733 <filename>UBOOT_LOADADDRESS</filename> variable is passed
5734 as a command-line parameter to the
5735 <filename>uboot-mkimage</filename> utility.
5736 </para>
5737 </glossdef>
5738 </glossentry>
5739
5740 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
5741 <glossdef>
5742 <para>
5743 Specifies the value passed on the
5744 <filename>make</filename> command line when building
5745 a U-Boot image.
5746 The value indicates the target platform configuration.
5747 You typically set this variable from the machine
5748 configuration file (i.e.
5749 <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
5750 </para>
5751 </glossdef>
5752 </glossentry>
5753
5754 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
5755 <glossdef>
5756 <para>
5757 Specifies the target used for building U-Boot.
5758 The target is passed directly as part of the "make" command
5759 (e.g. SPL and AIS).
5760 If you do not specifically set this variable, the
5761 OpenEmbedded build process passes and uses "all" for the
5762 target during the U-Boot building process.
5763 </para>
5764 </glossdef>
5765 </glossentry>
5766
5767 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
5768 <glossdef>
5769 <para>
5770 A list of classes to globally inherit.
5771 These classes are used by the OpenEmbedded build system
5772 to enable extra features (e.g.
5773 <filename>buildstats</filename>,
5774 <filename>image-mklibs</filename>, and so forth).
5775 </para>
5776
5777 <para>
5778 The default list is set in your
5779 <filename>local.conf</filename> file:
5780 <literallayout class='monospaced'>
5781 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
5782 </literallayout>
5783 For more information, see
5784 <filename>meta-yocto/conf/local.conf.sample</filename> in
5785 the
5786 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5787 </para>
5788 </glossdef>
5789 </glossentry>
5790
5791 </glossdiv>
5792
5793<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
5794<!-- </glossdiv>-->
5795
5796 <glossdiv id='var-glossary-w'><title>W</title>
5797
5798 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
5799 <glossdef>
5800 <para>
5801 Specifies the quality assurance checks whose failures are
5802 reported as warnings by the OpenEmbedded build system.
5803 You set this variable in your distribution configuration
5804 file.
5805 For a list of the checks you can control with this variable,
5806 see the
5807 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
5808 section.
5809 </para>
5810 </glossdef>
5811 </glossentry>
5812
5813 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
5814 <glossdef>
5815 <para>
5816 The pathname of the working directory in which the OpenEmbedded build system
5817 builds a recipe.
5818 This directory is located within the
5819 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
5820 as different packages are built.
5821 </para>
5822
5823 <para>
5824 The actual <filename>WORKDIR</filename> directory depends on several things:
5825 <itemizedlist>
5826 <listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem>
5827 <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
5828 <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
5829 <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
5830 <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
5831 <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
5832 <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
5833 </itemizedlist>
5834 </para>
5835
5836 <para>
5837 For packages that are not dependent on a particular machine,
5838 <filename>WORKDIR</filename> is defined as follows:
5839 <literallayout class='monospaced'>
5840 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
5841 </literallayout>
5842 As an example, assume a
5843 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
5844 folder name <filename>poky</filename> and a default
5845 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
5846 at <filename>poky/build</filename>.
5847 In this case, the working directory the build system uses to build
5848 the <filename>v86d</filename> package is the following:
5849 <literallayout class='monospaced'>
5850 ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
5851 </literallayout>
5852 </para>
5853
5854 <para>
5855 For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
5856 is defined slightly different:
5857 <literallayout class='monospaced'>
5858 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
5859 </literallayout>
5860 As an example, again assume a Source Directory top-level folder
5861 named <filename>poky</filename> and a default Build Directory
5862 at <filename>poky/build</filename>.
5863 In this case, the working directory the build system uses to build
5864 the <filename>acl</filename> recipe, which is being built for a
5865 MIPS-based device, is the following:
5866 <literallayout class='monospaced'>
5867 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
5868 </literallayout>
5869 </para>
5870 </glossdef>
5871 </glossentry>
5872
5873 </glossdiv>
5874
5875<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
5876<!-- </glossdiv>-->
5877
5878<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
5879<!-- </glossdiv>-->
5880
5881<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
5882<!-- </glossdiv>-->
5883
5884</glossary>
5885</chapter>
5886<!--
5887vim: expandtab tw=80 ts=4
5888-->
diff --git a/documentation/ref-manual/ref-varlocality.xml b/documentation/ref-manual/ref-varlocality.xml
new file mode 100644
index 0000000000..d3f873298d
--- /dev/null
+++ b/documentation/ref-manual/ref-varlocality.xml
@@ -0,0 +1,196 @@
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='ref-varlocality'>
6 <title>Variable Context</title>
7
8 <para>
9 While you can use most variables in almost any context such as
10 <filename>.conf</filename>, <filename>.bbclass</filename>,
11 <filename>.inc</filename>, and <filename>.bb</filename> files,
12 some variables are often associated with a particular locality or context.
13 This chapter describes some common associations.
14 </para>
15
16 <section id='ref-varlocality-configuration'>
17 <title>Configuration</title>
18
19 <para>
20 The following subsections provide lists of variables whose context is
21 configuration: distribution, machine, and local.
22 </para>
23
24 <section id='ref-varlocality-config-distro'>
25 <title>Distribution (Distro)</title>
26
27 <para>
28 This section lists variables whose configuration context is the
29 distribution, or distro.
30 <itemizedlist>
31 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename></para></listitem>
32 <listitem><para><filename><link linkend='var-DISTRO_NAME'>DISTRO_NAME</link></filename>
33 </para></listitem>
34 <listitem><para><filename><link linkend='var-DISTRO_VERSION'>DISTRO_VERSION</link>
35 </filename></para></listitem>
36 <listitem><para><filename><link linkend='var-MAINTAINER'>MAINTAINER</link></filename>
37 </para></listitem>
38 <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
39 </filename></para></listitem>
40 <listitem><para><filename><link linkend='var-TARGET_OS'>TARGET_OS</link></filename>
41 </para></listitem>
42 <listitem><para><filename><link linkend='var-TARGET_FPU'>TARGET_FPU</link></filename>
43 </para></listitem>
44 <listitem><para><filename><link linkend='var-TCMODE'>TCMODE</link></filename>
45 </para></listitem>
46 <listitem><para><filename><link linkend='var-TCLIBC'>TCLIBC</link></filename>
47 </para></listitem>
48 </itemizedlist>
49 </para>
50 </section>
51
52 <section id='ref-varlocality-config-machine'>
53 <title>Machine</title>
54
55 <para>
56 This section lists variables whose configuration context is the
57 machine.
58 <itemizedlist>
59 <listitem><para><filename><link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></filename>
60 </para></listitem>
61 <listitem><para><filename><link linkend='var-SERIAL_CONSOLES'>SERIAL_CONSOLES</link>
62 </filename></para></listitem>
63 <listitem><para><filename><link linkend='var-PACKAGE_EXTRA_ARCHS'>PACKAGE_EXTRA_ARCHS</link>
64 </filename></para></listitem>
65 <listitem><para><filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link>
66 </filename></para></listitem>
67 <listitem><para><filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link>
68 </filename></para></listitem>
69 <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS
70 </link></filename></para></listitem>
71 <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS
72 </link></filename></para></listitem>
73 <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS
74 </link></filename></para></listitem>
75 <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>
76 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename></para></listitem>
77 </itemizedlist>
78 </para>
79 </section>
80
81 <section id='ref-varlocality-config-local'>
82 <title>Local</title>
83
84 <para>
85 This section lists variables whose configuration context is the
86 local configuration through the <filename>local.conf</filename>
87 file.
88 <itemizedlist>
89 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename>
90 </para></listitem>
91 <listitem><para><filename><link linkend='var-MACHINE'>MACHINE</link></filename>
92 </para></listitem>
93 <listitem><para><filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>
94 </para></listitem>
95 <listitem><para><filename><link linkend='var-BBFILES'>BBFILES</link></filename>
96 </para></listitem>
97 <listitem><para><filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES
98 </link></filename></para></listitem>
99 <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
100 </filename></para></listitem>
101 <listitem><para><filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
102 </filename></para></listitem>
103 <listitem><para><filename><link linkend='var-BBINCLUDELOGS'>BBINCLUDELOGS</link>
104 </filename></para></listitem>
105 <listitem><para><filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>
106 ENABLE_BINARY_LOCALE_GENERATION</link></filename></para></listitem>
107 </itemizedlist>
108 </para>
109 </section>
110 </section>
111
112 <section id='ref-varlocality-recipes'>
113 <title>Recipes</title>
114
115 <para>
116 The following subsections provide lists of variables whose context is
117 recipes: required, dependencies, path, and extra build information.
118 </para>
119
120 <section id='ref-varlocality-recipe-required'>
121 <title>Required</title>
122
123 <para>
124 This section lists variables that are required for recipes.
125 <itemizedlist>
126 <listitem><para><filename><link linkend='var-LICENSE'>LICENSE</link>
127 </filename></para></listitem>
128 <listitem><para><filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
129 </filename></para></listitem>
130 <listitem><para><filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> - used
131 in recipes that fetch local or remote files.
132 </para></listitem>
133 </itemizedlist>
134 </para>
135 </section>
136
137 <section id='ref-varlocality-recipe-dependencies'>
138 <title>Dependencies</title>
139
140 <para>
141 This section lists variables that define recipe dependencies.
142 <itemizedlist>
143 <listitem><para><filename><link linkend='var-DEPENDS'>DEPENDS</link>
144 </filename></para></listitem>
145 <listitem><para><filename><link linkend='var-RDEPENDS'>RDEPENDS</link>
146 </filename></para></listitem>
147 <listitem><para><filename><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link>
148 </filename></para></listitem>
149 <listitem><para><filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link>
150 </filename></para></listitem>
151 <listitem><para><filename><link linkend='var-RREPLACES'>RREPLACES</link>
152 </filename></para></listitem>
153 </itemizedlist>
154 </para>
155 </section>
156
157 <section id='ref-varlocality-recipe-paths'>
158 <title>Paths</title>
159
160 <para>
161 This section lists variables that define recipe paths.
162 <itemizedlist>
163 <listitem><para><filename><link linkend='var-WORKDIR'>WORKDIR</link>
164 </filename></para></listitem>
165 <listitem><para><filename><link linkend='var-S'>S</link>
166 </filename></para></listitem>
167 <listitem><para><filename><link linkend='var-FILES'>FILES</link>
168 </filename></para></listitem>
169 </itemizedlist>
170 </para>
171 </section>
172
173 <section id='ref-varlocality-recipe-build'>
174 <title>Extra Build Information</title>
175
176 <para>
177 This section lists variables that define extra build information for recipes.
178 <itemizedlist>
179 <listitem><para><filename><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link>
180 </filename></para></listitem>
181 <listitem><para><filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link>
182 </filename></para></listitem>
183 <listitem><para><filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
184 </filename></para></listitem>
185 <listitem><para><filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
186 </para></listitem>
187 <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE
188 </link></filename></para></listitem>
189 </itemizedlist>
190 </para>
191 </section>
192 </section>
193</chapter>
194<!--
195vim: expandtab tw=80 ts=4 spell spelllang=en_gb
196-->
diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml
new file mode 100644
index 0000000000..c48951f934
--- /dev/null
+++ b/documentation/ref-manual/resources.xml
@@ -0,0 +1,128 @@
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='resources'>
6<title>Contributing to the Yocto Project</title>
7
8<section id='resources-intro'>
9 <title>Introduction</title>
10 <para>
11 The Yocto Project team is happy for people to experiment with the Yocto Project.
12 A number of places exist to find help if you run into difficulties or find bugs.
13 To find out how to download source code,
14 see the "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto Project Release</ulink>"
15 section in the Yocto Project Development Manual.
16 </para>
17</section>
18
19<section id='resources-bugtracker'>
20 <title>Tracking Bugs</title>
21
22 <para>
23 If you find problems with the Yocto Project, you should report them using the
24 Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>.
25 </para>
26</section>
27
28<section id='resources-mailinglist'>
29 <title>Mailing lists</title>
30
31 <para>
32 A number of mailing lists maintained by the Yocto Project exist
33 as well as related OpenEmbedded mailing lists for discussion,
34 patch submission and announcements.
35 To subscribe to one of the following mailing lists, click on the
36 appropriate URL in the following list and follow the instructions:
37 <itemizedlist>
38 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> -
39 General Yocto Project discussion mailing list. </para></listitem>
40 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'></ulink> -
41 Discussion mailing list about OpenEmbedded-Core (the core metadata).</para></listitem>
42 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'></ulink> -
43 Discussion mailing list about OpenEmbedded.</para></listitem>
44 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> -
45 Discussion mailing list about the
46 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
47 build tool.</para></listitem>
48 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> -
49 Discussion mailing list about
50 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>.
51 </para></listitem>
52 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> -
53 Mailing list to receive official Yocto Project release and milestone
54 announcements.</para></listitem>
55 </itemizedlist>
56 </para>
57</section>
58
59<section id='resources-irc'>
60 <title>Internet Relay Chat (IRC)</title>
61
62 <para>
63 Two IRC channels on freenode are available for the Yocto Project and Poky discussions:
64 <itemizedlist>
65 <listitem><para><filename>#yocto</filename></para></listitem>
66 <listitem><para><filename>#poky</filename></para></listitem>
67 </itemizedlist>
68 </para>
69</section>
70
71<section id='resources-links'>
72 <title>Links</title>
73
74 <para>
75 Here is a list of resources you will find helpful:
76 <itemizedlist>
77 <listitem><para><emphasis>
78 <ulink url='&YOCTO_HOME_URL;'>The Yocto Project website</ulink>:
79 </emphasis> The home site for the Yocto
80 Project.</para></listitem>
81 <listitem><para><emphasis>
82 <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
83 The company who acquired OpenedHand in 2008 and began
84 development on the Yocto Project.</para></listitem>
85 <listitem><para><emphasis>
86 <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
87 The upstream, generic, embedded distribution used as the basis
88 for the build system in the Yocto Project.
89 Poky derives from and contributes back to the OpenEmbedded
90 project.</para></listitem>
91 <listitem><para><emphasis>
92 <ulink url='http://developer.berlios.de/projects/bitbake/'>
93 BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem>
94 <listitem><para><emphasis>
95 BitBake User Manual:</emphasis>
96 A comprehensive guide to the BitBake tool.
97 You can find the BitBake User Manual in the
98 <filename>bitbake/doc/manual</filename> directory, which is
99 found in the
100 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
101 </para></listitem>
102 <listitem><para><emphasis>
103 <ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>:
104 </emphasis> An open source machine emulator and virtualizer.
105 </para></listitem>
106 </itemizedlist>
107 </para>
108</section>
109
110<section id='resources-contributions'>
111 <title>Contributions</title>
112
113 <para>
114 The Yocto Project gladly accepts contributions.
115 You can submit changes to the project either by creating and sending
116 pull requests,
117 or by submitting patches through email.
118 For information on how to do both as well as information on how
119 to find out who is the maintainer for areas of code, see the
120 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
121 section in the Yocto Project Development Manual.
122 </para>
123</section>
124
125</chapter>
126<!--
127vim: expandtab tw=80 ts=4
128-->
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
new file mode 100644
index 0000000000..be9c38709a
--- /dev/null
+++ b/documentation/ref-manual/technical-details.xml
@@ -0,0 +1,1335 @@
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='technical-details'>
6<title>Technical Details</title>
7
8 <para>
9 This chapter provides technical details for various parts of the Yocto Project.
10 Currently, topics include Yocto Project components,
11 shared state (sstate) cache, x32, and Licenses.
12 </para>
13
14<section id='usingpoky-components'>
15 <title>Yocto Project Components</title>
16
17 <para>
18 The BitBake task executor together with various types of configuration files form the
19 OpenEmbedded Core.
20 This section overviews these by describing what they are used for
21 and how they interact.
22 </para>
23
24 <para>
25 BitBake handles the parsing and execution of the data files.
26 The data itself is of various types:
27 <itemizedlist>
28 <listitem><para><emphasis>Recipes:</emphasis> Provides details about particular
29 pieces of software.</para></listitem>
30 <listitem><para><emphasis>Class Data:</emphasis> Abstracts common build
31 information (e.g. how to build a Linux kernel).</para></listitem>
32 <listitem><para><emphasis>Configuration Data:</emphasis> Defines machine-specific settings,
33 policy decisions, and so forth.
34 Configuration data acts as the glue to bind everything together.</para></listitem>
35 </itemizedlist>
36 For more information on data, see the
37 "<ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-terms'>Yocto Project Terms</ulink>"
38 section in the Yocto Project Development Manual.
39 </para>
40
41 <para>
42 BitBake knows how to combine multiple data sources together and refers to each data source
43 as a layer.
44 For information on layers, see the
45 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
46 Creating Layers</ulink>" section of the Yocto Project Development Manual.
47 </para>
48
49 <para>
50 Following are some brief details on these core components.
51 For more detailed information on these components, see the
52 "<link linkend='ref-structure'>Source Directory Structure</link>" chapter.
53 </para>
54
55 <section id='usingpoky-components-bitbake'>
56 <title>BitBake</title>
57
58 <para>
59 BitBake is the tool at the heart of the OpenEmbedded build system
60 and is responsible for parsing the
61 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
62 generating a list of tasks from it, and then executing those tasks.
63 To see a list of the options BitBake supports, use the following
64 help command:
65 <literallayout class='monospaced'>
66 $ bitbake --help
67 </literallayout>
68 </para>
69
70 <para>
71 The most common usage for BitBake is <filename>bitbake &lt;packagename&gt;</filename>, where
72 <filename>packagename</filename> is the name of the package you want to build
73 (referred to as the "target" in this manual).
74 The target often equates to the first part of a <filename>.bb</filename> filename.
75 So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
76 might type the following:
77 <literallayout class='monospaced'>
78 $ bitbake matchbox-desktop
79 </literallayout>
80 Several different versions of <filename>matchbox-desktop</filename> might exist.
81 BitBake chooses the one selected by the distribution configuration.
82 You can get more details about how BitBake chooses between different
83 target versions and providers in the
84 "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section.
85 </para>
86
87 <para>
88 BitBake also tries to execute any dependent tasks first.
89 So for example, before building <filename>matchbox-desktop</filename>, BitBake
90 would build a cross compiler and <filename>eglibc</filename> if they had not already
91 been built.
92 <note>This release of the Yocto Project does not support the <filename>glibc</filename>
93 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
94 builds with <filename>eglibc</filename>.</note>
95 </para>
96
97 <para>
98 A useful BitBake option to consider is the <filename>-k</filename> or
99 <filename>--continue</filename> option.
100 This option instructs BitBake to try and continue processing the job as much
101 as possible even after encountering an error.
102 When an error occurs, the target that
103 failed and those that depend on it cannot be remade.
104 However, when you use this option other dependencies can still be processed.
105 </para>
106 </section>
107
108 <section id='usingpoky-components-metadata'>
109 <title>Metadata (Recipes)</title>
110
111 <para>
112 The <filename>.bb</filename> files are usually referred to as "recipes."
113 In general, a recipe contains information about a single piece of software.
114 The information includes the location from which to download the source patches
115 (if any are needed), which special configuration options to apply,
116 how to compile the source files, and how to package the compiled output.
117 </para>
118
119 <para>
120 The term "package" can also be used to describe recipes.
121 However, since the same word is used for the packaged output from the OpenEmbedded
122 build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
123 this document avoids using the term "package" when referring to recipes.
124 </para>
125 </section>
126
127 <section id='usingpoky-components-classes'>
128 <title>Classes</title>
129
130 <para>
131 Class files (<filename>.bbclass</filename>) contain information that
132 is useful to share between
133 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> files.
134 An example is the Autotools class, which contains
135 common settings for any application that Autotools uses.
136 The "<link linkend='ref-classes'>Classes</link>" chapter provides details
137 about common classes and how to use them.
138 </para>
139 </section>
140
141 <section id='usingpoky-components-configuration'>
142 <title>Configuration</title>
143
144 <para>
145 The configuration files (<filename>.conf</filename>) define various configuration variables
146 that govern the OpenEmbedded build process.
147 These files fall into several areas that define machine configuration options,
148 distribution configuration options, compiler tuning options, general common configuration
149 options, and user configuration options in <filename>local.conf</filename>, which is found
150 in the
151 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
152 </para>
153 </section>
154</section>
155
156<section id="cross-development-toolchain-generation">
157 <title>Cross-Development Toolchain Generation</title>
158
159 <para>
160 The Yocto Project does most of the work for you when it comes to
161 creating
162 <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
163 This section provides some technical background information on how
164 cross-development toolchains are created and used.
165 For more information on these toolchain, you can also see the
166 <ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>.
167 </para>
168
169 <para>
170 In the Yocto Project development environment, cross-development
171 toolchains are used to build the image and applications that run on the
172 target hardware.
173 With just a few commands, the OpenEmbedded build system creates
174 these necessary toolchains for you.
175 </para>
176
177 <para>
178 The following figure shows a high-level build environment regarding
179 toolchain construction and use.
180 </para>
181
182 <para>
183 <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
184 </para>
185
186 <para>
187 Most of the work occurs on the Build Host.
188 This is the machine used to build images and generally work within the
189 the Yocto Project environment.
190 When you run BitBake to create an image, the OpenEmbedded build system
191 uses the host <filename>gcc</filename> compiler to bootstrap a
192 cross-compiler named <filename>gcc-cross</filename>.
193 The <filename>gcc-cross</filename> compiler is what BitBake uses to
194 compile source files when creating the target image.
195 You can think of <filename>gcc-cross</filename> simply as an
196 automatically generated cross-compiler that is used internally within
197 BitBake only.
198 </para>
199
200 <para>
201 The chain of events that occurs when <filename>gcc-cross</filename> is
202 bootstrapped is as follows:
203 <literallayout class='monospaced'>
204 gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> eglibc-initial -> eglibc -> gcc-cross -> gcc-runtime
205 </literallayout>
206 <itemizedlist>
207 <listitem><para><filename>gcc</filename>:
208 The build host's GNU Compiler Collection (GCC).
209 </para></listitem>
210 <listitem><para><filename>binutils-cross</filename>:
211 The bare minimum binary utilities needed in order to run
212 the <filename>gcc-cross-initial</filename> phase of the
213 bootstrap operation.
214 </para></listitem>
215 <listitem><para><filename>gcc-cross-initial</filename>:
216 An early stage of the bootstrap process for creating
217 the cross-compiler.
218 This stage builds enough of the <filename>gcc-cross</filename>,
219 the C library, and other pieces needed to finish building the
220 final cross-compiler in later stages.
221 This tool is a "native" package (i.e. it is designed to run on
222 the build host).
223 </para></listitem>
224 <listitem><para><filename>linux-libc-headers</filename>:
225 Headers needed for the cross-compiler.
226 </para></listitem>
227 <listitem><para><filename>eglibc-initial</filename>:
228 An initial version of the Embedded GLIBC needed to bootstrap
229 <filename>eglibc</filename>.
230 </para></listitem>
231 <listitem><para><filename>gcc-cross</filename>:
232 The final stage of the bootstrap process for the
233 cross-compiler.
234 This stage results in the actual cross-compiler that
235 BitBake uses when it builds an image for a targeted
236 device.
237 <note>
238 If you are replacing this cross compiler toolchain
239 with a custom version, you must replace
240 <filename>gcc-cross</filename>.
241 </note>
242 This tool is also a "native" package (i.e. it is
243 designed to run on the build host).
244 </para></listitem>
245 <listitem><para><filename>gcc-runtime</filename>:
246 Runtime libraries resulting from the toolchain bootstrapping
247 process.
248 This tool produces a binary that consists of the
249 runtime libraries need for the targeted device.
250 </para></listitem>
251 </itemizedlist>
252 </para>
253
254 <para>
255 You can use the OpenEmbedded build system to build an installer for
256 the relocatable SDK used to develop applications.
257 When you run the installer, it installs the toolchain, which contains
258 the development tools (e.g., the
259 <filename>gcc-cross-canadian</filename>),
260 <filename>binutils-cross-canadian</filename>, and other
261 <filename>nativesdk-*</filename> tools you need to cross-compile and
262 test your software.
263 The figure shows the commands you use to easily build out this
264 toolchain.
265 This cross-development toolchain is built to execute on the
266 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
267 which might or might not be the same
268 machine as the Build Host.
269 <note>
270 If your target architecture is supported by the Yocto Project,
271 you can take advantage of pre-built images that ship with the
272 Yocto Project and already contain cross-development toolchain
273 installers.
274 </note>
275 </para>
276
277 <para>
278 Here is the bootstrap process for the relocatable toolchain:
279 <literallayout class='monospaced'>
280 gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> eglibc-initial -> nativesdk-eglibc -> gcc-crosssdk -> gcc-cross-canadian
281 </literallayout>
282 <itemizedlist>
283 <listitem><para><filename>gcc</filename>:
284 The build host's GNU Compiler Collection (GCC).
285 </para></listitem>
286 <listitem><para><filename>binutils-crosssdk</filename>:
287 The bare minimum binary utilities needed in order to run
288 the <filename>gcc-crosssdk-initial</filename> phase of the
289 bootstrap operation.
290 </para></listitem>
291 <listitem><para><filename>gcc-crosssdk-initial</filename>:
292 An early stage of the bootstrap process for creating
293 the cross-compiler.
294 This stage builds enough of the
295 <filename>gcc-crosssdk</filename> and supporting pieces so that
296 the final stage of the bootstrap process can produce the
297 finished cross-compiler.
298 This tool is a "native" binary that runs on the build host.
299 </para></listitem>
300 <listitem><para><filename>linux-libc-headers</filename>:
301 Headers needed for the cross-compiler.
302 </para></listitem>
303 <listitem><para><filename>eglibc-initial</filename>:
304 An initial version of the Embedded GLIBC needed to bootstrap
305 <filename>nativesdk-eglibc</filename>.
306 </para></listitem>
307 <listitem><para><filename>nativesdk-eglibc</filename>:
308 The Embedded GLIBC needed to bootstrap the
309 <filename>gcc-crosssdk</filename>.
310 </para></listitem>
311 <listitem><para><filename>gcc-crosssdk</filename>:
312 The final stage of the bootstrap process for the
313 relocatable cross-compiler.
314 The <filename>gcc-crosssdk</filename> is a transitory compiler
315 and never leaves the build host.
316 Its purpose is to help in the bootstrap process to create the
317 eventual relocatable <filename>gcc-cross-canadian</filename>
318 compiler, which is relocatable.
319 This tool is also a "native" package (i.e. it is
320 designed to run on the build host).
321 </para></listitem>
322 <listitem><para><filename>gcc-cross-canadian</filename>:
323 The final relocatable cross-compiler.
324 When run on the
325 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
326 this tool
327 produces executable code that runs on the target device.
328 </para></listitem>
329 </itemizedlist>
330 </para>
331</section>
332
333<section id="shared-state-cache">
334 <title>Shared State Cache</title>
335
336 <para>
337 By design, the OpenEmbedded build system builds everything from scratch unless
338 BitBake can determine that parts do not need to be rebuilt.
339 Fundamentally, building from scratch is attractive as it means all parts are
340 built fresh and there is no possibility of stale data causing problems.
341 When developers hit problems, they typically default back to building from scratch
342 so they know the state of things from the start.
343 </para>
344
345 <para>
346 Building an image from scratch is both an advantage and a disadvantage to the process.
347 As mentioned in the previous paragraph, building from scratch ensures that
348 everything is current and starts from a known state.
349 However, building from scratch also takes much longer as it generally means
350 rebuilding things that do not necessarily need rebuilt.
351 </para>
352
353 <para>
354 The Yocto Project implements shared state code that supports incremental builds.
355 The implementation of the shared state code answers the following questions that
356 were fundamental roadblocks within the OpenEmbedded incremental build support system:
357 <itemizedlist>
358 <listitem>What pieces of the system have changed and what pieces have not changed?</listitem>
359 <listitem>How are changed pieces of software removed and replaced?</listitem>
360 <listitem>How are pre-built components that do not need to be rebuilt from scratch
361 used when they are available?</listitem>
362 </itemizedlist>
363 </para>
364
365 <para>
366 For the first question, the build system detects changes in the "inputs" to a given task by
367 creating a checksum (or signature) of the task's inputs.
368 If the checksum changes, the system assumes the inputs have changed and the task needs to be
369 rerun.
370 For the second question, the shared state (sstate) code tracks which tasks add which output
371 to the build process.
372 This means the output from a given task can be removed, upgraded or otherwise manipulated.
373 The third question is partly addressed by the solution for the second question
374 assuming the build system can fetch the sstate objects from remote locations and
375 install them if they are deemed to be valid.
376 </para>
377
378 <note>
379 The OpenEmbedded build system does not maintain
380 <link linkend='var-PR'><filename>PR</filename></link> information
381 as part of the shared state packages.
382 Consequently, considerations exist that affect maintaining shared
383 state feeds.
384 For information on how the OpenEmbedded works with packages and can
385 track incrementing <filename>PR</filename> information, see the
386 "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a Package Revision Number</ulink>"
387 section.
388 </note>
389
390 <para>
391 The rest of this section goes into detail about the overall incremental build
392 architecture, the checksums (signatures), shared state, and some tips and tricks.
393 </para>
394
395 <section id='overall-architecture'>
396 <title>Overall Architecture</title>
397
398 <para>
399 When determining what parts of the system need to be built, BitBake
400 uses a per-task basis and does not use a per-recipe basis.
401 You might wonder why using a per-task basis is preferred over a per-recipe basis.
402 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
403 In this case, <filename>do_install</filename> and <filename>do_package</filename>
404 output are still valid.
405 However, with a per-recipe approach, the build would not include the
406 <filename>.deb</filename> files.
407 Consequently, you would have to invalidate the whole build and rerun it.
408 Rerunning everything is not the best situation.
409 Also in this case, the core must be "taught" much about specific tasks.
410 This methodology does not scale well and does not allow users to easily add new tasks
411 in layers or as external recipes without touching the packaged-staging core.
412 </para>
413 </section>
414
415 <section id='checksums'>
416 <title>Checksums (Signatures)</title>
417
418 <para>
419 The shared state code uses a checksum, which is a unique signature of a task's
420 inputs, to determine if a task needs to be run again.
421 Because it is a change in a task's inputs that triggers a rerun, the process
422 needs to detect all the inputs to a given task.
423 For shell tasks, this turns out to be fairly easy because
424 the build process generates a "run" shell script for each task and
425 it is possible to create a checksum that gives you a good idea of when
426 the task's data changes.
427 </para>
428
429 <para>
430 To complicate the problem, there are things that should not be included in
431 the checksum.
432 First, there is the actual specific build path of a given task -
433 the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
434 It does not matter if the working directory changes because it should not
435 affect the output for target packages.
436 Also, the build process has the objective of making native or cross packages relocatable.
437 The checksum therefore needs to exclude <filename>WORKDIR</filename>.
438 The simplistic approach for excluding the working directory is to set
439 <filename>WORKDIR</filename> to some fixed value and create the checksum
440 for the "run" script.
441 </para>
442
443 <para>
444 Another problem results from the "run" scripts containing functions that
445 might or might not get called.
446 The incremental build solution contains code that figures out dependencies
447 between shell functions.
448 This code is used to prune the "run" scripts down to the minimum set,
449 thereby alleviating this problem and making the "run" scripts much more
450 readable as a bonus.
451 </para>
452
453 <para>
454 So far we have solutions for shell scripts.
455 What about Python tasks?
456 The same approach applies even though these tasks are more difficult.
457 The process needs to figure out what variables a Python function accesses
458 and what functions it calls.
459 Again, the incremental build solution contains code that first figures out
460 the variable and function dependencies, and then creates a checksum for the data
461 used as the input to the task.
462 </para>
463
464 <para>
465 Like the <filename>WORKDIR</filename> case, situations exist where dependencies
466 should be ignored.
467 For these cases, you can instruct the build process to ignore a dependency
468 by using a line like the following:
469 <literallayout class='monospaced'>
470 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
471 </literallayout>
472 This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not
473 depend on the value of <filename>MACHINE</filename>, even if it does reference it.
474 </para>
475
476 <para>
477 Equally, there are cases where we need to add dependencies BitBake is not able to find.
478 You can accomplish this by using a line like the following:
479 <literallayout class='monospaced'>
480 PACKAGE_ARCHS[vardeps] = "MACHINE"
481 </literallayout>
482 This example explicitly adds the <filename>MACHINE</filename> variable as a
483 dependency for <filename>PACKAGE_ARCHS</filename>.
484 </para>
485
486 <para>
487 Consider a case with in-line Python, for example, where BitBake is not
488 able to figure out dependencies.
489 When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
490 produces output when it discovers something for which it cannot figure out
491 dependencies.
492 The Yocto Project team has currently not managed to cover those dependencies
493 in detail and is aware of the need to fix this situation.
494 </para>
495
496 <para>
497 Thus far, this section has limited discussion to the direct inputs into a task.
498 Information based on direct inputs is referred to as the "basehash" in the
499 code.
500 However, there is still the question of a task's indirect inputs - the
501 things that were already built and present in the
502 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
503 The checksum (or signature) for a particular task needs to add the hashes
504 of all the tasks on which the particular task depends.
505 Choosing which dependencies to add is a policy decision.
506 However, the effect is to generate a master checksum that combines the basehash
507 and the hashes of the task's dependencies.
508 </para>
509
510 <para>
511 At the code level, there are a variety of ways both the basehash and the
512 dependent task hashes can be influenced.
513 Within the BitBake configuration file, we can give BitBake some extra information
514 to help it construct the basehash.
515 The following statements effectively result in a list of global variable
516 dependency excludes - variables never included in any checksum:
517 <literallayout class='monospaced'>
518 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH"
519 BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS"
520 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
521 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
522 </literallayout>
523 The previous example actually excludes
524 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
525 since it is actually constructed as a path within
526 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
527 the whitelist.
528 </para>
529
530 <para>
531 The rules for deciding which hashes of dependent tasks to include through
532 dependency chains are more complex and are generally accomplished with a
533 Python function.
534 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
535 of this and also illustrates how you can insert your own policy into the system
536 if so desired.
537 This file defines the two basic signature generators <filename>OE-Core</filename>
538 uses: "OEBasic" and "OEBasicHash".
539 By default, there is a dummy "noop" signature handler enabled in BitBake.
540 This means that behavior is unchanged from previous versions.
541 <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
542 through this setting in the <filename>bitbake.conf</filename> file:
543 <literallayout class='monospaced'>
544 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
545 </literallayout>
546 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
547 "OEBasic" version but adds the task hash to the stamp files.
548 This results in any
549 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
550 change that changes the task hash, automatically
551 causing the task to be run again.
552 This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
553 values and changes to Metadata automatically ripple across the build.
554 </para>
555
556 <para>
557 It is also worth noting that the end result of these signature generators is to
558 make some dependency and hash information available to the build.
559 This information includes:
560 <literallayout class='monospaced'>
561 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
562 BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
563 BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
564 BB_TASKHASH - the hash of the currently running task
565 </literallayout>
566 </para>
567 </section>
568
569 <section id='shared-state'>
570 <title>Shared State</title>
571
572 <para>
573 Checksums and dependencies, as discussed in the previous section, solve half the
574 problem.
575 The other part of the problem is being able to use checksum information during the build
576 and being able to reuse or rebuild specific components.
577 </para>
578
579 <para>
580 The shared state class (<filename>sstate.bbclass</filename>)
581 is a relatively generic implementation of how to "capture" a snapshot of a given task.
582 The idea is that the build process does not care about the source of a task's output.
583 Output could be freshly built or it could be downloaded and unpacked from
584 somewhere - the build process does not need to worry about its source.
585 </para>
586
587 <para>
588 There are two types of output, one is just about creating a directory
589 in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
590 A good example is the output of either <filename>do_install</filename> or
591 <filename>do_package</filename>.
592 The other type of output occurs when a set of data is merged into a shared directory
593 tree such as the sysroot.
594 </para>
595
596 <para>
597 The Yocto Project team has tried to keep the details of the implementation hidden in
598 <filename>sstate.bbclass</filename>.
599 From a user's perspective, adding shared state wrapping to a task
600 is as simple as this <filename>do_deploy</filename> example taken from
601 <filename>do_deploy.bbclass</filename>:
602 <literallayout class='monospaced'>
603 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
604 SSTATETASKS += "do_deploy"
605 do_deploy[sstate-name] = "deploy"
606 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
607 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
608
609 python do_deploy_setscene () {
610 sstate_setscene(d)
611 }
612 addtask do_deploy_setscene
613 </literallayout>
614 In the example, we add some extra flags to the task, a name field ("deploy"), an
615 input directory where the task sends data, and the output
616 directory where the data from the task should eventually be copied.
617 We also add a <filename>_setscene</filename> variant of the task and add the task
618 name to the <filename>SSTATETASKS</filename> list.
619 </para>
620
621 <para>
622 If you have a directory whose contents you need to preserve, you can do this with
623 a line like the following:
624 <literallayout class='monospaced'>
625 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
626 </literallayout>
627 This method, as well as the following example, also works for multiple directories.
628 <literallayout class='monospaced'>
629 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
630 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
631 do_package[sstate-lockfile] = "${PACKAGELOCK}"
632 </literallayout>
633 These methods also include the ability to take a lockfile when manipulating
634 shared state directory structures since some cases are sensitive to file
635 additions or removals.
636 </para>
637
638 <para>
639 Behind the scenes, the shared state code works by looking in
640 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
641 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
642 for shared state files.
643 Here is an example:
644 <literallayout class='monospaced'>
645 SSTATE_MIRRORS ?= "\
646 file://.* http://someserver.tld/share/sstate/PATH \n \
647 file://.* file:///some/local/dir/sstate/PATH"
648 </literallayout>
649 <note>
650 The shared state directory (<filename>SSTATE_DIR</filename>) is
651 organized into two-character subdirectories, where the subdirectory
652 names are based on the first two characters of the hash.
653 If the shared state directory structure for a mirror has the
654 same structure as <filename>SSTATE_DIR</filename>, you must
655 specify "PATH" as part of the URI to enable the build system
656 to map to the appropriate subdirectory.
657 </note>
658 </para>
659
660 <para>
661 The shared state package validity can be detected just by looking at the
662 filename since the filename contains the task checksum (or signature) as
663 described earlier in this section.
664 If a valid shared state package is found, the build process downloads it
665 and uses it to accelerate the task.
666 </para>
667
668 <para>
669 The build processes use the <filename>*_setscene</filename> tasks
670 for the task acceleration phase.
671 BitBake goes through this phase before the main execution code and tries
672 to accelerate any tasks for which it can find shared state packages.
673 If a shared state package for a task is available, the shared state
674 package is used.
675 This means the task and any tasks on which it is dependent are not
676 executed.
677 </para>
678
679 <para>
680 As a real world example, the aim is when building an IPK-based image,
681 only the <filename>do_package_write_ipk</filename> tasks would have their
682 shared state packages fetched and extracted.
683 Since the sysroot is not used, it would never get extracted.
684 This is another reason why a task-based approach is preferred over a
685 recipe-based approach, which would have to install the output from every task.
686 </para>
687 </section>
688
689 <section id='tips-and-tricks'>
690 <title>Tips and Tricks</title>
691
692 <para>
693 The code in the build system that supports incremental builds is not
694 simple code.
695 This section presents some tips and tricks that help you work around
696 issues related to shared state code.
697 </para>
698
699 <section id='debugging'>
700 <title>Debugging</title>
701
702 <para>
703 When things go wrong, debugging needs to be straightforward.
704 Because of this, the Yocto Project team included strong debugging
705 tools:
706 <itemizedlist>
707 <listitem><para>Whenever a shared state package is written out, so is a
708 corresponding <filename>.siginfo</filename> file.
709 This practice results in a pickled Python database of all
710 the metadata that went into creating the hash for a given shared state
711 package.</para></listitem>
712 <listitem><para>If you run BitBake with the <filename>--dump-signatures</filename>
713 (or <filename>-S</filename>) option, BitBake dumps out
714 <filename>.siginfo</filename> files in
715 the stamp directory for every task it would have executed instead of
716 building the specified target package.</para></listitem>
717 <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
718 can process <filename>.siginfo</filename> files.
719 If you specify one of these files, BitBake dumps out the dependency
720 information in the file.
721 If you specify two files, BitBake compares the two files and dumps out
722 the differences between the two.
723 This more easily helps answer the question of "What
724 changed between X and Y?"</para></listitem>
725 </itemizedlist>
726 </para>
727 </section>
728
729 <section id='invalidating-shared-state'>
730 <title>Invalidating Shared State</title>
731
732 <para>
733 The shared state code uses checksums and shared state
734 cache to avoid unnecessarily rebuilding tasks.
735 As with all schemes, this one has some drawbacks.
736 It is possible that you could make implicit changes that are not factored
737 into the checksum calculation, but do affect a task's output.
738 A good example is perhaps when a tool changes its output.
739 Assume that the output of <filename>rpmdeps</filename> needed to change.
740 The result of the change should be that all the
741 <filename>package</filename>, <filename>package_write_rpm</filename>,
742 and <filename>package_deploy-rpm</filename> shared state cache
743 items would become invalid.
744 But, because this is a change that is external to the code and therefore implicit,
745 the associated shared state cache items do not become invalidated.
746 In this case, the build process uses the cached items rather than running the
747 task again.
748 Obviously, these types of implicit changes can cause problems.
749 </para>
750
751 <para>
752 To avoid these problems during the build, you need to understand the effects of any
753 change you make.
754 Note that any changes you make directly to a function automatically are factored into
755 the checksum calculation and thus, will invalidate the associated area of sstate cache.
756 You need to be aware of any implicit changes that are not obvious changes to the
757 code and could affect the output of a given task.
758 Once you are aware of such changes, you can take steps to invalidate the cache
759 and force the tasks to run.
760 The steps to take are as simple as changing function's comments in the source code.
761 For example, to invalidate package shared state files, change the comment statements
762 of <filename>do_package</filename> or the comments of one of the functions it calls.
763 The change is purely cosmetic, but it causes the checksum to be recalculated and
764 forces the task to be run again.
765 </para>
766
767 <note>
768 For an example of a commit that makes a cosmetic change to invalidate
769 a shared state, see this
770 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
771 </note>
772 </section>
773 </section>
774</section>
775
776<section id='x32'>
777 <title>x32</title>
778
779 <para>
780 x32 is a processor-specific Application Binary Interface (psABI) for x86_64.
781 An ABI defines the calling conventions between functions in a processing environment.
782 The interface determines what registers are used and what the sizes are for various C data types.
783 </para>
784
785 <para>
786 Some processing environments prefer using 32-bit applications even when running
787 on Intel 64-bit platforms.
788 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
789 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
790 leaving the system underutilized.
791 Now consider the x86_64 psABI.
792 This ABI is newer and uses 64-bits for data sizes and program pointers.
793 The extra bits increase the footprint size of the programs, libraries,
794 and also increases the memory and file system size requirements.
795 Executing under the x32 psABI enables user programs to utilize CPU and system resources
796 more efficiently while keeping the memory footprint of the applications low.
797 Extra bits are used for registers but not for addressing mechanisms.
798 </para>
799
800 <section id='support'>
801 <title>Support</title>
802
803 <para>
804 While the x32 psABI specifications are not fully finalized, this Yocto Project
805 release supports current development specifications of x32 psABI.
806 As of this release of the Yocto Project, x32 psABI support exists as follows:
807 <itemizedlist>
808 <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
809 </para></listitem>
810 <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
811 <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
812 <filename>core-image-sato</filename> images.</para></listitem>
813 </itemizedlist>
814 </para>
815 </section>
816
817 <section id='stabilizing-and-completing-x32'>
818 <title>Stabilizing and Completing x32</title>
819
820 <para>
821 As of this Yocto Project release, the x32 psABI kernel and library
822 interfaces specifications are not finalized.
823 </para>
824
825 <para>
826 Future Plans for the x32 psABI in the Yocto Project include the following:
827 <itemizedlist>
828 <listitem><para>Enhance and fix the few remaining recipes so they
829 work with and support x32 toolchains.</para></listitem>
830 <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
831 <listitem><para>Support larger images.</para></listitem>
832 </itemizedlist>
833 </para>
834 </section>
835
836 <section id='using-x32-right-now'>
837 <title>Using x32 Right Now</title>
838
839 <para>
840 Follow these steps to use the x32 spABI:
841 <itemizedlist>
842 <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
843 machines by editing the <filename>conf/local.conf</filename> like this:
844 <literallayout class='monospaced'>
845 MACHINE = "qemux86-64"
846 DEFAULTTUNE = "x86-64-x32"
847 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
848 or 'INVALID'), True) or 'lib'}"
849 #MACHINE = "genericx86"
850 #DEFAULTTUNE = "core2-64-x32"
851 </literallayout></para></listitem>
852 <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
853 Here is an example:
854 <literallayout class='monospaced'>
855 $ bitbake core-image-sato
856 </literallayout></para></listitem>
857 <listitem><para>As usual, run your image using QEMU:
858 <literallayout class='monospaced'>
859 $ runqemu qemux86-64 core-image-sato
860 </literallayout></para></listitem>
861 </itemizedlist>
862 </para>
863 </section>
864</section>
865
866<section id="wayland">
867 <title>Wayland</title>
868
869 <para>
870 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Wayland</ulink>
871 is a computer display server protocol that when implemented
872 provides a method for compositing window managers to communicate
873 directly with applications and video hardware and expects them to
874 communicate with input hardware using other libraries.
875 Using Wayland with supporting targets can result in better control
876 over graphics frame rendering than an application might otherwise
877 achieve.
878 </para>
879
880 <para>
881 The Yocto Project provides the Wayland protocol libraries and the
882 reference Weston compositor as part of it release.
883 This section describes what you need to do to implement Wayland and
884 use the compositor when building an image for a supporting target.
885 </para>
886
887 <section id="wayland-support">
888 <title>Support</title>
889
890 <para>
891 The Wayland protocol libraries and the reference Weston compositor
892 ship as integrated packages in the <filename>meta</filename> layer
893 of the
894 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
895 Specifically, you can find the recipes that build both Wayland
896 and Weston at <filename>meta/recipes-graphics/wayland</filename>.
897 </para>
898
899 <para>
900 You can build both the Wayland and Weston packages for use only
901 with targets that accept the
902 <ulink url='http://dri.freedesktop.org/wiki/'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
903 which is also known as Mesa DRI.
904 This implies that you cannot build and use the packages if your
905 target uses, for example, the
906 <trademark class='registered'>Intel</trademark> Embedded Media and
907 Graphics Driver (<trademark class='registered'>Intel</trademark>
908 EMGD) that overrides Mesa DRI.
909 </para>
910
911 <note>
912 Due to lack of EGL support, Weston 1.0.3 will not run directly on
913 the emulated QEMU hardware.
914 However, this version of Weston will run under X emulation without
915 issues.
916 </note>
917 </section>
918
919 <section id="enabling-wayland-in-an-image">
920 <title>Enabling Wayland in an Image</title>
921
922 <para>
923 To enable Wayland, you need to enable it to be built and enable
924 it to be included in the image.
925 </para>
926
927 <section id="enable-building">
928 <title>Building</title>
929
930 <para>
931 To cause Mesa to build the <filename>wayland-egl</filename>
932 platform and Weston to build Wayland with Kernel Mode
933 Setting
934 (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
935 support, include the "wayland" flag in the
936 <link linkend="var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></link>
937 statement in your <filename>local.conf</filename> file:
938 <literallayout class='monospaced'>
939 DISTRO_FEATURES_append = " wayland"
940 </literallayout>
941 </para>
942
943 <note>
944 If X11 has been enabled elsewhere, Weston will build Wayland
945 with X11 support
946 </note>
947 </section>
948
949 <section id="enable-installation-in-an-image">
950 <title>Installing</title>
951
952 <para>
953 To install the Wayland feature into an image, you must
954 include the following
955 <link linkend='var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></link>
956 statement in your <filename>local.conf</filename> file:
957 <literallayout class='monospaced'>
958 CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
959 </literallayout>
960 </para>
961 </section>
962 </section>
963
964 <section id="running-weston">
965 <title>Running Weston</title>
966
967 <para>
968 To run Weston inside X11, enabling it as described earlier and
969 building a Sato image is sufficient.
970 If you are running your image under Sato, a Weston Launcher appears
971 in the "Utility" category.
972 </para>
973
974 <para>
975 Alternatively, you can run Weston through the command-line
976 interpretor (CLI), which is better suited for development work.
977 To run Weston under the CLI you need to do the following after
978 your image is built:
979 <orderedlist>
980 <listitem><para>Run these commands to export
981 <filename>XDG_RUNTIME_DIR</filename>:
982 <literallayout class='monospaced'>
983 mkdir -p /tmp/$USER-weston
984 chmod 0700 /tmp/$USER-weston
985 export XDG_RUNTIME_DIR=/tmp/$USER=weston
986 </literallayout></para></listitem>
987 <listitem><para>Launch Weston in the shell:
988 <literallayout class='monospaced'>
989 weston
990 </literallayout></para></listitem>
991 </orderedlist>
992 </para>
993 </section>
994</section>
995
996<section id="licenses">
997 <title>Licenses</title>
998
999 <para>
1000 This section describes the mechanism by which the OpenEmbedded build system
1001 tracks changes to licensing text.
1002 The section also describes how to enable commercially licensed recipes,
1003 which by default are disabled.
1004 </para>
1005
1006 <para>
1007 For information that can help you maintain compliance with various open
1008 source licensing during the lifecycle of the product, see the
1009 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>" section
1010 in the Yocto Project Development Manual.
1011 </para>
1012
1013 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
1014 <title>Tracking License Changes</title>
1015
1016 <para>
1017 The license of an upstream project might change in the future.
1018 In order to prevent these changes going unnoticed, the
1019 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
1020 variable tracks changes to the license text. The checksums are validated at the end of the
1021 configure step, and if the checksums do not match, the build will fail.
1022 </para>
1023
1024 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
1025 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
1026
1027 <para>
1028 The <filename>LIC_FILES_CHKSUM</filename>
1029 variable contains checksums of the license text in the source code for the recipe.
1030 Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
1031 <literallayout class='monospaced'>
1032 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
1033 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
1034 file://licfile2.txt;endline=50;md5=zzzz \
1035 ..."
1036 </literallayout>
1037 </para>
1038
1039 <para>
1040 The build system uses the
1041 <filename><link linkend='var-S'>S</link></filename> variable as
1042 the default directory used when searching files listed in
1043 <filename>LIC_FILES_CHKSUM</filename>.
1044 The previous example employs the default directory.
1045 </para>
1046
1047 <para>
1048 Consider this next example:
1049 <literallayout class='monospaced'>
1050 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
1051 md5=bb14ed3c4cda583abc85401304b5cd4e"
1052 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1053 </literallayout>
1054 </para>
1055
1056 <para>
1057 The first line locates a file in
1058 <filename>${S}/src/ls.c</filename>.
1059 The second line refers to a file in
1060 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
1061 </para>
1062 <para>
1063 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
1064 mandatory for all recipes, unless the
1065 <filename>LICENSE</filename> variable is set to "CLOSED".
1066 </para>
1067 </section>
1068
1069 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
1070 <title>Explanation of Syntax</title>
1071 <para>
1072 As mentioned in the previous section, the
1073 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
1074 important files that contain the license text for the source code.
1075 It is possible to specify a checksum for an entire file, or a specific section of a
1076 file (specified by beginning and ending line numbers with the "beginline" and "endline"
1077 parameters, respectively).
1078 The latter is useful for source files with a license notice header,
1079 README documents, and so forth.
1080 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
1081 first line of the file.
1082 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
1083 ends with the last line of the file.
1084 </para>
1085
1086 <para>
1087 The "md5" parameter stores the md5 checksum of the license text.
1088 If the license text changes in any way as compared to this parameter
1089 then a mismatch occurs.
1090 This mismatch triggers a build failure and notifies the developer.
1091 Notification allows the developer to review and address the license text changes.
1092 Also note that if a mismatch occurs during the build, the correct md5
1093 checksum is placed in the build log and can be easily copied to the recipe.
1094 </para>
1095
1096 <para>
1097 There is no limit to how many files you can specify using the
1098 <filename>LIC_FILES_CHKSUM</filename> variable.
1099 Generally, however, every project requires a few specifications for license tracking.
1100 Many projects have a "COPYING" file that stores the license information for all the source
1101 code files.
1102 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
1103 </para>
1104
1105 <tip>
1106 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
1107 error and displays the correct "md5" parameter value during the build.
1108 The correct parameter is also captured in the build log.
1109 </tip>
1110
1111 <tip>
1112 If the whole file contains only license text, you do not need to use the "beginline" and
1113 "endline" parameters.
1114 </tip>
1115 </section>
1116 </section>
1117
1118 <section id="enabling-commercially-licensed-recipes">
1119 <title>Enabling Commercially Licensed Recipes</title>
1120
1121 <para>
1122 By default, the OpenEmbedded build system disables
1123 components that have commercial or other special licensing
1124 requirements.
1125 Such requirements are defined on a
1126 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
1127 definition in the affected recipe.
1128 For instance, the
1129 <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1130 recipe contains the following statement:
1131 <literallayout class='monospaced'>
1132 LICENSE_FLAGS = "commercial"
1133 </literallayout>
1134 Here is a slightly more complicated example that contains both an
1135 explicit recipe name and version (after variable expansion):
1136 <literallayout class='monospaced'>
1137 LICENSE_FLAGS = "license_${PN}_${PV}"
1138 </literallayout>
1139 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
1140 definition to be enabled and included in an image, it
1141 needs to have a matching entry in the global
1142 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
1143 typically defined in your <filename>local.conf</filename> file.
1144 For example, to enable
1145 the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1146 package, you could add either the string
1147 "commercial_gst-plugins-ugly" or the more general string
1148 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
1149 See the
1150 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
1151 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
1152 Here is the example:
1153 <literallayout class='monospaced'>
1154 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
1155 </literallayout>
1156 Likewise, to additionally enable the package built from the recipe containing
1157 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
1158 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
1159 the following string would enable that package as well as
1160 the original <filename>gst-plugins-ugly</filename> package:
1161 <literallayout class='monospaced'>
1162 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
1163 </literallayout>
1164 As a convenience, you do not need to specify the complete license string
1165 in the whitelist for every package.
1166 you can use an abbreviated form, which consists
1167 of just the first portion or portions of the license string before
1168 the initial underscore character or characters.
1169 A partial string will match
1170 any license that contains the given string as the first
1171 portion of its license.
1172 For example, the following
1173 whitelist string will also match both of the packages
1174 previously mentioned as well as any other packages that have
1175 licenses starting with "commercial" or "license".
1176 <literallayout class='monospaced'>
1177 LICENSE_FLAGS_WHITELIST = "commercial license"
1178 </literallayout>
1179 </para>
1180
1181 <section id="license-flag-matching">
1182 <title>License Flag Matching</title>
1183
1184 <para>
1185 License flag matching allows you to control what recipes the
1186 OpenEmbedded build system includes in the build.
1187 Fundamentally, the build system attempts to match
1188 <filename>LICENSE_FLAG</filename> strings found in
1189 recipes against <filename>LICENSE_FLAGS_WHITELIST</filename>
1190 strings found in the whitelist.
1191 A match, causes the build system to include a recipe in the
1192 build, while failure to find a match causes the build system to
1193 exclude a recipe.
1194 </para>
1195
1196 <para>
1197 In general, license flag matching is simple.
1198 However, understanding some concepts will help you
1199 correctly and effectively use matching.
1200 </para>
1201
1202 <para>
1203 Before a flag
1204 defined by a particular recipe is tested against the
1205 contents of the whitelist, the expanded string
1206 <filename>_${PN}</filename> is appended to the flag.
1207 This expansion makes each <filename>LICENSE_FLAGS</filename>
1208 value recipe-specific.
1209 After expansion, the string is then matched against the
1210 whitelist.
1211 Thus, specifying
1212 <filename>LICENSE_FLAGS = "commercial"</filename>
1213 in recipe "foo", for example, results in the string
1214 <filename>"commercial_foo"</filename>.
1215 And, to create a match, that string must appear in the
1216 whitelist.
1217 </para>
1218
1219 <para>
1220 Judicious use of the <filename>LICENSE_FLAGS</filename>
1221 strings and the contents of the
1222 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
1223 allows you a lot of flexibility for including or excluding
1224 recipes based on licensing.
1225 For example, you can broaden the matching capabilities by
1226 using license flags string subsets in the whitelist.
1227 <note>When using a string subset, be sure to use the part of
1228 the expanded string that precedes the appended underscore
1229 character (e.g. <filename>usethispart_1.3</filename>,
1230 <filename>usethispart_1.4</filename>, and so forth).
1231 </note>
1232 For example, simply specifying the string "commercial" in
1233 the whitelist matches any expanded
1234 <filename>LICENSE_FLAGS</filename> definition that starts with
1235 the string "commercial" such as "commercial_foo" and
1236 "commercial_bar", which are the strings the build system
1237 automatically generates for hypothetical recipes named
1238 "foo" and "bar" assuming those recipes simply specify the
1239 following:
1240 <literallayout class='monospaced'>
1241 LICENSE_FLAGS = "commercial"
1242 </literallayout>
1243 Thus, you can choose to exhaustively
1244 enumerate each license flag in the whitelist and
1245 allow only specific recipes into the image, or
1246 you can use a string subset that causes a broader range of
1247 matches to allow a range of recipes into the image.
1248 </para>
1249
1250 <para>
1251 This scheme works even if the
1252 <filename>LICENSE_FLAG</filename> string already
1253 has <filename>_${PN}</filename> appended.
1254 For example, the build system turns the license flag
1255 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
1256 match both the general "commercial" and the specific
1257 "commercial_1.2_foo" strings found in the whitelist, as
1258 expected.
1259 </para>
1260
1261 <para>
1262 Here are some other scenarios:
1263 <itemizedlist>
1264 <listitem><para>You can specify a versioned string in the
1265 recipe such as "commercial_foo_1.2" in a "foo" recipe.
1266 The build system expands this string to
1267 "commercial_foo_1.2_foo".
1268 Combine this license flag with a whitelist that has
1269 the string "commercial" and you match the flag along
1270 with any other flag that starts with the string
1271 "commercial".</para></listitem>
1272 <listitem><para>Under the same circumstances, you can
1273 use "commercial_foo" in the whitelist and the
1274 build system not only matches "commercial_foo_1.2" but
1275 also matches any license flag with the string
1276 "commercial_foo", regardless of the version.
1277 </para></listitem>
1278 <listitem><para>You can be very specific and use both the
1279 package and version parts in the whitelist (e.g.
1280 "commercial_foo_1.2") to specifically match a
1281 versioned recipe.</para></listitem>
1282 </itemizedlist>
1283 </para>
1284 </section>
1285
1286 <section id="other-variables-related-to-commercial-licenses">
1287 <title>Other Variables Related to Commercial Licenses</title>
1288
1289 <para>
1290 Other helpful variables related to commercial
1291 license handling exist and are defined in the
1292 <filename>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
1293 <literallayout class='monospaced'>
1294 COMMERCIAL_AUDIO_PLUGINS ?= ""
1295 COMMERCIAL_VIDEO_PLUGINS ?= ""
1296 COMMERCIAL_QT = ""
1297 </literallayout>
1298 If you want to enable these components, you can do so by making sure you have
1299 statements similar to the following
1300 in your <filename>local.conf</filename> configuration file:
1301 <literallayout class='monospaced'>
1302 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
1303 gst-plugins-ugly-mpegaudioparse"
1304 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
1305 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
1306 COMMERCIAL_QT ?= "qmmp"
1307 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
1308 </literallayout>
1309 Of course, you could also create a matching whitelist
1310 for those components using the more general "commercial"
1311 in the whitelist, but that would also enable all the
1312 other packages with <filename>LICENSE_FLAGS</filename> containing
1313 "commercial", which you may or may not want:
1314 <literallayout class='monospaced'>
1315 LICENSE_FLAGS_WHITELIST = "commercial"
1316 </literallayout>
1317 </para>
1318
1319 <para>
1320 Specifying audio and video plug-ins as part of the
1321 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
1322 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
1323 or commercial Qt components as part of
1324 the <filename>COMMERCIAL_QT</filename> statement (along
1325 with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
1326 plug-ins or components into built images, thus adding
1327 support for media formats or components.
1328 </para>
1329 </section>
1330 </section>
1331</section>
1332</chapter>
1333<!--
1334vim: expandtab tw=80 ts=4
1335-->
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
new file mode 100644
index 0000000000..b00e7bc14e
--- /dev/null
+++ b/documentation/ref-manual/usingpoky.xml
@@ -0,0 +1,848 @@
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> 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 See the "<link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>"
52 section for more information on this script.
53 </para>
54
55 <para>
56 Once the build environment is set up, you can build a target using:
57 <literallayout class='monospaced'>
58 $ bitbake &lt;target&gt;
59 </literallayout>
60 </para>
61
62 <para>
63 The <filename>target</filename> is the name of the recipe you want to build.
64 Common targets are the images in <filename>meta/recipes-core/images</filename>,
65 <filename>/meta/recipes-sato/images</filename>, etc. all found in the
66 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
67 Or, the target can be the name of a recipe for a specific piece of software such as
68 BusyBox.
69 For more details about the images the OpenEmbedded build system supports, see the
70 "<link linkend="ref-images">Images</link>" chapter.
71 </para>
72
73 <note>
74 Building an image without GNU General Public License Version 3 (GPLv3) components
75 is only supported for minimal and base images.
76 See the "<link linkend='ref-images'>Images</link>" chapter for more information.
77 </note>
78 </section>
79
80 <section id='building-an-image-using-gpl-components'>
81 <title>Building an Image Using GPL Components</title>
82
83 <para>
84 When building an image using GPL components, you need to maintain your original
85 settings and not switch back and forth applying different versions of the GNU
86 General Public License.
87 If you rebuild using different versions of GPL, dependency errors might occur
88 due to some components not being rebuilt.
89 </para>
90 </section>
91</section>
92
93<section id='usingpoky-install'>
94 <title>Installing and Using the Result</title>
95
96 <para>
97 Once an image has been built, it often needs to be installed.
98 The images and kernels built by the OpenEmbedded build system are placed in the
99 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
100 <filename class="directory">tmp/deploy/images</filename>.
101 For information on how to run pre-built images such as <filename>qemux86</filename>
102 and <filename>qemuarm</filename>, see the
103 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
104 section in the Yocto Project Quick Start.
105 For information about how to install these images, see the documentation for your
106 particular board or machine.
107 </para>
108</section>
109
110<section id='usingpoky-debugging'>
111 <title>Debugging Build Failures</title>
112
113 <para>
114 The exact method for debugging build failures depends on the nature of the
115 problem and on the system's area from which the bug originates.
116 Standard debugging practices such as comparison against the last
117 known working version with examination of the changes and the re-application of steps
118 to identify the one causing the problem are
119 valid for the Yocto Project just as they are for any other system.
120 Even though it is impossible to detail every possible potential failure,
121 this section provides some general tips to aid in debugging.
122 </para>
123
124 <para>
125 For discussions on debugging, see the
126 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
127 and
128 "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working within Eclipse</ulink>"
129 sections in the Yocto Project Development Manual.
130 </para>
131
132 <section id='usingpoky-debugging-taskfailures'>
133 <title>Task Failures</title>
134
135 <para>The log file for shell tasks is available in
136 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
137 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
138 machine (<filename>qemux86</filename>) might be
139 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>.
140 To see what BitBake runs to generate that log, look at the corresponding
141 <filename>run.do_taskname.pid</filename> file located in the same directory.
142 </para>
143
144 <para>
145 Presently, the output from Python tasks is sent directly to the console.
146 </para>
147 </section>
148
149 <section id='usingpoky-debugging-taskrunning'>
150 <title>Running Specific Tasks</title>
151
152 <para>
153 Any given package consists of a set of tasks.
154 The standard BitBake behavior in most cases is: <filename>fetch</filename>,
155 <filename>unpack</filename>,
156 <filename>patch</filename>, <filename>configure</filename>,
157 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
158 <filename>package_write</filename>, and <filename>build</filename>.
159 The default task is <filename>build</filename> and any tasks on which it depends
160 build first.
161 Some tasks exist, such as <filename>devshell</filename>, that are not part of the
162 default build chain.
163 If you wish to run a task that is not part of the default build chain, you can use the
164 <filename>-c</filename> option in BitBake.
165 Here is an example:
166 <literallayout class='monospaced'>
167 $ bitbake matchbox-desktop -c devshell
168 </literallayout>
169 </para>
170
171 <para>
172 If you wish to rerun a task, use the <filename>-f</filename> force option.
173 For example, the following sequence forces recompilation after changing files in the
174 working directory.
175 <literallayout class='monospaced'>
176 $ bitbake matchbox-desktop
177 .
178 .
179 [make some changes to the source code in the working directory]
180 .
181 .
182 $ bitbake matchbox-desktop -c compile -f
183 $ bitbake matchbox-desktop
184 </literallayout>
185 </para>
186
187 <para>
188 This sequence first builds and then recompiles
189 <filename>matchbox-desktop</filename>.
190 The last command reruns all tasks (basically the packaging tasks) after the compile.
191 BitBake recognizes that the <filename>compile</filename> task was rerun and therefore
192 understands that the other tasks also need to be run again.
193 </para>
194
195 <para>
196 You can view a list of tasks in a given package by running the
197 <filename>listtasks</filename> task as follows:
198 <literallayout class='monospaced'>
199 $ bitbake matchbox-desktop -c listtasks
200 </literallayout>
201 The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
202 </para>
203 </section>
204
205 <section id='usingpoky-debugging-dependencies'>
206 <title>Dependency Graphs</title>
207
208 <para>
209 Sometimes it can be hard to see why BitBake wants to build some other packages before a given
210 package you have specified.
211 The <filename>bitbake -g targetname</filename> command creates the
212 <filename>depends.dot</filename>, <filename>package-depends.dot</filename>,
213 and <filename>task-depends.dot</filename> files in the current directory.
214 These files show the package and task dependencies and are useful for debugging problems.
215 You can use the <filename>bitbake -g -u depexp targetname</filename> command to
216 display the results in a more human-readable form.
217 </para>
218 </section>
219
220 <section id='usingpoky-debugging-bitbake'>
221 <title>General BitBake Problems</title>
222
223 <para>
224 You can see debug output from BitBake by using the <filename>-D</filename> option.
225 The debug output gives more information about what BitBake
226 is doing and the reason behind it.
227 Each <filename>-D</filename> option you use increases the logging level.
228 The most common usage is <filename>-DDD</filename>.
229 </para>
230
231 <para>
232 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
233 BitBake chose a certain version of a package or why BitBake
234 picked a certain provider.
235 This command could also help you in a situation where you think BitBake did something
236 unexpected.
237 </para>
238 </section>
239
240 <section id='development-host-system-issues'>
241 <title>Development Host System Issues</title>
242
243 <para>
244 Sometimes issues on the host development system can cause your
245 build to fail.
246 Following are known, host-specific problems.
247 Be sure to always consult the
248 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
249 for a look at all release-related issues.
250 <itemizedlist>
251 <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>:
252 If your development host system has the unpatched
253 <filename>GNU Make 3.82</filename>,
254 the <filename>do_install</filename> task
255 fails for <filename>eglibc-initial</filename> during the
256 build.</para>
257 <para>Typically, every distribution that ships
258 <filename>GNU Make 3.82</filename> as
259 the default already has the patched version.
260 However, some distributions, such as Debian, have
261 <filename>GNU Make 3.82</filename> as an option, which
262 is unpatched.
263 You will see this error on these types of distributions.
264 Switch to <filename>GNU Make 3.81</filename> or patch
265 your <filename>make</filename> to solve the problem.
266 </para></listitem>
267 </itemizedlist>
268 </para>
269 </section>
270
271 <section id='usingpoky-debugging-buildfile'>
272 <title>Building with No Dependencies</title>
273 <para>
274 If you really want to build a specific <filename>.bb</filename> file, you can use
275 the command form <filename>bitbake -b &lt;somepath/somefile.bb&gt;</filename>.
276 This command form does not check for dependencies so you should use it
277 only when you know its dependencies already exist.
278 You can also specify fragments of the filename.
279 In this case, BitBake checks for a unique match.
280 </para>
281 </section>
282
283 <section id='usingpoky-debugging-variables'>
284 <title>Variables</title>
285 <para>
286 You can use the <filename>-e</filename> BitBake option to
287 display the resulting environment for a configuration
288 when you do not specify a package or for a specific package when
289 you do specify the package.
290 If you want to show the environment resulting from parsing a single
291 recipe, use the <filename>-b recipename</filename> form.
292 </para>
293 </section>
294
295 <section id='recipe-logging-mechanisms'>
296 <title>Recipe Logging Mechanisms</title>
297 <para>
298 Best practices exist while writing recipes that both log build progress and
299 act on build conditions such as warnings and errors.
300 Both Python and Bash language bindings exist for the logging mechanism:
301 <itemizedlist>
302 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
303 supports several loglevels: <filename>bb.fatal</filename>,
304 <filename>bb.error</filename>, <filename>bb.warn</filename>,
305 <filename>bb.note</filename>, <filename>bb.plain</filename>,
306 and <filename>bb.debug</filename>.</para></listitem>
307 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
308 of loglevels exist and are accessed with a similar syntax:
309 <filename>bbfatal</filename>, <filename>bberror</filename>,
310 <filename>bbwarn</filename>, <filename>bbnote</filename>,
311 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
312 </itemizedlist>
313 </para>
314
315 <para>
316 For guidance on how logging is handled in both Python and Bash recipes, see the
317 <filename>logging.bbclass</filename> file in the
318 <filename>meta/classes</filename> folder of the
319 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
320 </para>
321
322 <section id='logging-with-python'>
323 <title>Logging With Python</title>
324 <para>
325 When creating recipes using Python and inserting code that handles build logs,
326 keep in mind the goal is to have informative logs while keeping the console as
327 "silent" as possible.
328 Also, if you want status messages in the log, use the "debug" loglevel.
329 </para>
330
331 <para>
332 Following is an example written in Python.
333 The code handles logging for a function that determines the number of tasks
334 needed to be run:
335 <literallayout class='monospaced'>
336 python do_listtasks() {
337 bb.debug(2, "Starting to figure out the task list")
338 if noteworthy_condition:
339 bb.note("There are 47 tasks to run")
340 bb.debug(2, "Got to point xyz")
341 if warning_trigger:
342 bb.warn("Detected warning_trigger, this might be a problem later.")
343 if recoverable_error:
344 bb.error("Hit recoverable_error, you really need to fix this!")
345 if fatal_error:
346 bb.fatal("fatal_error detected, unable to print the task list")
347 bb.plain("The tasks present are abc")
348 bb.debug(2, "Finished figuring out the tasklist")
349 }
350 </literallayout>
351 </para>
352 </section>
353
354 <section id='logging-with-bash'>
355 <title>Logging With Bash</title>
356 <para>
357 When creating recipes using Bash and inserting code that handles build
358 logs, you have the same goals - informative with minimal console output.
359 The syntax you use for recipes written in Bash is similar to that of
360 recipes written in Python described in the previous section.
361 </para>
362
363 <para>
364 Following is an example written in Bash.
365 The code logs the progress of the <filename>do_my_function</filename> function.
366 <literallayout class='monospaced'>
367 do_my_function() {
368 bbdebug 2 "Running do_my_function"
369 if [ exceptional_condition ]; then
370 bbnote "Hit exceptional_condition"
371 fi
372 bbdebug 2 "Got to point xyz"
373 if [ warning_trigger ]; then
374 bbwarn "Detected warning_trigger, this might cause a problem later."
375 fi
376 if [ recoverable_error ]; then
377 bberror "Hit recoverable_error, correcting"
378 fi
379 if [ fatal_error ]; then
380 bbfatal "fatal_error detected"
381 fi
382 bbdebug 2 "Completed do_my_function"
383 }
384 </literallayout>
385 </para>
386 </section>
387 </section>
388
389 <section id='usingpoky-debugging-others'>
390 <title>Other Tips</title>
391
392 <para>
393 Here are some other tips that you might find useful:
394 <itemizedlist>
395 <listitem><para>When adding new packages, it is worth watching for
396 undesirable items making their way into compiler command lines.
397 For example, you do not want references to local system files like
398 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
399 </para></listitem>
400 <listitem><para>If you want to remove the <filename>psplash</filename>
401 boot splashscreen,
402 add <filename>psplash=false</filename> to the kernel command line.
403 Doing so prevents <filename>psplash</filename> from loading
404 and thus allows you to see the console.
405 It is also possible to switch out of the splashscreen by
406 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
407 </para></listitem>
408 </itemizedlist>
409 </para>
410 </section>
411</section>
412
413<section id='maintaining-build-output-quality'>
414 <title>Maintaining Build Output Quality</title>
415
416 <para>
417 Many factors can influence the quality of a build.
418 For example, if you upgrade a recipe to use a new version of an upstream software
419 package or you experiment with some new configuration options, subtle changes
420 can occur that you might not detect until later.
421 Consider the case where your recipe is using a newer version of an upstream package.
422 In this case, a new version of a piece of software might introduce an optional
423 dependency on another library, which is auto-detected.
424 If that library has already been built when the software is building,
425 the software will link to the built library and that library will be pulled
426 into your image along with the new software even if you did not want the
427 library.
428 </para>
429
430 <para>
431 The <filename>buildhistory</filename> class exists to help you maintain
432 the quality of your build output.
433 You can use the class to highlight unexpected and possibly unwanted
434 changes in the build output.
435 When you enable build history, it records information about the contents of
436 each package and image and then commits that information to a local Git
437 repository where you can examine the information.
438 </para>
439
440 <para>
441 The remainder of this section describes the following:
442 <itemizedlist>
443 <listitem><para>How you can enable and disable
444 build history</para></listitem>
445 <listitem><para>How to understand what the build history contains
446 </para></listitem>
447 <listitem><para>How to limit the information used for build history
448 </para></listitem>
449 <listitem><para>How to examine the build history from both a
450 command-line and web interface</para></listitem>
451 </itemizedlist>
452 </para>
453
454 <section id='enabling-and-disabling-build-history'>
455 <title>Enabling and Disabling Build History</title>
456
457 <para>
458 Build history is disabled by default.
459 To enable it, add the following statements to the end of your
460 <filename>conf/local.conf</filename> file found in the
461 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
462 <literallayout class='monospaced'>
463 INHERIT += "buildhistory"
464 BUILDHISTORY_COMMIT = "1"
465 </literallayout>
466 Enabling build history as previously described
467 causes the build process to collect build
468 output information and commit it to a local
469 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
470 <note>
471 Enabling build history increases your build times slightly,
472 particularly for images, and increases the amount of disk
473 space used during the build.
474 </note>
475 </para>
476
477 <para>
478 You can disable build history by removing the previous statements
479 from your <filename>conf/local.conf</filename> file.
480 However, you should realize that enabling and disabling
481 build history in this manner can change the
482 <filename>do_package</filename> task checksums, which if you
483 are using the OEBasicHash signature generator (the default
484 for many current distro configurations including
485 <filename>DISTRO = "poky"</filename> and
486 <filename>DISTRO = ""</filename>) and will result in the packaging
487 tasks being re-run during the subsequent build.
488 </para>
489
490 <para>
491 To disable the build history functionality without causing the
492 packaging tasks to be re-run, add this statement to your
493 <filename>conf/local.conf</filename> file:
494 <literallayout class='monospaced'>
495 BUILDHISTORY_FEATURES = ""
496 </literallayout>
497 </para>
498 </section>
499
500 <section id='understanding-what-the-build-history-contains'>
501 <title>Understanding What the Build History Contains</title>
502
503 <para>
504 Build history information is kept in
505 <filename>$</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>/buildhistory</filename>
506 in the Build Directory.
507 The following is an example abbreviated listing:
508 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
509 </para>
510
511 <para>
512 At the top level, there is a <filename>metadata-revs</filename> file
513 that lists the revisions of the repositories for the layers enabled
514 when the build was produced.
515 The rest of the data splits into separate
516 <filename>packages</filename>, <filename>images</filename> and
517 <filename>sdk</filename> directories, the contents of which are
518 described below.
519 </para>
520
521 <section id='build-history-package-information'>
522 <title>Build History Package Information</title>
523
524 <para>
525 The history for each package contains a text file that has
526 name-value pairs with information about the package.
527 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
528 contains the following:
529 <literallayout class='monospaced'>
530 PV = 1.19.3
531 PR = r3
532 RDEPENDS = update-rc.d eglibc (>= 2.13)
533 RRECOMMENDS = busybox-syslog busybox-udhcpc
534 PKGSIZE = 564701
535 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
536 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
537 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
538 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
539 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
540 </literallayout>
541 Most of these name-value pairs correspond to variables used
542 to produce the package.
543 The exceptions are <filename>FILELIST</filename>, which is the
544 actual list of files in the package, and
545 <filename>PKGSIZE</filename>, which is the total size of files
546 in the package in bytes.
547 </para>
548
549 <para>
550 There is also a file corresponding to the recipe from which the
551 package came (e.g.
552 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
553 <literallayout class='monospaced'>
554 PV = 1.19.3
555 PR = r3
556 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
557 virtual/libc update-rc.d-native
558 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
559 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
560 busybox-staticdev busybox-locale
561 </literallayout>
562 </para>
563
564 <para>
565 Finally, for those recipes fetched from a version control
566 system (e.g., Git), a file exists that lists source revisions
567 that are specified in the recipe and lists the actual revisions
568 used during the build.
569 Listed and actual revisions might differ when
570 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
571 is set to
572 <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>.
573 Here is an example assuming
574 <filename>buildhistory/packages/emenlow-poky-linux/linux-yocto/latest_srcrev</filename>):
575 <literallayout class='monospaced'>
576 # SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
577 SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
578 # SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
579 SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
580 # SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
581 SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
582 </literallayout>
583 You can use the <filename>buildhistory-collect-srcrevs</filename>
584 command to collect the stored <filename>SRCREV</filename> values
585 from build history and report them in a format suitable for use in
586 global configuration (e.g., <filename>local.conf</filename>
587 or a distro include file) to override floating
588 <filename>AUTOREV</filename> values to a fixed set of revisions.
589 Here is some example output from this command:
590 <literallayout class='monospaced'>
591 # emenlow-poky-linux
592 SRCREV_machine_pn-linux-yocto = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
593 SRCREV_emgd_pn-linux-yocto = "caea08c988e0f41103bbe18eafca20348f95da02"
594 SRCREV_meta_pn-linux-yocto = "c2ed0f16fdec628242a682897d5d86df4547cf24"
595 # core2-poky-linux
596 SRCREV_pn-kmod = "62081c0f68905b22f375156d4532fd37fa5c8d33"
597 SRCREV_pn-blktrace = "d6918c8832793b4205ed3bfede78c2f915c23385"
598 SRCREV_pn-opkg = "649"
599 </literallayout>
600 <note>
601 Here are some notes on using the
602 <filename>buildhistory-collect-srcrevs</filename> command:
603 <itemizedlist>
604 <listitem><para>By default, only values where the
605 <filename>SRCREV</filename> was
606 not hardcoded (usually when <filename>AUTOREV</filename>
607 was used) are reported.
608 Use the <filename>-a</filename> option to see all
609 <filename>SRCREV</filename> values.
610 </para></listitem>
611 <listitem><para>The output statements might not have any effect
612 if overrides are applied elsewhere in the build system
613 configuration.
614 Use the <filename>-f</filename> option to add the
615 <filename>forcevariable</filename> override to each output line
616 if you need to work around this restriction.
617 </para></listitem>
618 <listitem><para>The script does apply special handling when
619 building for multiple machines.
620 However, the script does place a
621 comment before each set of values that specifies
622 which triplet to which they belong as shown above
623 (e.g., <filename>emenlow-poky-linux</filename>).
624 </para></listitem>
625 </itemizedlist>
626 </note>
627 </para>
628 </section>
629
630 <section id='build-history-image-information'>
631 <title>Build History Image Information</title>
632
633 <para>
634 The files produced for each image are as follows:
635 <itemizedlist>
636 <listitem><para><filename>image-files:</filename>
637 A directory containing selected files from the root
638 filesystem.
639 The files are defined by
640 <filename>BUILDHISTORY_IMAGE_FILES</filename>.
641 </para></listitem>
642 <listitem><para><filename>build-id:</filename>
643 Human-readable information about the build configuration
644 and metadata source revisions.</para></listitem>
645 <listitem><para><filename>*.dot:</filename>
646 Dependency graphs for the image that are
647 compatible with <filename>graphviz</filename>.
648 </para></listitem>
649 <listitem><para><filename>files-in-image.txt:</filename>
650 A list of files in the image with permissions,
651 owner, group, size, and symlink information.
652 </para></listitem>
653 <listitem><para><filename>image-info.txt:</filename>
654 A text file containing name-value pairs with information
655 about the image.
656 See the following listing example for more information.
657 </para></listitem>
658 <listitem><para><filename>installed-package-names.txt:</filename>
659 A list of installed packages by name only.</para></listitem>
660 <listitem><para><filename>installed-package-sizes.txt:</filename>
661 A list of installed packages ordered by size.
662 </para></listitem>
663 <listitem><para><filename>installed-packages.txt:</filename>
664 A list of installed packages with full package
665 filenames.</para></listitem>
666 </itemizedlist>
667 <note>
668 Installed package information is able to be gathered and
669 produced even if package management is disabled for the final
670 image.
671 </note>
672 </para>
673
674 <para>
675 Here is an example of <filename>image-info.txt</filename>:
676 <literallayout class='monospaced'>
677 DISTRO = poky
678 DISTRO_VERSION = 1.1+snapshot-20120207
679 USER_CLASSES = image-mklibs image-prelink
680 IMAGE_CLASSES = image_types
681 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
682 package-management ssh-server-dropbear package-management
683 IMAGE_LINGUAS = en-us en-gb
684 IMAGE_INSTALL = task-core-boot task-base-extended
685 BAD_RECOMMENDATIONS =
686 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
687 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
688 IMAGESIZE = 171816
689 </literallayout>
690 Other than <filename>IMAGESIZE</filename>, which is the
691 total size of the files in the image in Kbytes, the
692 name-value pairs are variables that may have influenced the
693 content of the image.
694 This information is often useful when you are trying to determine
695 why a change in the package or file listings has occurred.
696 </para>
697 </section>
698
699 <section id='using-build-history-to-gather-image-information-only'>
700 <title>Using Build History to Gather Image Information Only</title>
701
702 <para>
703 As you can see, build history produces image information,
704 including dependency graphs, so you can see why something
705 was pulled into the image.
706 If you are just interested in this information and not
707 interested in collecting history or any package information,
708 you can enable writing only image information without
709 any history by adding the following
710 to your <filename>conf/local.conf</filename> file found in the
711 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
712 <literallayout class='monospaced'>
713 INHERIT += "buildhistory"
714 BUILDHISTORY_COMMIT = "0"
715 BUILDHISTORY_FEATURES = "image"
716 </literallayout>
717 </para>
718 </section>
719
720 <section id='build-history-sdk-information'>
721 <title>Build History SDK Information</title>
722 <para>
723 Build history collects similar information on the contents
724 of SDKs (e.g., <filename>meta-toolchain</filename>
725 or <filename>bitbake -c populate_sdk imagename</filename>)
726 as compared to information it collects for images.
727 The following list shows the files produced for each SDK:
728 <itemizedlist>
729 <listitem><para><filename>files-in-sdk.txt:</filename>
730 A list of files in the SDK with permissions,
731 owner, group, size, and symlink information.
732 This list includes both the host and target parts
733 of the SDK.
734 </para></listitem>
735 <listitem><para><filename>sdk-info.txt:</filename>
736 A text file containing name-value pairs with information
737 about the SDK.
738 See the following listing example for more information.
739 </para></listitem>
740 <listitem><para>The following information appears under
741 each of the <filename>host</filename>
742 and <filename>target</filename> directories
743 for the portions of the SDK that run on the host and
744 on the target, respectively:
745 <itemizedlist>
746 <listitem><para><filename>depends.dot:</filename>
747 Dependency graph for the SDK that is
748 compatible with <filename>graphviz</filename>.
749 </para></listitem>
750 <listitem><para><filename>installed-package-names.txt:</filename>
751 A list of installed packages by name only.
752 </para></listitem>
753 <listitem><para><filename>installed-package-sizes.txt:</filename>
754 A list of installed packages ordered by size.
755 </para></listitem>
756 <listitem><para><filename>installed-packages.txt:</filename>
757 A list of installed packages with full package
758 filenames.</para></listitem>
759 </itemizedlist>
760 </para></listitem>
761 </itemizedlist>
762 </para>
763
764 <para>
765 Here is an example of <filename>sdk-info.txt</filename>:
766 <literallayout class='monospaced'>
767 DISTRO = poky
768 DISTRO_VERSION = 1.3+snapshot-20130327
769 SDK_NAME = poky-eglibc-i686-arm
770 SDK_VERSION = 1.3+snapshot
771 SDKMACHINE =
772 SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
773 BAD_RECOMMENDATIONS =
774 SDKSIZE = 352712
775 </literallayout>
776 Other than <filename>SDKSIZE</filename>, which is the
777 total size of the files in the SDK in Kbytes, the
778 name-value pairs are variables that might have influenced the
779 content of the SDK.
780 This information is often useful when you are trying to
781 determine why a change in the package or file listings
782 has occurred.
783 </para>
784 </section>
785
786 <section id='examining-build-history-information'>
787 <title>Examining Build History Information</title>
788
789 <para>
790 You can examine build history output from the command line or
791 from a web interface.
792 </para>
793
794 <para>
795 To see any changes that have occurred (assuming you have
796 <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply
797 use any Git command that allows you to view the history of
798 a repository.
799 Here is one method:
800 <literallayout class='monospaced'>
801 $ git log -p
802 </literallayout>
803 You need to realize, however, that this method does show
804 changes that are not significant (e.g. a package's size
805 changing by a few bytes).
806 </para>
807
808 <para>
809 A command-line tool called <filename>buildhistory-diff</filename>
810 does exist, though, that queries the Git repository and prints just
811 the differences that might be significant in human-readable form.
812 Here is an example:
813 <literallayout class='monospaced'>
814 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
815 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
816 /etc/anotherpkg.conf was added
817 /sbin/anotherpkg was added
818 * (installed-package-names.txt):
819 * anotherpkg was added
820 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
821 anotherpkg was added
822 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
823 * PR changed from "r0" to "r1"
824 * PV changed from "0.1.10" to "0.1.12"
825 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
826 * PR changed from "r0" to "r1"
827 * PV changed from "0.1.10" to "0.1.12"
828 </literallayout>
829 </para>
830
831 <para>
832 To see changes to the build history using a web interface, follow
833 the instruction in the <filename>README</filename> file here.
834 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
835 </para>
836
837 <para>
838 Here is a sample screenshot of the interface:
839 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
840 </para>
841 </section>
842 </section>
843</section>
844
845</chapter>
846<!--
847vim: expandtab tw=80 ts=4
848-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-28 18:10:08 +0000