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.xml1270
-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.xml685
-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 -> 50418 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.xml556
-rw-r--r--documentation/ref-manual/migration.xml1616
-rw-r--r--documentation/ref-manual/ref-bitbake.xml472
-rw-r--r--documentation/ref-manual/ref-classes.xml3255
-rw-r--r--documentation/ref-manual/ref-features.xml344
-rw-r--r--documentation/ref-manual/ref-images.xml167
-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.xml146
-rw-r--r--documentation/ref-manual/ref-structure.xml1039
-rw-r--r--documentation/ref-manual/ref-style.css979
-rw-r--r--documentation/ref-manual/ref-variables.xml8419
-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.xml1409
-rw-r--r--documentation/ref-manual/usingpoky.xml882
41 files changed, 21674 insertions, 0 deletions
diff --git a/documentation/ref-manual/TODO b/documentation/ref-manual/TODO
new file mode 100644
index 0000000..ee0db97
--- /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 0000000..c223bbb
--- /dev/null
+++ b/documentation/ref-manual/closer-look.xml
@@ -0,0 +1,1270 @@
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
37 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
38 This block expands on how BitBake fetches source, applies
39 patches, completes compilation, analyzes output for package
40 generation, creates and tests packages, generates images, and
41 generates cross-development tools.</para></listitem>
42 <listitem><para><emphasis>Package Feeds:</emphasis>
43 Directories containing output packages (RPM, DEB or IPK),
44 which are subsequently used in the construction of an image or
45 SDK, produced by the build system.
46 These feeds can also be copied and shared using a web server or
47 other means to facilitate extending or updating existing
48 images on devices at runtime if runtime package management is
49 enabled.</para></listitem>
50 <listitem><para><emphasis>Images:</emphasis>
51 Images produced by the development process.
52 </para></listitem>
53 <listitem><para><emphasis>Application Development SDK:</emphasis>
54 Cross-development tools that are produced along with an image
55 or separately with BitBake.</para></listitem>
56 </itemizedlist>
57 </para>
58
59 <section id="user-configuration">
60 <title>User Configuration</title>
61
62 <para>
63 User configuration helps define the build.
64 Through user configuration, you can tell BitBake the
65 target architecture for which you are building the image,
66 where to store downloaded source, and other build properties.
67 </para>
68
69 <para>
70 The following figure shows an expanded representation of the
71 "User Configuration" box of the
72 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
73 </para>
74
75 <para>
76 <imagedata fileref="figures/user-configuration.png" align="center" width="5.5in" depth="3.5in" />
77 </para>
78
79 <para>
80 BitBake needs some basic configuration files in order to complete
81 a build.
82 These files are <filename>*.conf</filename> files.
83 The minimally necessary ones reside as example files in the
84 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
85 For simplicity, this section refers to the Source Directory as
86 the "Poky Directory."
87 </para>
88
89 <para>
90 When you clone the <filename>poky</filename> Git repository or you
91 download and unpack a Yocto Project release, you can set up the
92 Source Directory to be named anything you want.
93 For this discussion, the cloned repository uses the default
94 name <filename>poky</filename>.
95 <note>
96 The Poky repository is primarily an aggregation of existing
97 repositories.
98 It is not a canonical upstream source.
99 </note>
100 </para>
101
102 <para>
103 The <filename>meta-yocto</filename> layer inside Poky contains
104 a <filename>conf</filename> directory that has example
105 configuration files.
106 These example files are used as a basis for creating actual
107 configuration files when you source the build environment
108 script
109 (i.e.
110 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
111 or
112 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
113 </para>
114
115 <para>
116 Sourcing the build environment script creates a
117 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
118 if one does not already exist.
119 BitBake uses the Build Directory for all its work during builds.
120 The Build Directory has a <filename>conf</filename> directory that
121 contains default versions of your <filename>local.conf</filename>
122 and <filename>bblayers.conf</filename> configuration files.
123 These default configuration files are created only if versions
124 do not already exist in the Build Directory at the time you
125 source the build environment setup script.
126 </para>
127
128 <para>
129 Because the Poky repository is fundamentally an aggregation of
130 existing repositories, some users might be familiar with running
131 the <filename>&OE_INIT_FILE;</filename> or
132 <filename>oe-init-build-env-memres</filename> script in the context
133 of separate OpenEmbedded-Core and BitBake repositories rather than a
134 single Poky repository.
135 This discussion assumes the script is executed from within a cloned
136 or unpacked version of Poky.
137 </para>
138
139 <para>
140 Depending on where the script is sourced, different sub-scripts
141 are called to set up the Build Directory (Yocto or OpenEmbedded).
142 Specifically, the script
143 <filename>scripts/oe-setup-builddir</filename> inside the
144 poky directory sets up the Build Directory and seeds the directory
145 (if necessary) with configuration files appropriate for the
146 Yocto Project development environment.
147 <note>
148 The <filename>scripts/oe-setup-builddir</filename> script
149 uses the <filename>$TEMPLATECONF</filename> variable to
150 determine which sample configuration files to locate.
151 </note>
152 </para>
153
154 <para>
155 The <filename>local.conf</filename> file provides many
156 basic variables that define a build environment.
157 Here is a list of a few.
158 To see the default configurations in a <filename>local.conf</filename>
159 file created by the build environment script, see the
160 <filename>local.conf.sample</filename> in the
161 <filename>meta-yocto</filename> layer:
162 <itemizedlist>
163 <listitem><para><emphasis>Parallelism Options:</emphasis>
164 Controlled by the
165 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
166 and
167 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
168 variables.</para></listitem>
169 <listitem><para><emphasis>Target Machine Selection:</emphasis>
170 Controlled by the
171 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
172 variable.</para></listitem>
173 <listitem><para><emphasis>Download Directory:</emphasis>
174 Controlled by the
175 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
176 variable.</para></listitem>
177 <listitem><para><emphasis>Shared State Directory:</emphasis>
178 Controlled by the
179 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
180 variable.</para></listitem>
181 <listitem><para><emphasis>Build Output:</emphasis>
182 Controlled by the
183 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
184 variable.</para></listitem>
185 </itemizedlist>
186 <note>
187 Configurations set in the <filename>conf/local.conf</filename>
188 file can also be set in the
189 <filename>conf/site.conf</filename> and
190 <filename>conf/auto.conf</filename> configuration files.
191 </note>
192 </para>
193
194 <para>
195 The <filename>bblayers.conf</filename> file tells BitBake what
196 layers you want considered during the build.
197 By default, the layers listed in this file include layers
198 minimally needed by the build system.
199 However, you must manually add any custom layers you have created.
200 You can find more information on working with the
201 <filename>bblayers.conf</filename> file in the
202 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
203 section in the Yocto Project Development Manual.
204 </para>
205
206 <para>
207 The files <filename>site.conf</filename> and
208 <filename>auto.conf</filename> are not created by the environment
209 initialization script.
210 If you want these configuration files, you must create them
211 yourself:
212 <itemizedlist>
213 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
214 You can use the <filename>conf/site.conf</filename>
215 configuration file to configure multiple build directories.
216 For example, suppose you had several build environments and
217 they shared some common features.
218 You can set these default build properties here.
219 A good example is perhaps the level of parallelism you want
220 to use through the
221 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
222 and
223 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
224 variables.</para>
225 <para>One useful scenario for using the
226 <filename>conf/site.conf</filename> file is to extend your
227 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
228 variable to include the path to a
229 <filename>conf/site.conf</filename>.
230 Then, when BitBake looks for Metadata using
231 <filename>BBPATH</filename>, it finds the
232 <filename>conf/site.conf</filename> file and applies your
233 common configurations found in the file.
234 To override configurations in a particular build directory,
235 alter the similar configurations within that build
236 directory's <filename>conf/local.conf</filename> file.
237 </para></listitem>
238 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
239 This file is not hand-created.
240 Rather, the file is usually created and written to by
241 an autobuilder.
242 The settings put into the file are typically the same as
243 you would find in the <filename>conf/local.conf</filename>
244 or the <filename>conf/site.conf</filename> files.
245 </para></listitem>
246 </itemizedlist>
247 </para>
248
249 <para>
250 You can edit all configuration files to further define
251 any particular build environment.
252 This process is represented by the "User Configuration Edits"
253 box in the figure.
254 </para>
255
256 <para>
257 When you launch your build with the
258 <filename>bitbake &lt;target&gt;</filename> command, BitBake
259 sorts out the configurations to ultimately define your build
260 environment.
261 </para>
262 </section>
263
264 <section id="metadata-machine-configuration-and-policy-configuration">
265 <title>Metadata, Machine Configuration, and Policy Configuration</title>
266
267 <para>
268 The previous section described the user configurations that
269 define BitBake's global behavior.
270 This section takes a closer look at the layers the build system
271 uses to further control the build.
272 These layers provide Metadata for the software, machine, and
273 policy.
274 </para>
275
276 <para>
277 In general, three types of layer input exist:
278 <itemizedlist>
279 <listitem><para><emphasis>Policy Configuration:</emphasis>
280 Distribution Layers provide top-level or general
281 policies for the image or SDK being built.
282 For example, this layer would dictate whether BitBake
283 produces RPM or IPK packages.</para></listitem>
284 <listitem><para><emphasis>Machine Configuration:</emphasis>
285 Board Support Package (BSP) layers provide machine
286 configurations.
287 This type of information is specific to a particular
288 target architecture.</para></listitem>
289 <listitem><para><emphasis>Metadata:</emphasis>
290 Software layers contain user-supplied recipe files,
291 patches, and append files.
292 </para></listitem>
293 </itemizedlist>
294 </para>
295
296 <para>
297 The following figure shows an expanded representation of the
298 Metadata, Machine Configuration, and Policy Configuration input
299 (layers) boxes of the
300 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
301 </para>
302
303 <para>
304 <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
305 </para>
306
307 <para>
308 In general, all layers have a similar structure.
309 They all contain a licensing file
310 (e.g. <filename>COPYING</filename>) if the layer is to be
311 distributed, a <filename>README</filename> file as good practice
312 and especially if the layer is to be distributed, a
313 configuration directory, and recipe directories.
314 </para>
315
316 <para>
317 The Yocto Project has many layers that can be used.
318 You can see a web-interface listing of them on the
319 <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
320 page.
321 The layers are shown at the bottom categorized under
322 "Yocto Metadata Layers."
323 These layers are fundamentally a subset of the
324 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
325 which lists all layers provided by the OpenEmbedded community.
326 <note>
327 Layers exist in the Yocto Project Source Repositories that
328 cannot be found in the OpenEmbedded Metadata Index.
329 These layers are either deprecated or experimental in nature.
330 </note>
331 </para>
332
333 <para>
334 BitBake uses the <filename>conf/bblayers.conf</filename> file,
335 which is part of the user configuration, to find what layers it
336 should be using as part of the build.
337 </para>
338
339 <para>
340 For more information on layers, see the
341 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
342 section in the Yocto Project Development Manual.
343 </para>
344
345 <section id="distro-layer">
346 <title>Distro Layer</title>
347
348 <para>
349 The distribution layer provides policy configurations for your
350 distribution.
351 Best practices dictate that you isolate these types of
352 configurations into their own layer.
353 Settings you provide in
354 <filename>conf/distro/&lt;distro&gt;.conf</filename> override
355 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>) hold
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
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>recipes-*</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 come 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</filename></link>
549 class to include that 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</filename> class, 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 types are 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</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
678 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
679 to produce images.
680 You can see from the
681 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
682 the BitBake area consists of several functional areas.
683 This section takes a closer look at each of those areas.
684 </para>
685
686 <para>
687 Separate documentation exists for the BitBake tool.
688 See the
689 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>
690 for reference material on BitBake.
691 </para>
692
693 <section id='source-fetching-dev-environment'>
694 <title>Source Fetching</title>
695
696 <para>
697 The first stages of building a recipe are to fetch and unpack
698 the source code:
699 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
700 </para>
701
702 <para>
703 The <filename>do_fetch</filename> and
704 <filename>do_unpack</filename> tasks fetch the source files
705 and unpack them into the work directory.
706 By default, everything is accomplished in the
707 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
708 which has a defined structure.
709 For additional general information on the Build Directory,
710 see the
711 "<link linkend='structure-core-build'><filename>build/</filename></link>"
712 section.
713 </para>
714
715 <para>
716 Unpacked source files are pointed to by the
717 <link linkend='var-S'><filename>S</filename></link> variable.
718 Each recipe has an area in the Build Directory where the
719 unpacked source code resides.
720 The name of that directory for any given recipe is defined from
721 several different variables.
722 You can see the variables that define these directories
723 by looking at the figure:
724 <itemizedlist>
725 <listitem><para><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> -
726 The base directory where the OpenEmbedded build system
727 performs all its work during the build.
728 </para></listitem>
729 <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link> -
730 The architecture of the built package or packages.
731 </para></listitem>
732 <listitem><para><link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link> -
733 The operating system of the target device.
734 </para></listitem>
735 <listitem><para><link linkend='var-PN'><filename>PN</filename></link> -
736 The name of the built package.
737 </para></listitem>
738 <listitem><para><link linkend='var-PV'><filename>PV</filename></link> -
739 The version of the recipe used to build the package.
740 </para></listitem>
741 <listitem><para><link linkend='var-PR'><filename>PR</filename></link> -
742 The revision of the recipe used to build the package.
743 </para></listitem>
744 <listitem><para><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> -
745 The location within <filename>TMPDIR</filename> where
746 a specific package is built.
747 </para></listitem>
748 <listitem><para><link linkend='var-S'><filename>S</filename></link> -
749 Contains the unpacked source files for a given recipe.
750 </para></listitem>
751 </itemizedlist>
752 </para>
753 </section>
754
755 <section id='patching-dev-environment'>
756 <title>Patching</title>
757
758 <para>
759 Once source code is fetched and unpacked, BitBake locates
760 patch files and applies them to the source files:
761 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
762 </para>
763
764 <para>
765 The <filename>do_patch</filename> task processes recipes by
766 using the
767 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
768 variable to locate applicable patch files, which by default
769 are <filename>*.patch</filename> or
770 <filename>*.diff</filename> files, or any file if
771 "apply=yes" is specified for the file in
772 <filename>SRC_URI</filename>.
773 </para>
774
775 <para>
776 BitBake finds and applies multiple patches for a single recipe
777 in the order in which it finds the patches.
778 Patches are applied to the recipe's source files located in the
779 <link linkend='var-S'><filename>S</filename></link> directory.
780 </para>
781
782 <para>
783 For more information on how the source directories are
784 created, see the
785 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
786 section.
787 </para>
788 </section>
789
790 <section id='configuration-and-compilation-dev-environment'>
791 <title>Configuration and Compilation</title>
792
793 <para>
794 After source code is patched, BitBake executes tasks that
795 configure and compile the source code:
796 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
797 </para>
798
799 <para>
800 This step in the build process consists of three tasks:
801 <itemizedlist>
802 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
803 This task configures the source by enabling and
804 disabling any build-time and configuration options for
805 the software being built.
806 Configurations can come from the recipe itself as well
807 as from an inherited class.
808 Additionally, the software itself might configure itself
809 depending on the target for which it is being built.
810 </para>
811
812 <para>The configurations handled by the
813 <filename>do_configure</filename> task are specific
814 to source code configuration for the source code
815 being built by the recipe.</para>
816
817 <para>If you are using the
818 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
819 class,
820 you can add additional configuration options by using
821 the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
822 variable.
823 For information on how this variable works within
824 that class, see the
825 <filename>meta/classes/autotools.bbclass</filename> file.
826 </para></listitem>
827 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
828 Once a configuration task has been satisfied, BitBake
829 compiles the source using the
830 <filename>do_compile</filename> task.
831 Compilation occurs in the directory pointed to by the
832 <link linkend='var-B'><filename>B</filename></link>
833 variable.
834 Realize that the <filename>B</filename> directory is, by
835 default, the same as the
836 <link linkend='var-S'><filename>S</filename></link>
837 directory.</para></listitem>
838 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
839 Once compilation is done, BitBake executes the
840 <filename>do_install</filename> task.
841 This task copies files from the <filename>B</filename>
842 directory and places them in a holding area pointed to
843 by the
844 <link linkend='var-D'><filename>D</filename></link>
845 variable.</para></listitem>
846 </itemizedlist>
847 </para>
848 </section>
849
850 <section id='package-splitting-dev-environment'>
851 <title>Package Splitting</title>
852
853 <para>
854 After source code is configured and compiled, the
855 OpenEmbedded build system analyzes
856 the results and splits the output into packages:
857 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
858 </para>
859
860 <para>
861 The <filename>do_package</filename> and
862 <filename>do_packagedata</filename> tasks combine to analyze
863 the files found in the
864 <link linkend='var-D'><filename>D</filename></link> directory
865 and split them into subsets based on available packages and
866 files.
867 The analyzing process involves the following as well as other
868 items: splitting out debugging symbols,
869 looking at shared library dependencies between packages,
870 and looking at package relationships.
871 The <filename>do_packagedata</filename> task creates package
872 metadata based on the analysis such that the
873 OpenEmbedded build system can generate the final packages.
874 Working, staged, and intermediate results of the analysis
875 and package splitting process use these areas:
876 <itemizedlist>
877 <listitem><para><link linkend='var-PKGD'><filename>PKGD</filename></link> -
878 The destination directory for packages before they are
879 split.
880 </para></listitem>
881 <listitem><para><link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> -
882 A shared, global-state directory that holds data
883 generated during the packaging process.
884 </para></listitem>
885 <listitem><para><link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link> -
886 A temporary work area used by the
887 <filename>do_package</filename> task.
888 </para></listitem>
889 <listitem><para><link linkend='var-PKGDEST'><filename>PKGDEST</filename></link> -
890 The parent directory for packages after they have
891 been split.
892 </para></listitem>
893 </itemizedlist>
894 The <link linkend='var-FILES'><filename>FILES</filename></link>
895 variable defines the files that go into each package in
896 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
897 If you want details on how this is accomplished, you can
898 look at the
899 <link linkend='ref-classes-package'><filename>package</filename></link>
900 class.
901 </para>
902
903 <para>
904 Depending on the type of packages being created (RPM, DEB, or
905 IPK), the <filename>do_package_write_*</filename> task
906 creates the actual packages and places them in the
907 Package Feed area, which is
908 <filename>${TMPDIR}/deploy</filename>.
909 You can see the
910 "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
911 section for more detail on that part of the build process.
912 <note>
913 Support for creating feeds directly from the
914 <filename>deploy/*</filename> directories does not exist.
915 Creating such feeds usually requires some kind of feed
916 maintenance mechanism that would upload the new packages
917 into an official package feed (e.g. the
918 Ångström distribution).
919 This functionality is highly distribution-specific
920 and thus is not provided out of the box.
921 </note>
922 </para>
923 </section>
924
925 <section id='image-generation-dev-environment'>
926 <title>Image Generation</title>
927
928 <para>
929 Once packages are split and stored in the Package Feeds area,
930 the OpenEmbedded build system uses BitBake to generate the
931 root filesystem image:
932 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
933 </para>
934
935 <para>
936 The image generation process consists of several stages and
937 depends on many variables.
938 The <filename>do_rootfs</filename> task uses these key variables
939 to help create the list of packages to actually install:
940 <itemizedlist>
941 <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
942 Lists out the base set of packages to install from
943 the Package Feeds area.</para></listitem>
944 <listitem><para><link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>:
945 Specifies packages that should not be installed.
946 </para></listitem>
947 <listitem><para><link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
948 Specifies features to include in the image.
949 Most of these features map to additional packages for
950 installation.</para></listitem>
951 <listitem><para><link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>:
952 Specifies the package backend to use and consequently
953 helps determine where to locate packages within the
954 Package Feeds area.</para></listitem>
955 <listitem><para><link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>:
956 Determines the language(s) for which additional
957 language support packages are installed.
958 </para></listitem>
959 </itemizedlist>
960 </para>
961
962 <para>
963 Package installation is under control of the package manager
964 (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
965 not package management is enabled for the target.
966 At the end of the process, if package management is not
967 enabled for the target, the package manager's data files
968 are deleted from the root filesystem.
969 </para>
970
971 <para>
972 During image generation, the build system attempts to run
973 all post-installation scripts.
974 Any that fail to run on the build host are run on the
975 target when the target system is first booted.
976 If you are using a
977 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
978 all the post installation scripts must succeed during the
979 package installation phase since the root filesystem is
980 read-only.
981 </para>
982
983 <para>
984 During Optimization, optimizing processes are run across
985 the image.
986 These processes include <filename>mklibs</filename> and
987 <filename>prelink</filename>.
988 The <filename>mklibs</filename> process optimizes the size
989 of the libraries.
990 A <filename>prelink</filename> process optimizes the dynamic
991 linking of shared libraries to reduce start up time of
992 executables.
993 </para>
994
995 <para>
996 Along with writing out the root filesystem image, the
997 <filename>do_rootfs</filename> task creates a manifest file
998 (<filename>.manifest</filename>) in the same directory as
999 the root filesystem image that lists out, line-by-line, the
1000 installed packages.
1001 This manifest file is useful for the
1002 <link linkend='ref-classes-testimage'><filename>testimage</filename></link>
1003 class, for example, to determine whether or not to run
1004 specific tests.
1005 See the
1006 <link linkend='var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></link>
1007 variable for additional information.
1008 </para>
1009
1010 <para>
1011 Part of the image generation process includes compressing the
1012 root filesystem image.
1013 Compression is accomplished through several optimization
1014 routines designed to reduce the overall size of the image.
1015 </para>
1016
1017 <para>
1018 After the root filesystem has been constructed, the image
1019 generation process turns everything into an image file or
1020 a set of image files.
1021 The formats used for the root filesystem depend on the
1022 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1023 variable.
1024 </para>
1025
1026 <note>
1027 The entire image generation process is run under Pseudo.
1028 Running under Pseudo ensures that the files in the root
1029 filesystem have correct ownership.
1030 </note>
1031 </section>
1032
1033 <section id='sdk-generation-dev-environment'>
1034 <title>SDK Generation</title>
1035
1036 <para>
1037 The OpenEmbedded build system uses BitBake to generate the
1038 Software Development Kit (SDK) installer script:
1039 <imagedata fileref="figures/sdk-generation.png" align="center" width="6in" depth="7in" />
1040 </para>
1041
1042 <note>
1043 For more information on the cross-development toolchain
1044 generation, see the
1045 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1046 section.
1047 For information on advantages gained when building a
1048 cross-development toolchain using the
1049 <filename>do_populate_sdk</filename> task, see the
1050 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
1051 section in the Yocto Project Application Developer's Guide.
1052 </note>
1053
1054 <para>
1055 Like image generation, the SDK script process consists of
1056 several stages and depends on many variables.
1057 The <filename>do_populate_sdk</filename> task uses these
1058 key variables to help create the list of packages to actually
1059 install.
1060 For information on the variables listed in the figure, see the
1061 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1062 section.
1063 </para>
1064
1065 <para>
1066 The <filename>do_populate_sdk</filename> task handles two
1067 parts: a target part and a host part.
1068 The target part is the part built for the target hardware and
1069 includes libraries and headers.
1070 The host part is the part of the SDK that runs on the
1071 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
1072 </para>
1073
1074 <para>
1075 Once both parts are constructed, the
1076 <filename>do_populate_sdk</filename> task performs some cleanup
1077 on both parts.
1078 After the cleanup, the task creates a cross-development
1079 environment setup script and any configuration files that
1080 might be needed.
1081 </para>
1082
1083 <para>
1084 The final output of the task is the Cross-development
1085 toolchain installation script (<filename>.sh</filename> file),
1086 which includes the environment setup script.
1087 </para>
1088 </section>
1089 </section>
1090
1091 <section id='images-dev-environment'>
1092 <title>Images</title>
1093
1094 <para>
1095 The images produced by the OpenEmbedded build system
1096 are compressed forms of the
1097 root filesystem that are ready to boot on a target device.
1098 You can see from the
1099 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1100 that BitBake output, in part, consists of images.
1101 This section is going to look more closely at this output:
1102 <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
1103 </para>
1104
1105 <para>
1106 For a list of example images that the Yocto Project provides,
1107 see the
1108 "<link linkend='ref-images'>Images</link>" chapter.
1109 </para>
1110
1111 <para>
1112 Images are written out to the
1113 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1114 inside the <filename>tmp/deploy/images/&lt;machine&gt;/</filename>
1115 folder as shown in the figure.
1116 This folder contains any files expected to be loaded on the
1117 target device.
1118 The
1119 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
1120 variable points to the <filename>deploy</filename> directory,
1121 while the
1122 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
1123 variable points to the appropriate directory containing images for
1124 the current configuration.
1125 <itemizedlist>
1126 <listitem><para><filename>&lt;kernel-image&gt;</filename>:
1127 A kernel binary file.
1128 The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
1129 variable setting determines the naming scheme for the
1130 kernel image file.
1131 Depending on that variable, the file could begin with
1132 a variety of naming strings.
1133 The <filename>deploy/images/&lt;machine&gt;</filename>
1134 directory can contain multiple image files for the
1135 machine.</para></listitem>
1136 <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
1137 Root filesystems for the target device (e.g.
1138 <filename>*.ext3</filename> or <filename>*.bz2</filename>
1139 files).
1140 The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1141 variable setting determines the root filesystem image
1142 type.
1143 The <filename>deploy/images/&lt;machine&gt;</filename>
1144 directory can contain multiple root filesystems for the
1145 machine.</para></listitem>
1146 <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
1147 Tarballs that contain all the modules built for the kernel.
1148 Kernel module tarballs exist for legacy purposes and
1149 can be suppressed by setting the
1150 <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
1151 variable to "0".
1152 The <filename>deploy/images/&lt;machine&gt;</filename>
1153 directory can contain multiple kernel module tarballs
1154 for the machine.</para></listitem>
1155 <listitem><para><filename>&lt;bootloaders&gt;</filename>:
1156 Bootloaders supporting the image, if applicable to the
1157 target machine.
1158 The <filename>deploy/images/&lt;machine&gt;</filename>
1159 directory can contain multiple bootloaders for the
1160 machine.</para></listitem>
1161 <listitem><para><filename>&lt;symlinks&gt;</filename>:
1162 The <filename>deploy/images/&lt;machine&gt;</filename>
1163 folder contains
1164 a symbolic link that points to the most recently built file
1165 for each machine.
1166 These links might be useful for external scripts that
1167 need to obtain the latest version of each file.
1168 </para></listitem>
1169 </itemizedlist>
1170 </para>
1171 </section>
1172
1173 <section id='sdk-dev-environment'>
1174 <title>Application Development SDK</title>
1175
1176 <para>
1177 In the
1178 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
1179 the output labeled "Application Development SDK" represents an
1180 SDK.
1181 This section is going to take a closer look at this output:
1182 <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
1183 </para>
1184
1185 <para>
1186 The specific form of this output is a self-extracting
1187 SDK installer (<filename>*.sh</filename>) that, when run,
1188 installs the SDK, which consists of a cross-development
1189 toolchain, a set of libraries and headers, and an SDK
1190 environment setup script.
1191 Running this installer essentially sets up your
1192 cross-development environment.
1193 You can think of the cross-toolchain as the "host"
1194 part because it runs on the SDK machine.
1195 You can think of the libraries and headers as the "target"
1196 part because they are built for the target hardware.
1197 The setup script is added so that you can initialize the
1198 environment before using the tools.
1199 </para>
1200
1201 <note>
1202 <para>
1203 The Yocto Project supports several methods by which you can
1204 set up this cross-development environment.
1205 These methods include downloading pre-built SDK installers,
1206 building and installing your own SDK installer, or running
1207 an Application Development Toolkit (ADT) installer to
1208 install not just cross-development toolchains
1209 but also additional tools to help in this type of
1210 development.
1211 </para>
1212
1213 <para>
1214 For background information on cross-development toolchains
1215 in the Yocto Project development environment, see the
1216 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1217 section.
1218 For information on setting up a cross-development
1219 environment, see the
1220 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
1221 section in the Yocto Project Application Developer's Guide.
1222 </para>
1223 </note>
1224
1225 <para>
1226 Once built, the SDK installers are written out to the
1227 <filename>deploy/sdk</filename> folder inside the
1228 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1229 as shown in the figure at the beginning of this section.
1230 Several variables exist that help configure these files:
1231 <itemizedlist>
1232 <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
1233 Points to the <filename>deploy</filename>
1234 directory.</para></listitem>
1235 <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
1236 Specifies the architecture of the machine
1237 on which the cross-development tools are run to
1238 create packages for the target hardware.
1239 </para></listitem>
1240 <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
1241 Lists the features to include in the "target" part
1242 of the SDK.
1243 </para></listitem>
1244 <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
1245 Lists packages that make up the host
1246 part of the SDK (i.e. the part that runs on
1247 the <filename>SDKMACHINE</filename>).
1248 When you use
1249 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
1250 to create the SDK, a set of default packages
1251 apply.
1252 This variable allows you to add more packages.
1253 </para></listitem>
1254 <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
1255 Lists packages that make up the target part
1256 of the SDK (i.e. the part built for the
1257 target hardware).
1258 </para></listitem>
1259 <listitem><para><link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>:
1260 Defines the default SDK installation path offered by the
1261 installation script.
1262 </para></listitem>
1263 </itemizedlist>
1264 </para>
1265 </section>
1266
1267</chapter>
1268<!--
1269vim: expandtab tw=80 ts=4
1270-->
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 0000000..5dfb0b3
--- /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 0000000..fc7169b
--- /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 0000000..0812743
--- /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 0000000..b58d4d7
--- /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 0000000..5d05a43
--- /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 0000000..035011f
--- /dev/null
+++ b/documentation/ref-manual/faq.xml
@@ -0,0 +1,685 @@
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 id='faq-not-meeting-requirements'>
34 My development system does not meet the
35 required Git, tar, and Python versions.
36 In particular, I do not have Python 2.7.3 or greater, or
37 I do have Python 3.x, which is specifically not supported by
38 the Yocto Project.
39 Can I still use the Yocto Project?
40 </para>
41 </question>
42 <answer>
43 <para>
44 You can get the required tools on your host development
45 system a couple different ways (i.e. building a tarball or
46 downloading a tarball).
47 See the
48 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
49 section for steps on how to update your build tools.
50 </para>
51 </answer>
52 </qandaentry>
53
54 <qandaentry>
55 <question>
56 <para>
57 How can you claim Poky / OpenEmbedded-Core is stable?
58 </para>
59 </question>
60 <answer>
61 <para>
62 There are three areas that help with stability;
63 <itemizedlist>
64 <listitem><para>The Yocto Project team keeps
65 <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small
66 and focused, containing around 830 recipes as opposed to the thousands
67 available in other OpenEmbedded community layers.
68 Keeping it small makes it easy to test and maintain.</para></listitem>
69 <listitem><para>The Yocto Project team runs manual and automated tests
70 using a small, fixed set of reference hardware as well as emulated
71 targets.</para></listitem>
72 <listitem><para>The Yocto Project uses an autobuilder,
73 which provides continuous build and integration tests.</para></listitem>
74 </itemizedlist>
75 </para>
76 </answer>
77 </qandaentry>
78
79 <qandaentry>
80 <question>
81 <para>
82 How do I get support for my board added to the Yocto Project?
83 </para>
84 </question>
85 <answer>
86 <para>
87 Support for an additional board is added by creating a
88 Board Support Package (BSP) layer for it.
89 For more information on how to create a BSP layer, see the
90 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
91 section in the Yocto Project Development Manual and the
92 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
93 </para>
94 <para>
95 Usually, if the board is not completely exotic, adding support in
96 the Yocto Project is fairly straightforward.
97 </para>
98 </answer>
99 </qandaentry>
100
101 <qandaentry>
102 <question>
103 <para>
104 Are there any products built using the OpenEmbedded build system?
105 </para>
106 </question>
107 <answer>
108 <para>
109 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
110 is built using the OpenEmbedded build system.
111 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
112 website for more information.
113 There are a number of pre-production devices using the OpenEmbedded build system
114 and the Yocto Project team
115 announces them as soon as they are released.
116 </para>
117 </answer>
118 </qandaentry>
119
120 <qandaentry>
121 <question>
122 <para>
123 What does the OpenEmbedded build system produce as output?
124 </para>
125 </question>
126 <answer>
127 <para>
128 Because you can use the same set of recipes to create output of
129 various formats, the output of an OpenEmbedded build depends on
130 how you start it.
131 Usually, the output is a flashable image ready for the target
132 device.
133 </para>
134 </answer>
135 </qandaentry>
136
137 <qandaentry>
138 <question>
139 <para>
140 How do I add my package to the Yocto Project?
141 </para>
142 </question>
143 <answer>
144 <para>
145 To add a package, you need to create a BitBake recipe.
146 For information on how to create a BitBake recipe, see the
147 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe'>Writing a New Recipe</ulink>"
148 in the Yocto Project Development Manual.
149 </para>
150 </answer>
151 </qandaentry>
152
153 <qandaentry>
154 <question>
155 <para>
156 Do I have to reflash my entire board with a new Yocto Project image when recompiling
157 a package?
158 </para>
159 </question>
160 <answer>
161 <para>
162 The OpenEmbedded build system can build packages in various
163 formats such as IPK for OPKG, Debian package
164 (<filename>.deb</filename>), or RPM.
165 You can then upgrade the packages using the package tools on
166 the device, much like on a desktop distribution such as
167 Ubuntu or Fedora.
168 However, package management on the target is entirely optional.
169 </para>
170 </answer>
171 </qandaentry>
172
173 <qandaentry>
174 <question>
175 <para>
176 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
177 </para>
178 </question>
179 <answer>
180 <para>
181 GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
182 platform targeted at mobile and embedded devices.
183 The main difference between GNOME Mobile and standard GNOME is that
184 desktop-orientated libraries have been removed, along with deprecated libraries,
185 creating a much smaller footprint.
186 </para>
187 </answer>
188 </qandaentry>
189
190 <qandaentry>
191 <question>
192 <para>
193 I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
194 What is wrong?
195 </para>
196 </question>
197 <answer>
198 <para>
199 You are probably running the build on an NTFS filesystem.
200 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
201 </para>
202 </answer>
203 </qandaentry>
204
205<!-- <qandaentry>
206 <question>
207 <para>
208 How do I make the Yocto Project work in RHEL/CentOS?
209 </para>
210 </question>
211 <answer>
212 <para>
213 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
214 install some required packages.
215 The standard CentOS packages needed are:
216 <itemizedlist>
217 <listitem><para>"Development tools" (selected during installation)</para></listitem>
218 <listitem><para><filename>texi2html</filename></para></listitem>
219 <listitem><para><filename>compat-gcc-34</filename></para></listitem>
220 </itemizedlist>
221 On top of these, you need the following external packages:
222 <itemizedlist>
223 <listitem><para><filename>python-sqlite2</filename> from
224 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
225 </para></listitem>
226 <listitem><para><filename>help2man</filename> from
227 <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>
228 </itemizedlist>
229 </para>
230
231 <para>
232 Once these packages are installed, the OpenEmbedded build system will be able
233 to build standard images.
234 However, there might be a problem with the QEMU emulator segfaulting.
235 You can either disable the generation of binary locales by setting
236 <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
237 </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
238 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
239 </para>
240
241 <note>
242 <para>For information on distributions that the Yocto Project
243 uses during validation, see the
244 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>
245 Wiki page.</para>
246 <para>For notes about using the Yocto Project on a RHEL 4-based
247 host, see the
248 <ulink url='&YOCTO_WIKI_URL;/wiki/BuildingOnRHEL4'>Building on RHEL4</ulink>
249 Wiki page.</para>
250 </note>
251 </answer>
252 </qandaentry> -->
253
254 <qandaentry>
255 <question>
256 <para>
257 I see lots of 404 responses for files on
258 <filename>&YOCTO_HOME_URL;/sources/*</filename>. Is something wrong?
259 </para>
260 </question>
261 <answer>
262 <para>
263 Nothing is wrong.
264 The OpenEmbedded build system checks any configured source mirrors before downloading
265 from the upstream sources.
266 The build system does this searching for both source archives and
267 pre-checked out versions of SCM-managed software.
268 These checks help in large installations because it can reduce load on the SCM servers
269 themselves.
270 The address above is one of the default mirrors configured into the
271 build system.
272 Consequently, if an upstream source disappears, the team
273 can place sources there so builds continue to work.
274 </para>
275 </answer>
276 </qandaentry>
277
278 <qandaentry>
279 <question>
280 <para>
281 I have machine-specific data in a package for one machine only but the package is
282 being marked as machine-specific in all cases, how do I prevent this?
283 </para>
284 </question>
285 <answer>
286 <para>
287 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
288 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
289 manually marked as
290 machine-specific for the case that needs it.
291 The code that handles
292 <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in
293 the <filename>meta/classes/base.bbclass</filename> file.
294 </para>
295 </answer>
296 </qandaentry>
297
298 <qandaentry>
299 <question>
300 <para>
301 I'm behind a firewall and need to use a proxy server. How do I do that?
302 </para>
303 </question>
304 <answer>
305 <para>
306 Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename>
307 and you therefore need to specify the proxy settings in a
308 <filename>.wgetrc</filename> file in your home directory.
309 Here are some example settings:
310 <literallayout class='monospaced'>
311 http_proxy = http://proxy.yoyodyne.com:18023/
312 ftp_proxy = http://proxy.yoyodyne.com:18023/
313 </literallayout>
314 The Yocto Project also includes a
315 <filename>site.conf.sample</filename> file that shows how to
316 configure CVS and Git proxy servers if needed.
317 </para>
318 </answer>
319 </qandaentry>
320
321 <qandaentry>
322 <question>
323 <para>
324 What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>?
325 </para>
326 </question>
327 <answer>
328 <para>
329 The <filename>*-native</filename> targets are designed to run on the system
330 being used for the build.
331 These are usually tools that are needed to assist the build in some way such as
332 <filename>quilt-native</filename>, which is used to apply patches.
333 The non-native version is the one that runs on the target device.
334 </para>
335 </answer>
336 </qandaentry>
337
338 <qandaentry>
339 <question>
340 <para>
341 I'm seeing random build failures. Help?!
342 </para>
343 </question>
344 <answer>
345 <para>
346 If the same build is failing in totally different and random
347 ways, the most likely explanation is:
348 <itemizedlist>
349 <listitem><para>The hardware you are running the build on
350 has some problem.</para></listitem>
351 <listitem><para>You are running the build under
352 virtualization, in which case the virtualization
353 probably has bugs.</para></listitem>
354 </itemizedlist>
355 The OpenEmbedded build system processes a massive amount of
356 data that causes lots of network, disk and CPU activity and
357 is sensitive to even single-bit failures in any of these areas.
358 True random failures have always been traced back to hardware
359 or virtualization issues.
360 </para>
361 </answer>
362 </qandaentry>
363
364 <qandaentry>
365 <question>
366 <para>
367 What do we need to ship for license compliance?
368 </para>
369 </question>
370 <answer>
371 <para>
372 This is a difficult question and you need to consult your lawyer
373 for the answer for your specific case.
374 It is worth bearing in mind that for GPL compliance, there needs
375 to be enough information shipped to allow someone else to
376 rebuild and produce the same end result you are shipping.
377 This means sharing the source code, any patches applied to it,
378 and also any configuration information about how that package
379 was configured and built.
380 </para>
381
382 <para>
383 You can find more information on licensing in the
384 "<ulink url='&YOCTO_DOCS_DEV_URL;#licensing'>Licensing</ulink>"
385 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>"
386 sections, both of which are in the Yocto Project Development
387 Manual.
388 </para>
389 </answer>
390 </qandaentry>
391
392 <qandaentry>
393 <question>
394 <para>
395 How do I disable the cursor on my touchscreen device?
396 </para>
397 </question>
398 <answer>
399 <para>
400 You need to create a form factor file as described in the
401 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
402 section in the Yocto Project Board Support Packages (BSP)
403 Developer's Guide.
404 Set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to
405 one as follows:
406 <literallayout class='monospaced'>
407 HAVE_TOUCHSCREEN=1
408 </literallayout>
409 </para>
410 </answer>
411 </qandaentry>
412
413 <qandaentry>
414 <question>
415 <para>
416 How do I make sure connected network interfaces are brought up by default?
417 </para>
418 </question>
419 <answer>
420 <para>
421 The default interfaces file provided by the netbase recipe does not
422 automatically bring up network interfaces.
423 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
424 file.
425 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
426 section in the Yocto Project Board Support Packages (BSP)
427 Developer's Guide for information on creating these types of
428 miscellaneous recipe files.
429 </para>
430 <para>
431 For example, add the following files to your layer:
432 <literallayout class='monospaced'>
433 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
434 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
435 </literallayout>
436 </para>
437 </answer>
438 </qandaentry>
439
440 <qandaentry>
441 <question>
442 <para>
443 How do I create images with more free space?
444 </para>
445 </question>
446 <answer>
447 <para>
448 By default, the OpenEmbedded build system creates images
449 that are 1.3 times the size of the populated root filesystem.
450 To affect the image size, you need to set various
451 configurations:
452 <itemizedlist>
453 <listitem><para><emphasis>Image Size:</emphasis>
454 The OpenEmbedded build system uses the
455 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
456 variable to define the size of the image in Kbytes.
457 The build system determines the size by taking into
458 account the initial root filesystem size before any
459 modifications such as requested size for the image and
460 any requested additional free disk space to be
461 added to the image.</para></listitem>
462 <listitem><para><emphasis>Overhead:</emphasis>
463 Use the
464 <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
465 variable to define the multiplier that the build system
466 applies to the initial image size, which is 1.3 by
467 default.</para></listitem>
468 <listitem><para><emphasis>Additional Free Space:</emphasis>
469 Use the
470 <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
471 variable to add additional free space to the image.
472 The build system adds this space to the image after
473 it determines its
474 <filename>IMAGE_ROOTFS_SIZE</filename>.
475 </para></listitem>
476 </itemizedlist>
477 </para>
478 </answer>
479 </qandaentry>
480
481 <qandaentry>
482 <question>
483 <para>
484 Why don't you support directories with spaces in the pathnames?
485 </para>
486 </question>
487 <answer>
488 <para>
489 The Yocto Project team has tried to do this before but too
490 many of the tools the OpenEmbedded build system depends on,
491 such as <filename>autoconf</filename>, break when they find
492 spaces in pathnames.
493 Until that situation changes, the team will not support spaces
494 in pathnames.
495 </para>
496 </answer>
497 </qandaentry>
498
499 <qandaentry>
500 <question>
501 <para>
502 How do I use an external toolchain?
503 </para>
504 </question>
505 <answer>
506 <para>
507 The toolchain configuration is very flexible and customizable.
508 It is primarily controlled with the
509 <filename><link linkend='var-TCMODE'>TCMODE</link></filename>
510 variable.
511 This variable controls which <filename>tcmode-*.inc</filename>
512 file to include from the
513 <filename>meta/conf/distro/include</filename> directory within
514 the
515 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
516 </para>
517
518 <para>
519 The default value of <filename>TCMODE</filename> is "default",
520 which tells the OpenEmbedded build system to use its internally
521 built toolchain (i.e. <filename>tcmode-default.inc</filename>).
522 However, other patterns are accepted.
523 In particular, "external-*" refers to external toolchains.
524 One example is the Sourcery G++ Toolchain.
525 The support for this toolchain resides in the separate
526 <filename>meta-sourcery</filename> layer at
527 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
528 </para>
529
530 <para>
531 In addition to the toolchain configuration, you also need a
532 corresponding toolchain recipe file.
533 This recipe file needs to package up any pre-built objects in
534 the toolchain such as <filename>libgcc</filename>,
535 <filename>libstdcc++</filename>, any locales, and
536 <filename>libc</filename>.
537 </para>
538 </answer>
539 </qandaentry>
540
541 <qandaentry>
542 <question>
543 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
544 How does the OpenEmbedded build system obtain source code and
545 will it work behind my firewall or proxy server?
546 </para>
547 </question>
548 <answer>
549 <para>
550 The way the build system obtains source code is highly
551 configurable.
552 You can setup the build system to get source code in most
553 environments if HTTP transport is available.
554 </para>
555 <para>
556 When the build system searches for source code, it first
557 tries the local download directory.
558 If that location fails, Poky tries
559 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
560 the upstream source, and then
561 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
562 in that order.
563 </para>
564 <para>
565 Assuming your distribution is "poky", the OpenEmbedded build
566 system uses the Yocto Project source
567 <filename>PREMIRRORS</filename> by default for SCM-based
568 sources, upstreams for normal tarballs, and then falls back
569 to a number of other mirrors including the Yocto Project
570 source mirror if those fail.
571 </para>
572 <para>
573 As an example, you could add a specific server for the
574 build system to attempt before any others by adding something
575 like the following to the <filename>local.conf</filename>
576 configuration file:
577 <literallayout class='monospaced'>
578 PREMIRRORS_prepend = "\
579 git://.*/.* http://www.yoctoproject.org/sources/ \n \
580 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
581 http://.*/.* http://www.yoctoproject.org/sources/ \n \
582 https://.*/.* http://www.yoctoproject.org/sources/ \n"
583 </literallayout>
584 </para>
585 <para>
586 These changes cause the build system to intercept Git, FTP,
587 HTTP, and HTTPS requests and direct them to the
588 <filename>http://</filename> sources mirror.
589 You can use <filename>file://</filename> URLs to point to
590 local directories or network shares as well.
591 </para>
592 <para>
593 Aside from the previous technique, these options also exist:
594 <literallayout class='monospaced'>
595 BB_NO_NETWORK = "1"
596 </literallayout>
597 This statement tells BitBake to issue an error instead of
598 trying to access the Internet.
599 This technique is useful if you want to ensure code builds
600 only from local sources.
601 </para>
602 <para>
603 Here is another technique:
604 <literallayout class='monospaced'>
605 BB_FETCH_PREMIRRORONLY = "1"
606 </literallayout>
607 This statement limits the build system to pulling source
608 from the <filename>PREMIRRORS</filename> only.
609 Again, this technique is useful for reproducing builds.
610 </para>
611 <para>
612 Here is another technique:
613 <literallayout class='monospaced'>
614 BB_GENERATE_MIRROR_TARBALLS = "1"
615 </literallayout>
616 This statement tells the build system to generate mirror
617 tarballs.
618 This technique is useful if you want to create a mirror server.
619 If not, however, the technique can simply waste time during
620 the build.
621 </para>
622 <para>
623 Finally, consider an example where you are behind an
624 HTTP-only firewall.
625 You could make the following changes to the
626 <filename>local.conf</filename> configuration file as long as
627 the <filename>PREMIRRORS</filename> server is current:
628 <literallayout class='monospaced'>
629 PREMIRRORS_prepend = "\
630 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
631 http://.*/.* http://www.yoctoproject.org/sources/ \n \
632 https://.*/.* http://www.yoctoproject.org/sources/ \n"
633 BB_FETCH_PREMIRRORONLY = "1"
634 </literallayout>
635 These changes would cause the build system to successfully
636 fetch source over HTTP and any network accesses to anything
637 other than the <filename>PREMIRRORS</filename> would fail.
638 </para>
639 <para>
640 The build system also honors the standard shell environment
641 variables <filename>http_proxy</filename>,
642 <filename>ftp_proxy</filename>,
643 <filename>https_proxy</filename>, and
644 <filename>all_proxy</filename> to redirect requests through
645 proxy servers.
646 </para>
647 </answer>
648 </qandaentry>
649
650 <qandaentry>
651 <question>
652 <para>
653 Can I get rid of build output so I can start over?
654 </para>
655 </question>
656 <answer>
657 <para>
658 Yes - you can easily do this.
659 When you use BitBake to build an image, all the build output
660 goes into the directory created when you run the
661 build environment setup script (i.e.
662 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
663 or
664 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
665 By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
666 is named <filename>build</filename> but can be named
667 anything you want.
668 </para>
669
670 <para>
671 Within the Build Directory, is the <filename>tmp</filename>
672 directory.
673 To remove all the build output yet preserve any source code or
674 downloaded files from previous builds, simply remove the
675 <filename>tmp</filename> directory.
676 </para>
677 </answer>
678 </qandaentry>
679
680
681</qandaset>
682</chapter>
683<!--
684vim: expandtab tw=80 ts=4
685-->
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 0000000..04f2794
--- /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 0000000..f6db86c
--- /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 0000000..edf98d9
--- /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 0000000..a07464f
--- /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 0000000..d36670a
--- /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 0000000..ab96258
--- /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 0000000..d99eac1
--- /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 0000000..0a4f2e7
--- /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 0000000..4bc311f
--- /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 0000000..8ecd018
--- /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 0000000..2893d84
--- /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 0000000..c37e274
--- /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 0000000..a539cc5
--- /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 0000000..26aefb5
--- /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 0000000..f751505
--- /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 0000000..f2b3f8e
--- /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 0000000..650c6c8
--- /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 0000000..f48489a
--- /dev/null
+++ b/documentation/ref-manual/introduction.xml
@@ -0,0 +1,556 @@
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 find information on tracing and profiling in the
26 <ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual'>Yocto Project Profiling and Tracing Manual</ulink>.
27 For information on BitBake, which is the task execution tool the
28 OpenEmbedded build system is based on, see the
29 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
30 Finally, you can also find lots of Yocto Project information on the
31 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
32 </para>
33</section>
34
35<section id='intro-manualoverview'>
36 <title>Documentation Overview</title>
37 <para>
38 This reference manual consists of the following:
39 <itemizedlist>
40 <listitem><para><emphasis>
41 <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis>
42 Provides an overview of the components that make up the Yocto Project
43 followed by information about debugging images created in the Yocto Project.
44 </para></listitem>
45 <listitem><para><emphasis>
46 <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>:</emphasis>
47 Provides a more detailed look at the Yocto Project development
48 environment within the context of development.
49 </para></listitem>
50 <listitem><para><emphasis>
51 <link linkend='technical-details'>Technical Details</link>:</emphasis>
52 Describes fundamental Yocto Project components as well as an explanation
53 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
54 </para></listitem>
55 <listitem><para><emphasis>
56 <link linkend='migration'>Migrating to a Newer Yocto Project Release</link>:</emphasis>
57 Describes release-specific information that helps you move from
58 one Yocto Project Release to another.
59 </para></listitem>
60 <listitem><para><emphasis>
61 <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
62 Describes the
63 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> created
64 either by unpacking a released Yocto Project tarball on your host development system,
65 or by cloning the upstream
66 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
67 </para></listitem>
68 <listitem><para><emphasis>
69 <link linkend='ref-classes'>Classes</link>:</emphasis>
70 Describes the classes used in the Yocto Project.</para></listitem>
71 <listitem><para><emphasis>
72 <link linkend='ref-images'>Images</link>:</emphasis>
73 Describes the standard images that the Yocto Project supports.
74 </para></listitem>
75 <listitem><para><emphasis>
76 <link linkend='ref-features'>Features</link>:</emphasis>
77 Describes mechanisms for creating distribution, machine, and image
78 features during the build process using the OpenEmbedded build system.</para></listitem>
79 <listitem><para><emphasis>
80 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
81 Presents most variables used by the OpenEmbedded build system, which
82 uses BitBake.
83 Entries describe the function of the variable and how to apply them.
84 </para></listitem>
85 <listitem><para><emphasis>
86 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
87 Provides variable locality or context.</para></listitem>
88 <listitem><para><emphasis>
89 <link linkend='faq'>FAQ</link>:</emphasis>
90 Provides answers for commonly asked questions in the Yocto Project
91 development environment.</para></listitem>
92 <listitem><para><emphasis>
93 <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
94 Provides guidance on how you can contribute back to the Yocto
95 Project.</para></listitem>
96 </itemizedlist>
97 </para>
98</section>
99
100
101<section id='intro-requirements'>
102<title>System Requirements</title>
103 <para>
104 For general Yocto Project system requirements, see the
105 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
106 in the Yocto Project Quick Start.
107 The remainder of this section provides details on system requirements
108 not covered in the Yocto Project Quick Start.
109 </para>
110
111 <section id='detailed-supported-distros'>
112 <title>Supported Linux Distributions</title>
113
114 <para>
115 Currently, the Yocto Project is supported on the following
116 distributions:
117 <note>
118 <para>
119 Yocto Project releases are tested against the stable Linux
120 distributions in the following list.
121 The Yocto Project should work on other distributions but
122 validation is not performed against them.
123 </para>
124
125 <para>
126 In particular, the Yocto Project does not support
127 and currently has no plans to support
128 rolling-releases or development distributions due to their
129 constantly changing nature.
130 We welcome patches and bug reports, but keep in mind that
131 our priority is on the supported platforms listed below.
132 </para>
133
134 <para>
135 If you encounter problems, please go to
136 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
137 and submit a bug.
138 We are interested in hearing about your experience.
139 </para>
140 </note>
141 <itemizedlist>
142<!-- <listitem><para>Ubuntu 10.04</para></listitem>
143 <listitem><para>Ubuntu 11.10</para></listitem> -->
144 <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
145 <listitem><para>Ubuntu 13.10</para></listitem>
146 <listitem><para>Ubuntu 14.04 (LTS)</para></listitem>
147<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
148 <listitem><para>Fedora 17 (Spherical)</para></listitem> -->
149 <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
150 <listitem><para>Fedora release 20 (Heisenbug)</para></listitem>
151<!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem>
152 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
153 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
154 <listitem><para>CentOS release 6.3 (Final)</para></listitem> -->
155 <listitem><para>CentOS release 6.4</para></listitem>
156 <listitem><para>CentOS release 6.5</para></listitem>
157<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> -->
158 <listitem><para>Debian GNU/Linux 7.0 (Wheezy)</para></listitem>
159 <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
160 <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
161 <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
162 <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
163<!-- <listitem><para>openSUSE 11.4</para></listitem>
164 <listitem><para>openSUSE 12.1</para></listitem> -->
165 <listitem><para>openSUSE 12.2</para></listitem>
166 <listitem><para>openSUSE 12.3</para></listitem>
167 <listitem><para>openSUSE 13.1</para></listitem>
168 </itemizedlist>
169 </para>
170
171 <note>
172 While the Yocto Project Team attempts to ensure all Yocto Project
173 releases are one hundred percent compatible with each officially
174 supported Linux distribution, instances might exist where you
175 encounter a problem while using the Yocto Project on a specific
176 distribution.
177 For example, the CentOS 6.4 distribution does not include the
178 Gtk+ 2.20.0 and PyGtk 2.21.0 (or higher) packages, which are
179 required to run
180 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
181 </note>
182 </section>
183
184 <section id='required-packages-for-the-host-development-system'>
185 <title>Required Packages for the Host Development System</title>
186
187 <para>
188 The list of packages you need on the host development system can
189 be large when covering all build scenarios using the Yocto Project.
190 This section provides required packages according to
191 Linux distribution and function.
192 </para>
193
194 <section id='ubuntu-packages'>
195 <title>Ubuntu and Debian</title>
196
197 <para>
198 The following list shows the required packages by function
199 given a supported Ubuntu or Debian Linux distribution:
200 <itemizedlist>
201 <listitem><para><emphasis>Essentials:</emphasis>
202 Packages needed to build an image on a headless
203 system:
204 <literallayout class='monospaced'>
205 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
206 </literallayout></para></listitem>
207 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
208 Packages recommended if the host system has graphics
209 support or if you are going to use the Eclipse
210 IDE:
211 <literallayout class='monospaced'>
212 $ sudo apt-get install libsdl1.2-dev xterm
213 </literallayout></para></listitem>
214 <listitem><para><emphasis>Documentation:</emphasis>
215 Packages needed if you are going to build out the
216 Yocto Project documentation manuals:
217 <literallayout class='monospaced'>
218 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
219 </literallayout></para></listitem>
220 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
221 Packages needed if you are going to be using the
222 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
223 <literallayout class='monospaced'>
224 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
225 </literallayout></para></listitem>
226 </itemizedlist>
227 </para>
228 </section>
229
230 <section id='fedora-packages'>
231 <title>Fedora Packages</title>
232
233 <para>
234 The following list shows the required packages by function
235 given a supported Fedora Linux distribution:
236 <itemizedlist>
237 <listitem><para><emphasis>Essentials:</emphasis>
238 Packages needed to build an image for a headless
239 system:
240 <literallayout class='monospaced'>
241 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
242 </literallayout></para></listitem>
243 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
244 Packages recommended if the host system has graphics
245 support or if you are going to use the Eclipse
246 IDE:
247 <literallayout class='monospaced'>
248 $ sudo yum install SDL-devel xterm perl-Thread-Queue
249 </literallayout></para></listitem>
250 <listitem><para><emphasis>Documentation:</emphasis>
251 Packages needed if you are going to build out the
252 Yocto Project documentation manuals:
253 <literallayout class='monospaced'>
254 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
255 docbook-dtds docbook-utils fop libxslt dblatex xmlto
256 </literallayout></para></listitem>
257 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
258 Packages needed if you are going to be using the
259 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
260 <literallayout class='monospaced'>
261 $ sudo yum install autoconf automake libtool glib2-devel
262 </literallayout></para></listitem>
263 </itemizedlist>
264 </para>
265 </section>
266
267 <section id='opensuse-packages'>
268 <title>openSUSE Packages</title>
269
270 <para>
271 The following list shows the required packages by function
272 given a supported openSUSE Linux distribution:
273 <itemizedlist>
274 <listitem><para><emphasis>Essentials:</emphasis>
275 Packages needed to build an image for a headless
276 system:
277 <literallayout class='monospaced'>
278 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
279 </literallayout></para></listitem>
280 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
281 Packages recommended if the host system has graphics
282 support or if you are going to use the Eclipse
283 IDE:
284 <literallayout class='monospaced'>
285 $ sudo zypper install libSDL-devel xterm
286 </literallayout></para></listitem>
287 <listitem><para><emphasis>Documentation:</emphasis>
288 Packages needed if you are going to build out the
289 Yocto Project documentation manuals:
290 <literallayout class='monospaced'>
291 $ sudo zypper install make fop xsltproc dblatex xmlto
292 </literallayout></para></listitem>
293 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
294 Packages needed if you are going to be using the
295 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
296 <literallayout class='monospaced'>
297 $ sudo zypper install autoconf automake libtool glib2-devel
298 </literallayout></para></listitem>
299 </itemizedlist>
300 </para>
301 </section>
302
303 <section id='centos-packages'>
304 <title>CentOS Packages</title>
305
306 <para>
307 The following list shows the required packages by function
308 given a supported CentOS Linux distribution:
309 <note>Depending on the CentOS version you are using, other requirements
310 and dependencies might exist.
311 For details, you should look at the CentOS sections on the
312 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
313 wiki page.
314 </note>
315 <itemizedlist>
316 <listitem><para><emphasis>Essentials:</emphasis>
317 Packages needed to build an image for a headless
318 system:
319 <literallayout class='monospaced'>
320 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;
321 </literallayout></para></listitem>
322 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
323 Packages recommended if the host system has graphics
324 support or if you are going to use the Eclipse
325 IDE:
326 <literallayout class='monospaced'>
327 $ sudo yum install SDL-devel xterm
328 </literallayout></para></listitem>
329 <listitem><para><emphasis>Documentation:</emphasis>
330 Packages needed if you are going to build out the
331 Yocto Project documentation manuals:
332 <literallayout class='monospaced'>
333 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
334 docbook-dtds docbook-utils fop libxslt dblatex xmlto
335 </literallayout></para></listitem>
336 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
337 Packages needed if you are going to be using the
338 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
339 <literallayout class='monospaced'>
340 $ sudo yum install autoconf automake libtool glib2-devel
341 </literallayout></para></listitem>
342 </itemizedlist>
343 </para>
344 </section>
345 </section>
346
347 <section id='required-git-tar-and-python-versions'>
348 <title>Required Git, tar, and Python Versions</title>
349
350 <para>
351 In order to use the build system, your host development system
352 must meet the following version requirements for Git, tar, and
353 Python:
354 <itemizedlist>
355 <listitem><para>Git 1.7.5 or greater</para></listitem>
356 <listitem><para>tar 1.24 or greater</para></listitem>
357 <listitem><para>Python 2.7.3 or greater not including
358 Python 3.x, which is not supported.</para></listitem>
359 </itemizedlist>
360 </para>
361
362 <para>
363 If your host development system does not meet all these requirements,
364 you can resolve this by installing a <filename>buildtools</filename>
365 tarball that contains these tools.
366 You can get the tarball one of two ways: download a pre-built
367 tarball or use BitBake to build the tarball.
368 </para>
369
370 <section id='downloading-a-pre-built-buildtools-tarball'>
371 <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
372
373 <para>
374 Downloading and running a pre-built buildtools installer is
375 the easiest of the two methods by which you can get these tools:
376 <orderedlist>
377 <listitem><para>
378 Locate and download the <filename>*.sh</filename> at
379 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
380 </para></listitem>
381 <listitem><para>
382 Execute the installation script.
383 Here is an example:
384 <literallayout class='monospaced'>
385 $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
386 </literallayout>
387 During execution, a prompt appears that allows you to
388 choose the installation directory.
389 For example, you could choose the following:
390 <literallayout class='monospaced'>
391 /home/your-username/buildtools
392 </literallayout>
393 </para></listitem>
394 <listitem><para>
395 Source the tools environment setup script by using a
396 command like the following:
397 <literallayout class='monospaced'>
398 $ source /home/your-username/buildtools/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 <para>
404 After you have sourced the setup script,
405 the tools are added to <filename>PATH</filename>
406 and any other environment variables required to run the
407 tools are initialized.
408 The results are working versions versions of Git, tar,
409 Python and <filename>chrpath</filename>.
410 </para></listitem>
411 </orderedlist>
412 </para>
413 </section>
414
415 <section id='building-your-own-buildtools-tarball'>
416 <title>Building Your Own <filename>buildtools</filename> Tarball</title>
417
418 <para>
419 Building and running your own buildtools installer applies
420 only when you have a build host that can already run BitBake.
421 In this case, you use that machine to build the
422 <filename>.sh</filename> file and then
423 take steps to transfer and run it on a
424 machine that does not meet the minimal Git, tar, and Python
425 requirements.
426 </para>
427
428 <para>
429 Here are the steps to take to build and run your own
430 buildtools installer:
431 <orderedlist>
432 <listitem><para>
433 On the machine that is able to run BitBake,
434 be sure you have set up your build environment with
435 the setup script
436 (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
437 or
438 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
439 </para></listitem>
440 <listitem><para>
441 Run the BitBake command to build the tarball:
442 <literallayout class='monospaced'>
443 $ bitbake buildtools-tarball
444 </literallayout>
445 <note>
446 The
447 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
448 variable in your <filename>local.conf</filename> file
449 determines whether you build tools for a 32-bit
450 or 64-bit system.
451 </note>
452 Once the build completes, you can find the
453 <filename>.sh</filename> file that installs
454 the tools in the <filename>tmp/deploy/sdk</filename>
455 subdirectory of the
456 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
457 The installer file has the string "buildtools"
458 in the name.
459 </para></listitem>
460 <listitem><para>
461 Transfer the <filename>.sh</filename> file from the
462 build host to the machine that does not meet the
463 Git, tar, or Python requirements.
464 </para></listitem>
465 <listitem><para>
466 On the machine that does not meet the requirements,
467 run the <filename>.sh</filename> file
468 to install the tools.
469 Here is an example:
470 <literallayout class='monospaced'>
471 $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
472 </literallayout>
473 During execution, a prompt appears that allows you to
474 choose the installation directory.
475 For example, you could choose the following:
476 <literallayout class='monospaced'>
477 /home/your-username/buildtools
478 </literallayout>
479 </para></listitem>
480 <listitem><para>
481 Source the tools environment setup script by using a
482 command like the following:
483 <literallayout class='monospaced'>
484 $ source /home/your-username/buildtools/environment-setup-i586-poky-linux
485 </literallayout>
486 Of course, you need to supply your installation directory and be
487 sure to use the right file (i.e. i585 or x86-64).
488 </para>
489 <para>
490 After you have sourced the setup script,
491 the tools are added to <filename>PATH</filename>
492 and any other environment variables required to run the
493 tools are initialized.
494 The results are working versions versions of Git, tar,
495 Python and <filename>chrpath</filename>.
496 </para></listitem>
497 </orderedlist>
498 </para>
499 </section>
500 </section>
501</section>
502
503<section id='intro-getit'>
504 <title>Obtaining the Yocto Project</title>
505 <para>
506 The Yocto Project development team makes the Yocto Project available through a number
507 of methods:
508 <itemizedlist>
509 <listitem><para><emphasis>Source Repositories:</emphasis>
510 Working from a copy of the upstream
511 <filename>poky</filename> repository is the
512 preferred method for obtaining and using a Yocto Project
513 release.
514 You can view the Yocto Project Source Repositories at
515 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
516 In particular, you can find the
517 <filename>poky</filename> repository at
518 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
519 </para></listitem>
520 <listitem><para><emphasis>Releases:</emphasis> Stable, tested
521 releases are available as tarballs through
522 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
523 <listitem><para><emphasis>Nightly Builds:</emphasis> These
524 tarball releases are available at
525 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
526 These builds include Yocto Project releases, meta-toolchain
527 tarball installation scripts, and experimental builds.
528 </para></listitem>
529 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can
530 find tarball releases of the Yocto Project and supported BSPs
531 at the
532 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
533 Along with these downloads, you can find lots of other
534 information at this site.
535 </para></listitem>
536 </itemizedlist>
537 </para>
538</section>
539
540<section id='intro-getit-dev'>
541 <title>Development Checkouts</title>
542 <para>
543 Development using the Yocto Project requires a local
544 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
545 You can set up the Source Directory by cloning a copy of the upstream
546 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> Git repository.
547 For information on how to do this, see the
548 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
549 section in the Yocto Project Development Manual.
550 </para>
551</section>
552
553</chapter>
554<!--
555vim: expandtab tw=80 ts=4
556-->
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
new file mode 100644
index 0000000..7cefa5e
--- /dev/null
+++ b/documentation/ref-manual/migration.xml
@@ -0,0 +1,1616 @@
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 arising
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'><filename>packagegroup.bbclass</filename></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 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 class, 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'><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='migration-1.5-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
1087<section id='moving-to-the-yocto-project-1.6-release'>
1088 <title>Moving to the Yocto Project 1.6 Release</title>
1089
1090 <para>
1091 This section provides migration information for moving to the
1092 Yocto Project 1.6 Release from the prior release.
1093 </para>
1094
1095
1096 <section id='migration-1.6-archiver-class'>
1097 <title><filename>archiver</filename> Class</title>
1098
1099 <para>
1100 The
1101 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
1102 class has been rewritten and its configuration has been simplified.
1103 For more details on the source archiver, see the
1104 "<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>"
1105 section in the Yocto Project Development Manual.
1106 </para>
1107 </section>
1108
1109 <section id='migration-1.6-packaging-changes'>
1110 <title>Packaging Changes</title>
1111
1112 <para>
1113 The following packaging changes have been made:
1114 <itemizedlist>
1115 <listitem><para>
1116 The <filename>binutils</filename> recipe no longer produces
1117 a <filename>binutils-symlinks</filename> package.
1118 <filename>update-alternatives</filename> is now used to
1119 handle the preferred <filename>binutils</filename>
1120 variant on the target instead.
1121 </para></listitem>
1122 <listitem><para>
1123 The tc (traffic control) utilities have been split out of
1124 the main <filename>iproute2</filename> package and put
1125 into the <filename>iproute2-tc</filename> package.
1126 </para></listitem>
1127 <listitem><para>
1128 The <filename>gtk-engines</filename> schemas have been
1129 moved to a dedicated
1130 <filename>gtk-engines-schemas</filename> package.
1131 </para></listitem>
1132 <listitem><para>
1133 The <filename>armv7a</filename> with thumb package
1134 architecture suffix has changed.
1135 The suffix for these packages with the thumb
1136 optimization enabled is "t2" as it should be.
1137 Use of this suffix was not the case in the 1.5 release.
1138 Architecture names will change within package feeds as a
1139 result.
1140 </para></listitem>
1141 </itemizedlist>
1142 </para>
1143 </section>
1144
1145 <section id='migration-1.6-bitbake'>
1146 <title>BitBake</title>
1147
1148 <para>
1149 The following changes have been made to
1150 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
1151 </para>
1152
1153 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
1154 <title>Matching Branch Requirement for Git Fetching</title>
1155
1156 <para>
1157 When fetching source from a Git repository using
1158 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
1159 BitBake will now validate the
1160 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
1161 value against the branch.
1162 You can specify the branch using the following form:
1163 <literallayout class='monospaced'>
1164 SRC_URI = "git://server.name/repository;branch=&lt;branchname&gt;"
1165 </literallayout>
1166 If you do not specify a branch, BitBake looks
1167 in the default "master" branch.
1168 </para>
1169
1170 <para>
1171 Alternatively, if you need to bypass this check (e.g.
1172 if you are fetching a revision corresponding to a tag that
1173 is not on any branch), you can add ";nobranch=1" to
1174 the end of the URL within <filename>SRC_URI</filename>.
1175 </para>
1176 </section>
1177
1178 <section id='migration-1.6-bitbake-deps'>
1179 <title>Python Definition substitutions</title>
1180
1181 <para>
1182 BitBake had some previously deprecated Python definitions
1183 within its <filename>bb</filename> module removed.
1184 You should use their sub-module counterparts instead:
1185 <itemizedlist>
1186 <listitem><para><filename>bb.MalformedUrl</filename>:
1187 Use <filename>bb.fetch.MalformedUrl</filename>.
1188 </para></listitem>
1189 <listitem><para><filename>bb.fetch.encodeurl</filename>:
1190 Use <filename>bb.fetch.encodeurl</filename>.
1191 </para></listitem>
1192 <listitem><para><filename>bb.decodeurl</filename>:
1193 Use <filename>bb.fetch.decodeurl</filename>
1194 </para></listitem>
1195 <listitem><para><filename>bb.mkdirhier</filename>:
1196 Use <filename>bb.utils.mkdirhier</filename>.
1197 </para></listitem>
1198 <listitem><para><filename>bb.movefile</filename>:
1199 Use <filename>bb.utils.movefile</filename>.
1200 </para></listitem>
1201 <listitem><para><filename>bb.copyfile</filename>:
1202 Use <filename>bb.utils.copyfile</filename>.
1203 </para></listitem>
1204 <listitem><para><filename>bb.which</filename>:
1205 Use <filename>bb.utils.which</filename>.
1206 </para></listitem>
1207 <listitem><para><filename>bb.vercmp_string</filename>:
1208 Use <filename>bb.utils.vercmp_string</filename>.
1209 </para></listitem>
1210 <listitem><para><filename>bb.vercmp</filename>:
1211 Use <filename>bb.utils.vercmp</filename>.
1212 </para></listitem>
1213 </itemizedlist>
1214 </para>
1215 </section>
1216
1217 <section id='migration-1.6-bitbake-fetcher'>
1218 <title>SVK Fetcher</title>
1219
1220 <para>
1221 The SVK fetcher has been removed from BitBake.
1222 </para>
1223 </section>
1224
1225 <section id='migration-1.6-bitbake-console-output'>
1226 <title>Console Output Error Redirection</title>
1227
1228 <para>
1229 The BitBake console UI will now output errors to
1230 <filename>stderr</filename> instead of
1231 <filename>stdout</filename>.
1232 Consequently, if you are piping or redirecting the output of
1233 <filename>bitbake</filename> to somewhere else, and you wish
1234 to retain the errors, you will need to add
1235 <filename>2>&amp;1</filename> (or something similar) to the
1236 end of your <filename>bitbake</filename> command line.
1237 </para>
1238 </section>
1239
1240 <section id='migration-1.6-task-taskname-overrides'>
1241 <title><filename>task-&lt;taskname&gt;</filename> Overrides</title>
1242
1243 <para>
1244 <filename>task-&lt;taskname&gt;</filename> overrides have been
1245 adjusted so that tasks whose names contain underscores have the
1246 underscores replaced by hyphens for the override so that they
1247 now function properly.
1248 For example, the task override for
1249 <filename>do_populate_sdk</filename> is
1250 <filename>task-populate-sdk</filename>.
1251 </para>
1252 </section>
1253 </section>
1254
1255 <section id='migration-1.6-variable-changes'>
1256 <title>Changes to Variables</title>
1257
1258 <para>
1259 The following variables have changed.
1260 For information on the OpenEmbedded build system variables, see the
1261 "<link linkend='ref-variables-glos'>Variables Glossary</link>" Chapter.
1262 </para>
1263
1264 <section id='migration-1.6-variable-changes-TMPDIR'>
1265 <title><filename>TMPDIR</filename></title>
1266
1267 <para>
1268 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1269 can no longer be on an NFS mount.
1270 NFS does not offer full POSIX locking and inode consistency
1271 and can cause unexpected issues if used to store
1272 <filename>TMPDIR</filename>.
1273 </para>
1274
1275 <para>
1276 The check for this occurs on startup.
1277 If <filename>TMPDIR</filename> is detected on an NFS mount,
1278 an error occurs.
1279 </para>
1280 </section>
1281
1282 <section id='migration-1.6-variable-changes-PRINC'>
1283 <title><filename>PRINC</filename></title>
1284
1285 <para>
1286 The
1287 <link linkend='var-PRINC'><filename>PRINC</filename></link>
1288 variable has been deprecated and triggers a warning if
1289 detected during a build.
1290 For
1291 <link linkend='var-PR'><filename>PR</filename></link>
1292 increments on changes, use the PR service instead.
1293 You can find out more about this service in the
1294 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
1295 section in the Yocto Project Development Manual.
1296 </para>
1297 </section>
1298
1299 <section id='migration-1.6-variable-changes-IMAGE_TYPES'>
1300 <title><filename>IMAGE_TYPES</filename></title>
1301
1302 <para>
1303 The "sum.jffs2" option for
1304 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>
1305 has been replaced by the "jffs2.sum" option, which fits the
1306 processing order.
1307 </para>
1308 </section>
1309
1310 <section id='migration-1.6-variable-changes-COPY_LIC_MANIFEST'>
1311 <title><filename>COPY_LIC_MANIFEST</filename></title>
1312
1313 <para>
1314 The
1315 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1316 variable must
1317 now be set to "1" rather than any value in order to enable
1318 it.
1319 </para>
1320 </section>
1321
1322 <section id='migration-1.6-variable-changes-COPY_LIC_DIRS'>
1323 <title><filename>COPY_LIC_DIRS</filename></title>
1324
1325 <para>
1326 The
1327 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
1328 variable must
1329 now be set to "1" rather than any value in order to enable
1330 it.
1331 </para>
1332 </section>
1333
1334 <section id='migration-1.6-variable-changes-PACKAGE_GROUP'>
1335 <title><filename>PACKAGE_GROUP</filename></title>
1336
1337 <para>
1338 The
1339 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
1340 variable has been renamed to
1341 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>
1342 to more accurately reflect its purpose.
1343 You can still use <filename>PACKAGE_GROUP</filename> but
1344 the OpenEmbedded build system produces a warning message when
1345 it encounters the variable.
1346 </para>
1347 </section>
1348 </section>
1349
1350 <section id='migration-1.6-directory-layout-changes'>
1351 <title>Directory Layout Changes</title>
1352
1353 <para>
1354 The <filename>meta-hob</filename> layer has been removed from
1355 the top-level of the
1356 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1357 The contents of this layer are no longer needed by the Hob
1358 user interface for building images and toolchains.
1359 </para>
1360 </section>
1361
1362 <section id='migration-1.6-build-changes'>
1363 <title>Build Changes</title>
1364
1365 <para>
1366 Separate build and source directories have been enabled
1367 by default for selected recipes where it is known to work
1368 (a whitelist) and for all recipes that inherit the
1369 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
1370 class.
1371 In future releases the
1372 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1373 class will enable a separate build directory by default as
1374 well.
1375 Recipes building Autotools-based
1376 software that fails to build with a separate build directory
1377 should be changed to inherit from the
1378 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
1379 class instead of the <filename>autotools</filename> class.
1380 </para>
1381 </section>
1382
1383 <section id='migration-1.6-building-qemu-native'>
1384 <title><filename>qemu-native</filename></title>
1385
1386 <para>
1387 <filename>qemu-native</filename> now builds without
1388 SDL-based graphical output support by default.
1389 The following additional lines are needed in your
1390 <filename>local.conf</filename> to enable it:
1391 <literallayout class='monospaced'>
1392 PACKAGECONFIG_pn-qemu-native = "sdl"
1393 ASSUME_PROVIDED += "libsdl-native"
1394 </literallayout>
1395 <note>
1396 The default <filename>local.conf</filename>
1397 contains these statements.
1398 Consequently, if you are building a headless system and using
1399 a default <filename>local.conf</filename> file, you will need
1400 comment these two lines out.
1401 </note>
1402 </para>
1403 </section>
1404
1405 <section id='migration-1.6-core-image-basic'>
1406 <title><filename>core-image-basic</filename></title>
1407
1408 <para>
1409 <filename>core-image-basic</filename> has been renamed to
1410 <filename>core-image-full-cmdline</filename>.
1411 </para>
1412
1413 <para>
1414 In addition to <filename>core-image-basic</filename> being renamed,
1415 <filename>packagegroup-core-basic</filename> has been renamed to
1416 <filename>packagegroup-core-full-cmdline</filename> to match.
1417 </para>
1418 </section>
1419
1420 <section id='migration-1.6-licensing'>
1421 <title>Licensing</title>
1422
1423 <para>
1424 The top-level <filename>LICENSE</filename> file has been changed
1425 to better describe the license of the various components of
1426 OE-Core.
1427 However, the licensing itself remains unchanged.
1428 </para>
1429
1430 <para>
1431 Normally, this change would not cause any side-effects.
1432 However, some recipes point to this file within
1433 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
1434 (as <filename>${COREBASE}/LICENSE</filename>) and thus the
1435 accompanying checksum must be changed from
1436 3f40d7994397109285ec7b81fdeb3b58 to
1437 4d92cd373abda3937c2bc47fbc49d690.
1438 A better alternative is to have
1439 <filename>LIC_FILES_CHKSUM</filename> point to a file
1440 describing the license that is distributed with the source
1441 that the recipe is building, if possible, rather than pointing
1442 to <filename>${COREBASE}/LICENSE</filename>.
1443 </para>
1444 </section>
1445
1446 <section id='migration-1.6-cflags-options'>
1447 <title><filename>CFLAGS</filename> Options</title>
1448
1449 <para>
1450 The "-fpermissive" option has been removed from the default
1451 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1452 value.
1453 You need to take action on individual recipes that fail when
1454 building with this option.
1455 You need to either patch the recipes to fix the issues reported by
1456 the compiler, or you need to add "-fpermissive" to
1457 <filename>CFLAGS</filename> in the recipes.
1458 </para>
1459 </section>
1460
1461 <section id='migration-1.6-custom-images'>
1462 <title>Custom Image Output Types</title>
1463
1464 <para>
1465 Custom image output types, as selected using
1466 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
1467 must declare their dependencies on other image types (if any) using
1468 a new
1469 <link linkend='var-IMAGE_TYPEDEP'><filename>IMAGE_TYPEDEP</filename></link>
1470 variable.
1471 </para>
1472 </section>
1473
1474 <section id='migration-1.6-do-package-write-task'>
1475 <title>Tasks</title>
1476
1477 <para>
1478 The <filename>do_package_write</filename> task has been removed.
1479 The task is no longer needed.
1480 </para>
1481 </section>
1482
1483 <section id='migration-1.6-update-alternatives-provider'>
1484 <title><filename>update-alternative</filename> Provider</title>
1485
1486 <para>
1487 The default <filename>update-alternatives</filename> provider has
1488 been changed from <filename>opkg</filename> to
1489 <filename>opkg-utils</filename>.
1490 This change resolves some troublesome circular dependencies.
1491 The runtime package has also been renamed from
1492 <filename>update-alternatives-cworth</filename>
1493 to <filename>update-alternatives-opkg</filename>.
1494 </para>
1495 </section>
1496
1497 <section id='migration-1.6-virtclass-overrides'>
1498 <title><filename>virtclass</filename> Overrides</title>
1499
1500 <para>
1501 The <filename>virtclass</filename> overrides are now deprecated.
1502 Use the equivalent class overrides instead (e.g.
1503 <filename>virtclass-native</filename> becomes
1504 <filename>class-native</filename>.)
1505 </para>
1506 </section>
1507
1508 <section id='migration-1.6-removed-renamed-recipes'>
1509 <title>Removed and Renamed Recipes</title>
1510
1511 <para>
1512 The following recipes have been removed:
1513 <itemizedlist>
1514 <listitem><para><filename>packagegroup-toolset-native</filename> -
1515 This recipe is largely unused.
1516 </para></listitem>
1517 <listitem><para><filename>linux-yocto-3.8</filename> -
1518 Support for the Linux yocto 3.8 kernel has been dropped.
1519 Support for the 3.10 and 3.14 kernels have been added
1520 with the <filename>linux-yocto-3.10</filename> and
1521 <filename>linux-yocto-3.14</filename> recipes.
1522 </para></listitem>
1523 <listitem><para><filename>ocf-linux</filename> -
1524 This recipe has been functionally replaced using
1525 <filename>cryptodev-linux</filename>.
1526 </para></listitem>
1527 <listitem><para><filename>genext2fs</filename> -
1528 <filename>genext2fs</filename> is no longer used by the
1529 build system and is unmaintained upstream.
1530 </para></listitem>
1531 <listitem><para><filename>js</filename> -
1532 This provided an ancient version of Mozilla's javascript
1533 engine that is no longer needed.
1534 </para></listitem>
1535 <listitem><para><filename>zaurusd</filename> -
1536 The recipe has been moved to the
1537 <filename>meta-handheld</filename> layer.
1538 </para></listitem>
1539 <listitem><para><filename>eglibc 2.17</filename> -
1540 Replaced by the <filename>eglibc 2.19</filename>
1541 recipe.
1542 </para></listitem>
1543 <listitem><para><filename>gcc 4.7.2</filename> -
1544 Replaced by the now stable
1545 <filename>gcc 4.8.2</filename>.
1546 </para></listitem>
1547 <listitem><para><filename>external-sourcery-toolchain</filename> -
1548 this recipe is now maintained in the
1549 <filename>meta-sourcery</filename> layer.
1550 </para></listitem>
1551 <listitem><para><filename>linux-libc-headers-yocto 3.4+git</filename> -
1552 Now using version 3.10 of the
1553 <filename>linux-libc-headers</filename> by default.
1554 </para></listitem>
1555 <listitem><para><filename>meta-toolchain-gmae</filename> -
1556 This recipe is obsolete.
1557 </para></listitem>
1558 <listitem><para><filename>packagegroup-core-sdk-gmae</filename> -
1559 This recipe is obsolete.
1560 </para></listitem>
1561 <listitem><para><filename>packagegroup-core-standalone-gmae-sdk-target</filename> -
1562 This recipe is obsolete.
1563 </para></listitem>
1564 </itemizedlist>
1565 </para>
1566 </section>
1567
1568 <section id='migration-1.6-removed-classes'>
1569 <title>Removed Classes</title>
1570
1571 <para>
1572 The following classes have become obsolete and have been removed:
1573 <itemizedlist>
1574 <listitem><para><filename>module_strip</filename>
1575 </para></listitem>
1576 <listitem><para><filename>pkg_metainfo</filename>
1577 </para></listitem>
1578 <listitem><para><filename>pkg_distribute</filename>
1579 </para></listitem>
1580 <listitem><para><filename>image-empty</filename>
1581 </para></listitem>
1582 </itemizedlist>
1583 </para>
1584 </section>
1585
1586 <section id='migration-1.6-reference-bsps'>
1587 <title>Reference Board Support Packages (BSPs)</title>
1588
1589 <para>
1590 The following reference BSPs changes occurred:
1591 <itemizedlist>
1592 <listitem><para>The BeagleBoard
1593 (<filename>beagleboard</filename>) ARM reference hardware
1594 has been replaced by the BeagleBone
1595 (<filename>beaglebone</filename>) hardware.
1596 </para></listitem>
1597 <listitem><para>The RouterStation Pro
1598 (<filename>routerstationpro</filename>) MIPS reference
1599 hardware has been replaced by the EdgeRouter Lite
1600 (<filename>edgerouter</filename>) hardware.
1601 </para></listitem>
1602 </itemizedlist>
1603 The previous reference BSPs for the
1604 <filename>beagleboard</filename> and
1605 <filename>routerstationpro</filename> machines are still available
1606 in a new <filename>meta-yocto-bsp-old</filename> layer in the
1607 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1608 at
1609 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/'>http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/</ulink>.
1610 </para>
1611 </section>
1612</section>
1613</chapter>
1614<!--
1615vim: expandtab tw=80 ts=4
1616-->
diff --git a/documentation/ref-manual/ref-bitbake.xml b/documentation/ref-manual/ref-bitbake.xml
new file mode 100644
index 0000000..28496de
--- /dev/null
+++ b/documentation/ref-manual/ref-bitbake.xml
@@ -0,0 +1,472 @@
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
118 <note>
119 <para>
120 You need to be aware of how BitBake parses curly braces.
121 If a recipe uses a closing curly brace within the function and
122 the character has no leading spaces, BitBake produces a parsing
123 error.
124 If you use a pair of curly brace in a shell function, the
125 closing curly brace must not be located at the start of the line
126 without leading spaces.
127 </para>
128
129 <para>
130 Here is an example that causes BitBake to produce a parsing
131 error:
132 <literallayout class='monospaced'>
133 fakeroot create_shar() {
134 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
135 usage()
136 {
137 echo "test"
138 ###### The following "}" at the start of the line causes a parsing error ######
139 }
140 EOF
141 }
142 </literallayout>
143 Writing the recipe this way avoids the error:
144 <literallayout class='monospaced'>
145 fakeroot create_shar() {
146 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
147 usage()
148 {
149 echo "test"
150 ######The following "}" with a leading space at the start of the line avoids the error ######
151 }
152 EOF
153 }
154 </literallayout>
155 </para>
156 </note>
157 </section>
158
159 <section id='ref-bitbake-providers'>
160 <title>Preferences and Providers</title>
161
162 <para>
163 Once all the <filename>.bb</filename> files have been
164 parsed, BitBake starts to build the target (<filename>core-image-sato</filename>
165 in the previous section's example) and looks for providers of that target.
166 Once a provider is selected, BitBake resolves all the dependencies for
167 the target.
168 In the case of <filename>core-image-sato</filename>, it would lead to
169 <filename>packagegroup-core-x11-sato</filename>,
170 which in turn leads to recipes like <filename>matchbox-terminal</filename>,
171 <filename>pcmanfm</filename> and <filename>gthumb</filename>.
172 These recipes in turn depend on <filename>eglibc</filename> and the toolchain.
173 </para>
174
175 <para>
176 Sometimes a target might have multiple providers.
177 A common example is "virtual/kernel", which is provided by each kernel package.
178 Each machine often selects the best kernel provider by using a line similar to the
179 following in the machine configuration file:
180 </para>
181
182 <literallayout class='monospaced'>
183 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
184 </literallayout>
185
186 <para>
187 The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename>
188 is the provider with the same name as the target.
189 </para>
190
191 <para>
192 Understanding how providers are chosen is made complicated by the fact
193 that multiple versions might exist.
194 BitBake defaults to the highest version of a provider.
195 Version comparisons are made using the same method as Debian.
196 You can use the
197 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
198 variable to specify a particular version (usually in the distro configuration).
199 You can influence the order by using the
200 <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename>
201 variable.
202 By default, files have a preference of "0".
203 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
204 package unlikely to be used unless it is explicitly referenced.
205 Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used.
206 <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
207 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package
208 versions until they have undergone sufficient testing to be considered stable.
209 </para>
210
211 <para>
212 In summary, BitBake has created a list of providers, which is prioritized, for each target.
213 </para>
214 </section>
215
216 <section id='ref-bitbake-dependencies'>
217 <title>Dependencies</title>
218
219 <para>
220 Each target BitBake builds consists of multiple tasks such as
221 <filename>fetch</filename>, <filename>unpack</filename>,
222 <filename>patch</filename>, <filename>configure</filename>,
223 and <filename>compile</filename>.
224 For best performance on multi-core systems, BitBake considers each task as an independent
225 entity with its own set of dependencies.
226 </para>
227
228 <para>
229 Dependencies are defined through several variables.
230 You can find information about variables BitBake uses in the BitBake documentation,
231 which is found in the <filename>bitbake/doc/manual</filename> directory within the
232 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
233 At a basic level, it is sufficient to know that BitBake uses the
234 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and
235 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when
236 calculating dependencies.
237 </para>
238 </section>
239
240 <section id='ref-bitbake-tasklist'>
241 <title>The Task List</title>
242
243 <para>
244 Based on the generated list of providers and the dependency information,
245 BitBake can now calculate exactly what tasks it needs to run and in what
246 order it needs to run them.
247 The build now starts with BitBake forking off threads up to the limit set in the
248 <filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></filename> variable.
249 BitBake continues to fork threads as long as there are tasks ready to run,
250 those tasks have all their dependencies met, and the thread threshold has not been
251 exceeded.
252 </para>
253
254 <para>
255 It is worth noting that you can greatly speed up the build time by properly setting
256 the <filename>BB_NUMBER_THREADS</filename> variable.
257 See the
258 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
259 section in the Yocto Project Quick Start for more information.
260 </para>
261
262 <para>
263 As each task completes, a timestamp is written to the directory specified by the
264 <filename><link linkend='var-STAMP'>STAMP</link></filename> variable.
265 On subsequent runs, BitBake looks within the <filename>build/tmp/stamps</filename>
266 directory and does not rerun
267 tasks that are already completed unless a timestamp is found to be invalid.
268 Currently, invalid timestamps are only considered on a per
269 <filename>.bb</filename> file basis.
270 So, for example, if the configure stamp has a timestamp greater than the
271 compile timestamp for a given target, then the compile task would rerun.
272 Running the compile task again, however, has no effect on other providers
273 that depend on that target.
274 This behavior could change or become configurable in future versions of BitBake.
275 </para>
276
277 <note>
278 Some tasks are marked as "nostamp" tasks.
279 No timestamp file is created when these tasks are run.
280 Consequently, "nostamp" tasks are always rerun.
281 </note>
282 </section>
283
284 <section id='ref-bitbake-runtask'>
285 <title>Running a Task</title>
286
287 <para>
288 Tasks can either be a shell task or a Python task.
289 For shell tasks, BitBake writes a shell script to
290 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script.
291 The generated shell script contains all the exported variables, and the shell functions
292 with all variables expanded.
293 Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
294 Looking at the expanded shell functions in the run file and the output in the log files
295 is a useful debugging technique.
296 </para>
297
298 <para>
299 For Python tasks, BitBake executes the task internally and logs information to the
300 controlling terminal.
301 Future versions of BitBake will write the functions to files similar to the way
302 shell tasks are handled.
303 Logging will be handled in a way similar to shell tasks as well.
304 </para>
305
306 <para>
307 Once all the tasks have been completed BitBake exits.
308 </para>
309
310 <para>
311 When running a task, BitBake tightly controls the execution environment
312 of the build tasks to make sure unwanted contamination from the build machine
313 cannot influence the build.
314 Consequently, if you do want something to get passed into the build
315 task's environment, you must take a few steps:
316 <orderedlist>
317 <listitem><para>Tell BitBake to load what you want from the environment
318 into the data store.
319 You can do so through the <filename>BB_ENV_EXTRAWHITE</filename>
320 variable.
321 For example, assume you want to prevent the build system from
322 accessing your <filename>$HOME/.ccache</filename> directory.
323 The following command tells BitBake to load
324 <filename>CCACHE_DIR</filename> from the environment into the data
325 store:
326 <literallayout class='monospaced'>
327 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
328 </literallayout></para></listitem>
329 <listitem><para>Tell BitBake to export what you have loaded into the
330 environment store to the task environment of every running task.
331 Loading something from the environment into the data store
332 (previous step) only makes it available in the datastore.
333 To export it to the task environment of every running task,
334 use a command similar to the following in your
335 <filename>local.conf</filename> or distro configuration file:
336 <literallayout class='monospaced'>
337 export CCACHE_DIR
338 </literallayout></para></listitem>
339 </orderedlist>
340 </para>
341
342 <note>
343 A side effect of the previous steps is that BitBake records the variable
344 as a dependency of the build process in things like the shared state
345 checksums.
346 If doing so results in unnecessary rebuilds of tasks, you can whitelist the
347 variable so that the shared state code ignores the dependency when it creates
348 checksums.
349 For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename>
350 example in the "<link linkend='checksums'>Checksums (Signatures)</link>" section.
351 </note>
352 </section>
353
354 <section id='ref-bitbake-commandline'>
355 <title>BitBake Command Line</title>
356
357 <para>
358 Following is the BitBake help output:
359 </para>
360
361 <screen>
362$ bitbake --help
363Usage: bitbake [options] [recipename/target ...]
364
365 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
366 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
367 will provide the layer, BBFILES and other configuration information.
368
369Options:
370 --version show program's version number and exit
371 -h, --help show this help message and exit
372 -b BUILDFILE, --buildfile=BUILDFILE
373 Execute tasks from a specific .bb recipe directly.
374 WARNING: Does not handle any dependencies from other
375 recipes.
376 -k, --continue Continue as much as possible after an error. While the
377 target that failed and anything depending on it cannot
378 be built, as much as possible will be built before
379 stopping.
380 -a, --tryaltconfigs Continue with builds by trying to use alternative
381 providers where possible.
382 -f, --force Force the specified targets/task to run (invalidating
383 any existing stamp file).
384 -c CMD, --cmd=CMD Specify the task to execute. The exact options
385 available depend on the metadata. Some examples might
386 be 'compile' or 'populate_sysroot' or 'listtasks' may
387 give a list of the tasks available.
388 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
389 Invalidate the stamp for the specified task such as
390 'compile' and then run the default task for the
391 specified target(s).
392 -r PREFILE, --read=PREFILE
393 Read the specified file before bitbake.conf.
394 -R POSTFILE, --postread=POSTFILE
395 Read the specified file after bitbake.conf.
396 -v, --verbose Output more log message data to the terminal.
397 -D, --debug Increase the debug level. You can specify this more
398 than once.
399 -n, --dry-run Don't execute, just go through the motions.
400 -S, --dump-signatures
401 Don't execute, just dump out the signature
402 construction information.
403 -p, --parse-only Quit after parsing the BB recipes.
404 -s, --show-versions Show current and preferred versions of all recipes.
405 -e, --environment Show the global or per-package environment complete
406 with information about where variables were
407 set/changed.
408 -g, --graphviz Save dependency tree information for the specified
409 targets in the dot syntax.
410 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
411 Assume these dependencies don't exist and are already
412 provided (equivalent to ASSUME_PROVIDED). Useful to
413 make dependency graphs more appealing
414 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
415 Show debug logging for the specified logging domains
416 -P, --profile Profile the command and save reports.
417 -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp).
418 -t SERVERTYPE, --servertype=SERVERTYPE
419 Choose which server to use, process or xmlrpc.
420 --revisions-changed Set the exit code depending on whether upstream
421 floating revisions have changed or not.
422 --server-only Run bitbake without a UI, only starting a server
423 (cooker) process.
424 -B BIND, --bind=BIND The name/address for the bitbake server to bind to.
425 --no-setscene Do not run any setscene tasks. sstate will be ignored
426 and everything needed, built.
427 --remote-server=REMOTE_SERVER
428 Connect to the specified server.
429 -m, --kill-server Terminate the remote server.
430 --observe-only Connect to a server as an observing-only client.
431 </screen>
432 </section>
433
434 <section id='ref-bitbake-fetchers'>
435 <title>Fetchers</title>
436
437 <para>
438 BitBake also contains a set of "fetcher" modules that allow
439 retrieval of source code from various types of sources.
440 For example, BitBake can get source code from a disk with the metadata, from websites,
441 from remote shell accounts, or from Source Code Management (SCM) systems
442 like <filename>cvs/subversion/git</filename>.
443 </para>
444
445 <para>
446 Fetchers are usually triggered by entries in
447 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
448 You can find information about the options and formats of entries for specific
449 fetchers in the BitBake manual located in the
450 <filename>bitbake/doc/manual</filename> directory of the
451 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
452 </para>
453
454 <para>
455 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
456 "auto-update" when the upstream SCM changes version.
457 Since this ability requires certain functionality from the SCM, not all
458 systems support it.
459 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
460 This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
461 variable.
462 See the
463 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section
464 in the Yocto Project Development Manual for more information.
465 </para>
466
467 </section>
468
469</chapter>
470<!--
471vim: expandtab tw=80 ts=4 spell spelllang=en_gb
472-->
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
new file mode 100644
index 0000000..da54608
--- /dev/null
+++ b/documentation/ref-manual/ref-classes.xml
@@ -0,0 +1,3255 @@
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
10 multiple recipe (<filename>.bb</filename>) files.
11 To use a class file, you simply make sure the recipe inherits the class.
12 In most cases, when a recipe inherits a class it is enough to enable its
13 features.
14 There are cases, however, where in the recipe you might need to set
15 variables or override some default behavior.
16</para>
17
18<para>
19 Any <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> usually
20 found in a recipe can also be placed in a class file.
21 Class files are identified by the extension <filename>.bbclass</filename>
22 and are usually placed in a <filename>classes/</filename> directory beneath
23 the <filename>meta*/</filename> directory found in the
24 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
25 Class files can also be pointed to by
26 <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link>
27 (e.g. <filename>build/</filename>) in the same way as
28 <filename>.conf</filename> files in the <filename>conf</filename> directory.
29 Class files are searched for in
30 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
31 using the same method by which <filename>.conf</filename> files are
32 searched.
33</para>
34
35<para>
36 This chapter discusses only the most useful and important classes.
37 Other classes do exist within the <filename>meta/classes</filename>
38 directory in the
39 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
40 You can reference the <filename>.bbclass</filename> files directly
41 for more information.
42</para>
43
44<section id='ref-classes-allarch'>
45 <title><filename>allarch.bbclass</filename></title>
46
47 <para>
48 The <filename>allarch</filename> class is inherited
49 by recipes that do not produce architecture-specific output.
50 The class disables functionality that is normally needed for recipes
51 that produce executable binaries (such as building the cross-compiler
52 and a C library as pre-requisites, and splitting out of debug symbols
53 during packaging).
54 </para>
55
56 <para>
57 By default, all recipes inherit the
58 <link linkend='ref-classes-base'><filename>base</filename></link> and
59 <link linkend='ref-classes-package'><filename>package</filename></link>
60 classes, which enable functionality
61 needed for recipes that produce executable output.
62 If your recipe, for example, only produces packages that contain
63 configuration files, media files, or scripts (e.g. Python and Perl),
64 then it should inherit the <filename>allarch</filename> class.
65 </para>
66</section>
67
68<section id='ref-classes-archiver'>
69 <title><filename>archiver.bbclass</filename></title>
70
71 <para>
72 The <filename>archiver</filename> class supports releasing
73 source code and other materials with the binaries.
74 </para>
75
76 <para>
77 For more details on the source archiver, see the
78 "<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>"
79 section in the Yocto Project Development Manual.
80 </para>
81</section>
82
83<section id='ref-classes-autotools'>
84 <title><filename>autotools.bbclass</filename></title>
85
86 <para>
87 The <filename>autotools</filename> class supports Autotooled
88 packages.
89 </para>
90
91 <para>
92 The <filename>autoconf</filename>, <filename>automake</filename>,
93 and <filename>libtool</filename> bring standardization.
94 This class defines a set of tasks (configure, compile etc.) that
95 work for all Autotooled packages.
96 It should usually be enough to define a few standard variables
97 and then simply <filename>inherit autotools</filename>.
98 This class can also work with software that emulates Autotools.
99 For more information, see the
100 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
101 section in the Yocto Project Development Manual.
102 </para>
103
104 <para>
105 It's useful to have some idea of how the tasks defined by this class work
106 and what they do behind the scenes.
107 <itemizedlist>
108 <listitem><para><filename>do_configure</filename> &dash; Regenerates the
109 configure script (using <filename>autoreconf</filename>) and then launches it
110 with a standard set of arguments used during cross-compilation.
111 You can pass additional parameters to <filename>configure</filename> through the
112 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
113 </para></listitem>
114 <listitem><para><filename>do_compile</filename> &dash; Runs <filename>make</filename> with
115 arguments that specify the compiler and linker.
116 You can pass additional arguments through
117 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
118 </para></listitem>
119 <listitem><para><filename>do_install</filename> &dash; Runs <filename>make install</filename>
120 and passes in
121 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
122 as <filename>DESTDIR</filename>.
123 </para></listitem>
124 </itemizedlist>
125 </para>
126
127 <note>
128 It is planned for future Yocto Project releases that by default, the
129 <filename>autotools</filename> class supports out-of-tree builds
130 (<link linkend='var-B'><filename>B</filename></link> !=
131 <link linkend='var-S'><filename>S</filename></link>).
132 If your recipes do not support out-of-tree builds, you should
133 have them inherit the
134 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
135 class.
136 </note>
137</section>
138
139<section id='ref-classes-autotools-brokensep'>
140 <title><filename>autotools-brokensep.bbclass</filename></title>
141
142 <para>
143 The <filename>autotools-brokensep</filename> class behaves the same
144 as the
145 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
146 class but builds with
147 <link linkend='var-B'><filename>B</filename></link> ==
148 <link linkend='var-S'><filename>S</filename></link>.
149 This method is useful when out-of-tree build support is either not
150 present or is broken.
151 <note>
152 It is recommended that out-of-tree support be fixed and used
153 if at all possible.
154 </note>
155 </para>
156</section>
157
158<section id='ref-classes-base'>
159 <title><filename>base.bbclass</filename></title>
160
161 <para>
162 The <filename>base</filename> class is special in that every
163 <filename>.bb</filename> file implicitly inherits the class.
164 This class contains definitions for standard basic
165 tasks such as fetching, unpacking, configuring (empty by default),
166 compiling (runs any <filename>Makefile</filename> present), installing
167 (empty by default) and packaging (empty by default).
168 These classes are often overridden or extended by other classes
169 such as the
170 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
171 class or the
172 <link linkend='ref-classes-package'><filename>package</filename></link>
173 class.
174 The class also contains some commonly used functions such as
175 <filename>oe_runmake</filename>.
176 </para>
177</section>
178
179<section id='ref-classes-bin-package'>
180 <title><filename>bin_package.bbclass</filename></title>
181
182 <para>
183 The <filename>bin_package</filename> class is a
184 helper class for recipes that extract the contents of a binary package
185 (e.g. an RPM) and install those contents rather than building the
186 binary from source.
187 The binary package is extracted and new packages in the configured
188 output package format are created.
189 <note>
190 For RPMs and other packages that do not contain a subdirectory,
191 you should specify a "subdir" parameter.
192 Here is an example where <filename>${BP}</filename> is used so that
193 the files are extracted into the subdirectory expected by the
194 default value of
195 <link linkend='var-S'><filename>S</filename></link>:
196 <literallayout class='monospaced'>
197 SRC_URI = "http://example.com/downloads/somepackage.rpm;subdir=${BP}"
198 </literallayout>
199 </note>
200 </para>
201</section>
202
203<section id='ref-classes-binconfig'>
204 <title><filename>binconfig.bbclass</filename></title>
205
206 <para>
207 The <filename>binconfig</filename> class helps to correct paths in
208 shell scripts.
209 </para>
210
211 <para>
212 Before <filename>pkg-config</filename> had become widespread, libraries
213 shipped shell scripts to give information about the libraries and
214 include paths needed to build software (usually named
215 <filename>LIBNAME-config</filename>).
216 This class assists any recipe using such scripts.
217 </para>
218
219 <para>
220 During staging, the OpenEmbedded build system installs such scripts
221 into the <filename>sysroots/</filename> directory.
222 Inheriting this class results in all paths in these scripts being
223 changed to point into the <filename>sysroots/</filename> directory so
224 that all builds that use the script use the correct directories
225 for the cross compiling layout.
226 See the
227 <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link>
228 variable for more information.
229 </para>
230</section>
231
232<section id='ref-classes-blacklist'>
233 <title><filename>blacklist.bbclass</filename></title>
234
235 <para>
236 The <filename>blacklist</filename> class prevents
237 the OpenEmbedded build system from building specific recipes
238 (blacklists them).
239 To use this class, inherit the class globally and set
240 <link linkend='var-PNBLACKLIST'><filename>PNBLACKLIST</filename></link>
241 for each recipe you wish to blacklist.
242 Specify the <link linkend='var-PN'><filename>PN</filename></link>
243 value as a variable flag (varflag) and provide a reason, which is
244 reported, if the package is requested to be built as the value.
245 For example, if you want to blacklist a recipe called "exoticware",
246 you add the following to your <filename>local.conf</filename>
247 or distribution configuration:
248 <literallayout class='monospaced'>
249 INHERIT += "blacklist"
250 PNBLACKLIST[exoticware] = "Not supported by our organization."
251 </literallayout>
252 </para>
253</section>
254
255<section id='ref-classes-boot-directdisk'>
256 <title><filename>boot-directdisk.bbclass</filename></title>
257
258 <para>
259 The <filename>boot-directdisk</filename> class
260 creates an image that can be placed directly onto a hard disk using
261 <filename>dd</filename> and then booted.
262 The image uses SYSLINUX.
263 </para>
264
265 <para>
266 The end result is a 512 boot sector populated with a
267 Master Boot Record (MBR) and partition table followed by an MSDOS
268 FAT16 partition containing SYSLINUX and a Linux kernel completed by
269 the <filename>ext2</filename> and <filename>ext3</filename>
270 root filesystems.
271 </para>
272</section>
273
274<section id='ref-classes-bootimg'>
275 <title><filename>bootimg.bbclass</filename></title>
276
277 <para>
278 The <filename>bootimg</filename> class creates a bootable
279 image using SYSLINUX, your kernel, and an optional initial RAM disk
280 (<filename>initrd</filename>).
281 </para>
282
283 <para>
284 When you use this class, two things happen:
285 <itemizedlist>
286 <listitem><para>
287 A <filename>.hddimg</filename> file is created.
288 This file is an MSDOS filesystem that contains SYSLINUX,
289 a kernel, an <filename>initrd</filename>, and a root filesystem
290 image.
291 All three of these can be written to hard drives directly and
292 also booted on a USB flash disks using <filename>dd</filename>.
293 </para></listitem>
294 <listitem><para>
295 A CD <filename>.iso</filename> image is created.
296 When this file is booted, the <filename>initrd</filename>
297 boots and processes the label selected in SYSLINUX.
298 Actions based on the label are then performed (e.g. installing
299 to a hard drive).</para></listitem>
300 </itemizedlist>
301 </para>
302
303 <para>
304 The <filename>bootimg</filename> class supports the
305 <link linkend='var-INITRD'><filename>INITRD</filename></link>,
306 <link linkend='var-NOISO'><filename>NOISO</filename></link>,
307 <link linkend='var-NOHDD'><filename>NOHDD</filename></link>, and
308 <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>
309 variables.
310 </para>
311</section>
312
313<section id='ref-classes-bugzilla'>
314 <title><filename>bugzilla.bbclass</filename></title>
315
316 <para>
317 The <filename>bugzilla</filename> class supports setting up an
318 instance of Bugzilla in which you can automatically files bug reports
319 in response to build failures.
320 For this class to work, you need to enable the XML-RPC interface in
321 the instance of Bugzilla.
322 </para>
323</section>
324
325<section id='ref-classes-buildhistory'>
326 <title><filename>buildhistory.bbclass</filename></title>
327
328 <para>
329 The <filename>buildhistory</filename> class records a
330 history of build output metadata, which can be used to detect possible
331 regressions as well as used for analysis of the build output.
332 For more information on using Build History, see the
333 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
334 section.
335 </para>
336</section>
337
338<section id='ref-classes-buildstats'>
339 <title><filename>buildstats.bbclass</filename></title>
340
341 <para>
342 The <filename>buildstats</filename> class records
343 performance statistics about each task executed during the build
344 (e.g. elapsed time, CPU usage, and I/O usage).
345 </para>
346
347 <para>
348 When you use this class, the output goes into the
349 <link linkend='var-BUILDSTATS_BASE'><filename>BUILDSTATS_BASE</filename></link>
350 directory, which defaults to <filename>${TMPDIR}/buildstats/</filename>.
351 You can analyze the elapsed time using
352 <filename>scripts/pybootchartgui/pybootchartgui.py</filename>, which
353 produces a cascading chart of the entire build process and can be
354 useful for highlighting bottlenecks.
355 </para>
356
357 <para>
358 Collecting build statistics is enabled by default through the
359 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
360 variable from your <filename>local.conf</filename> file.
361 Consequently, you do not have to do anything to enable the class.
362 However, if you want to disable the class, simply remove "buildstats"
363 from the <filename>USER_CLASSES</filename> list.
364 </para>
365</section>
366
367<section id='ref-classes-ccache'>
368 <title><filename>ccache.bbclass</filename></title>
369
370 <para>
371 The <filename>ccache</filename> class enables the
372 <ulink url='http://ccache.samba.org/'>C/C++ Compiler Cache</ulink>
373 for the build.
374 This class is used to give a minor performance boost during the build.
375 However, using the class can lead to unexpected side-effects.
376 Thus, it is recommended that you do not use this class.
377 See <ulink url='http://ccache.samba.org/'></ulink> for information on
378 the C/C++ Compiler Cache.
379 </para>
380</section>
381
382<section id='ref-classes-chrpath'>
383 <title><filename>chrpath.bbclass</filename></title>
384
385 <para>
386 The <filename>chrpath</filename> class
387 is a wrapper around the "chrpath" utility, which is used during the
388 build process for <filename>nativesdk</filename>,
389 <filename>cross</filename>, and
390 <filename>cross-canadian</filename> recipes to change
391 <filename>RPATH</filename> records within binaries in order to make
392 them relocatable.
393 </para>
394</section>
395
396<section id='ref-classes-clutter'>
397 <title><filename>clutter.bbclass</filename></title>
398
399 <para>
400 The <filename>clutter</filename> class consolidates the
401 major and minor version naming and other common items used by Clutter
402 and related recipes.
403 <note>
404 Unlike some other classes related to specific libraries, recipes
405 building other software that uses Clutter do not need to
406 inherit this class unless they use the same recipe versioning
407 scheme that the Clutter and related recipes do.
408 </note>
409 </para>
410</section>
411
412<section id='ref-classes-cmake'>
413 <title><filename>cmake.bbclass</filename></title>
414
415 <para>
416 The <filename>cmake</filename> class allows for
417 recipes that need to build software using the CMake build system.
418 You can use the
419 <link linkend='var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></link>
420 variable to specify additional configuration options to be passed on
421 the <filename>cmake</filename> command line.
422 </para>
423</section>
424
425<section id='ref-classes-cml1'>
426 <title><filename>cml1.bbclass</filename></title>
427
428 <para>
429 The <filename>cml1</filename> class provides basic support for the
430 Linux kernel style build configuration system.
431 </para>
432</section>
433
434<section id='ref-classes-copyleft_compliance'>
435 <title><filename>copyleft_compliance.bbclass</filename></title>
436
437 <para>
438 The <filename>copyleft_compliance</filename> class
439 preserves source code for the purposes of license compliance.
440 This class is an alternative to the <filename>archiver</filename>
441 class and is still used by some users even though it has been
442 deprecated in favor of the
443 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
444 class.
445 </para>
446</section>
447
448<section id='ref-classes-core-image'>
449 <title><filename>core-image.bbclass</filename></title>
450
451 <para>
452 The <filename>core-image</filename> class
453 provides common definitions for the
454 <filename>core-image-*</filename> image recipes, such as support for
455 additional
456 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
457 </para>
458</section>
459
460<section id='ref-classes-cpan'>
461 <title><filename>cpan.bbclass</filename></title>
462
463 <para>
464 The <filename>cpan</filename> class supports Perl modules.
465 </para>
466
467 <para>
468 Recipes for Perl modules are simple.
469 These recipes usually only need to point to the source's archive and
470 then inherit the proper class file.
471 Building is split into two methods depending on which method the module
472 authors used.
473 <itemizedlist>
474 <listitem><para>Modules that use old
475 <filename>Makefile.PL</filename>-based build system require
476 <filename>cpan.bbclass</filename> in their recipes.
477 </para></listitem>
478 <listitem><para>Modules that use
479 <filename>Build.PL</filename>-based build system require
480 using <filename>cpan_build.bbclass</filename> in their recipes.
481 </para></listitem>
482 </itemizedlist>
483 </para>
484</section>
485
486<section id='ref-classes-cross'>
487 <title><filename>cross.bbclass</filename></title>
488
489 <para>
490 The <filename>cross</filename> class provides support for the recipes
491 that build the cross-compilation tools.
492 </para>
493</section>
494
495<section id='ref-classes-cross-canadian'>
496 <title><filename>cross-canadian.bbclass</filename></title>
497
498 <para>
499 The <filename>cross-canadian</filename> class
500 provides support for the recipes that build the Canadian
501 Cross-compilation tools for SDKs.
502 See the
503 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
504 section for more discussion on these cross-compilation tools.
505 </para>
506</section>
507
508<section id='ref-classes-crosssdk'>
509 <title><filename>crosssdk.bbclass</filename></title>
510
511 <para>
512 The <filename>crosssdk</filename> class
513 provides support for the recipes that build the cross-compilation
514 tools used for building SDKs.
515 See the
516 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
517 section for more discussion on these cross-compilation tools.
518 </para>
519</section>
520
521<section id='ref-classes-debian'>
522 <title><filename>debian.bbclass</filename></title>
523
524 <para>
525 The <filename>debian</filename> class renames output packages so that
526 they follow the Debian naming policy (i.e. <filename>eglibc</filename>
527 becomes <filename>libc6</filename> and <filename>eglibc-devel</filename>
528 becomes <filename>libc6-dev</filename>.)
529 Renaming includes the library name and version as part of the package
530 name.
531 </para>
532
533 <para>
534 If a recipe creates packages for multiple libraries
535 (shared object files of <filename>.so</filename> type), use the
536 <link linkend='var-LEAD_SONAME'><filename>LEAD_SONAME</filename></link>
537 variable in the recipe to specify the library on which to apply the
538 naming scheme.
539 </para>
540</section>
541
542<section id='ref-classes-deploy'>
543 <title><filename>deploy.bbclass</filename></title>
544
545 <para>
546 The <filename>deploy</filename> class handles deploying files
547 to the
548 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
549 directory.
550 The main function of this class is to allow the deploy step to be
551 accelerated by shared state.
552 Recipes that inherit this class should define their own
553 <filename>do_deploy</filename> function to copy the files to be
554 deployed to
555 <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>,
556 and use <filename>addtask</filename> to add the task at the appropriate
557 place, which is usually after <filename>do_compile</filename> or
558 <filename>do_install</filename>.
559 The class then takes care of staging the files from
560 <filename>DEPLOYDIR</filename> to
561 <filename>DEPLOY_DIR_IMAGE</filename>.
562 </para>
563</section>
564
565<section id='ref-classes-devshell'>
566 <title><filename>devshell.bbclass</filename></title>
567
568 <para>
569 The <filename>devshell</filename> class adds the
570 <filename>devshell</filename> task.
571 Distribution policy dictates whether to include this class.
572 See the
573 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
574 in the Yocto Project Development Manual for more information about
575 using <filename>devshell</filename>.
576 </para>
577</section>
578
579<section id='ref-classes-distro_features_check'>
580 <title><filename>distro_features_check.bbclass</filename></title>
581
582 <para>
583 The <filename>distro_features_check</filename> class
584 allows individual recipes to check for required and conflicting
585 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
586 </para>
587
588 <para>
589 This class provides support for the
590 <link linkend='var-REQUIRED_DISTRO_FEATURES'><filename>REQUIRED_DISTRO_FEATURES</filename></link>
591 and
592 <link linkend='var-CONFLICT_DISTRO_FEATURES'><filename>CONFLICT_DISTRO_FEATURES</filename></link>
593 variables.
594 If any conditions specified in the recipe using the above variables are
595 not met, the recipe will be skipped.
596 </para>
597</section>
598
599<section id='ref-classes-distrodata'>
600 <title><filename>distrodata.bbclass</filename></title>
601
602 <para>
603 The <filename>distrodata</filename> class
604 provides for automatic checking for upstream recipe updates.
605 The class creates a comma-separated value (CSV) spreadsheet that
606 contains information about the recipes.
607 The information provides the <filename>distrodata</filename> and
608 <filename>distro_check</filename> tasks, which do upstream checking
609 and also verify if a package is used in multiple major distributions.
610 </para>
611
612 <para>
613 The class is not included by default.
614 To use it, you must include the following files and set the
615 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
616 variable:
617 <literallayout class='monospaced'>
618 include conf/distro/include/distro_alias.inc
619 include conf/distro/include/recipe_color.inc
620 include conf/distro/include/maintainers.inc
621 include conf/distro/include/upstream_tracking.inc
622 include conf/distro/include/package_regex.inc
623 INHERIT+= "distrodata"
624 </literallayout>
625 </para>
626</section>
627
628<section id='ref-classes-distutils'>
629 <title><filename>distutils.bbclass</filename></title>
630
631 <para>
632 The <filename>distutils</filename> class supports recipes for Python
633 version 2.x extensions, which are simple.
634 These recipes usually only need to point to the source's archive and
635 then inherit the proper class.
636 Building is split into two methods depending on which method the
637 module authors used.
638 <itemizedlist>
639 <listitem><para>Extensions that use an Autotools-based build system
640 require Autotools and
641 <filename>distutils</filename>-based classes in their recipes.
642 </para></listitem>
643 <listitem><para>Extensions that use build systems based on
644 <filename>distutils</filename> require
645 the <filename>distutils</filename> class in their recipes.
646 </para></listitem>
647 <listitem><para>Extensions that use build systems based on
648 <filename>setuptools</filename> require the
649 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
650 class in their recipes.
651 </para></listitem>
652 </itemizedlist>
653 </para>
654</section>
655
656<section id='ref-classes-distutils3'>
657 <title><filename>distutils3.bbclass</filename></title>
658
659 <para>
660 The <filename>distutils3</filename> class supports recipes for Python
661 version 3.x extensions, which are simple.
662 These recipes usually only need to point to the source's archive and
663 then inherit the proper class.
664 Building is split into two methods depending on which method the
665 module authors used.
666 <itemizedlist>
667 <listitem><para>Extensions that use an Autotools-based build system
668 require Autotools and
669 <filename>distutils</filename>-based classes in their recipes.
670 </para></listitem>
671 <listitem><para>Extensions that use
672 <filename>distutils</filename>-based build systems require
673 the <filename>distutils</filename> class in their recipes.
674 </para></listitem>
675 <listitem><para>Extensions that use build systems based on
676 <filename>setuptools3</filename> require the
677 <link linkend='ref-classes-setuptools'><filename>setuptools3</filename></link>
678 class in their recipes.
679 </para></listitem>
680 </itemizedlist>
681 </para>
682</section>
683
684<section id='ref-classes-externalsrc'>
685 <title><filename>externalsrc.bbclass</filename></title>
686
687 <para>
688 The <filename>externalsrc</filename> class supports building software
689 from source code that is external to the OpenEmbedded build system.
690 Building software from an external source tree means that the build
691 system's normal fetch, unpack, and patch process is not used.
692 </para>
693
694 <para>
695 By default, the OpenEmbedded build system uses the
696 <link linkend='var-S'><filename>S</filename></link> and
697 <link linkend='var-B'><filename>B</filename></link> variables to
698 locate unpacked recipe source code and to build it, respectively.
699 When your recipe inherits the <filename>externalsrc</filename> class,
700 you use the
701 <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
702 and
703 <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
704 variables to ultimately define <filename>S</filename> and
705 <filename>B</filename>.
706 </para>
707
708 <para>
709 By default, this class expects the source code to support recipe builds
710 that use the <link linkend='var-B'><filename>B</filename></link>
711 variable to point to the directory in which the OpenEmbedded build
712 system places the generated objects built from the recipes.
713 By default, the <filename>B</filename> directory is set to the
714 following, which is separate from the source directory
715 (<filename>S</filename>):
716 <literallayout class='monospaced'>
717 ${WORKDIR}/${BPN}/{PV}/
718 </literallayout>
719 See these variables for more information:
720 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
721 <link linkend='var-BPN'><filename>BPN</filename></link>, and
722 <link linkend='var-PV'><filename>PV</filename></link>,
723 </para>
724
725 <para>
726 For more information on the
727 <filename>externalsrc</filename> class, see the comments in
728 <filename>meta/classes/externalsrc.bbclass</filename> in the
729 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
730 For information on how to use the <filename>externalsrc</filename>
731 class, see the
732 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
733 section in the Yocto Project Development Manual.
734 </para>
735</section>
736
737<section id='ref-classes-extrausers'>
738 <title><filename>extrausers.bbclass</filename></title>
739
740 <para>
741 The <filename>extrausers</filename> class allows
742 additional user and group configuration to be applied at the image
743 level.
744 Inheriting this class either globally or from an image recipe allows
745 additional user and group operations to be performed using the
746 <link linkend='var-EXTRA_USERS_PARAMS'><filename>EXTRA_USERS_PARAMS</filename></link>
747 variable.
748 <note>
749 The user and group operations added using the
750 <filename>extrausers</filename> class are not tied to a specific
751 recipe outside of the recipe for the image.
752 Thus, the operations can be performed across the image as a whole.
753 Use the
754 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
755 class to add user and group configuration to a specific recipe.
756 </note>
757 </para>
758
759 <para>
760 Here is an example that uses this class in an image recipe:
761 <literallayout class='monospaced'>
762 inherit extrausers
763 EXTRA_USERS_PARAMS = "\
764 useradd -p '' tester; \
765 groupadd developers; \
766 userdel nobody; \
767 groupdel -g video; \
768 groupmod -g 1020 developers; \
769 usermod -s /bin/sh tester; \
770 "
771 </literallayout>
772 </para>
773</section>
774
775<section id='ref-classes-fontcache'>
776 <title><filename>fontcache.bbclass</filename></title>
777
778 <para>
779 The <filename>fontcache</filename> class generates the
780 proper post-install and post-remove (postinst and postrm)
781 scriptlets for font packages.
782 These scriptlets call <filename>fc-cache</filename> (part of
783 <filename>Fontconfig</filename>) to add the fonts to the font
784 information cache.
785 Since the cache files are architecture-specific,
786 <filename>fc-cache</filename> runs using QEMU if the postinst
787 scriptlets need to be run on the build host during image creation.
788 </para>
789
790 <para>
791 If the fonts being installed are in packages other than the main
792 package, set
793 <link linkend='var-FONT_PACKAGES'><filename>FONT_PACKAGES</filename></link>
794 to specify the packages containing the fonts.
795 </para>
796</section>
797
798<section id='ref-classes-gconf'>
799 <title><filename>gconf.bbclass</filename></title>
800
801 <para>
802 The <filename>gconf</filename> class provides common
803 functionality for recipes that need to install GConf schemas.
804 The schemas will be put into a separate package
805 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-gconf</filename>)
806 that is created automatically when this class is inherited.
807 This package uses the appropriate post-install and post-remove
808 (postinst/postrm) scriptlets to register and unregister the schemas
809 in the target image.
810 </para>
811</section>
812
813<section id='ref-classes-gettext'>
814 <title><filename>gettext.bbclass</filename></title>
815
816 <para>
817 The <filename>gettext</filename> class provides support for
818 building software that uses the GNU <filename>gettext</filename>
819 internationalization and localization system.
820 All recipes building software that use
821 <filename>gettext</filename> should inherit this class.
822 </para>
823</section>
824
825<section id='ref-classes-gnome'>
826 <title><filename>gnome.bbclass</filename></title>
827
828 <para>
829 The <filename>gnome</filename> class supports recipes that
830 build software from the GNOME stack.
831 This class inherits the
832 <link linkend='ref-classes-gnomebase'><filename>gnomebase</filename></link>,
833 <link linkend='ref-classes-gtk-icon-cache'><filename>gtk-icon-cache</filename></link>,
834 <link linkend='ref-classes-gconf'><filename>gconf</filename></link> and
835 <link linkend='ref-classes-mime'><filename>mime</filename></link> classes.
836 The class also disables GObject introspection where applicable.
837 </para>
838</section>
839
840<section id='ref-classes-gnomebase'>
841 <title><filename>gnomebase.bbclass</filename></title>
842
843 <para>
844 The <filename>gnomebase</filename> class is the base
845 class for recipes that build software from the GNOME stack.
846 This class sets
847 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> to
848 download the source from the GNOME mirrors as well as extending
849 <link linkend='var-FILES'><filename>FILES</filename></link>
850 with the typical GNOME installation paths.
851 </para>
852</section>
853
854<section id='ref-classes-grub-efi'>
855 <title><filename>grub-efi.bbclass</filename></title>
856
857 <para>
858 The <filename>grub-efi</filename>
859 class provides <filename>grub-efi</filename>-specific functions for
860 building bootable images.
861 </para>
862
863 <para>
864 This class supports several variables:
865 <itemizedlist>
866 <listitem><para>
867 <link linkend='var-INITRD'><filename>INITRD</filename></link>:
868 Indicates a filesystem image to use as an initrd (optional).
869 </para></listitem>
870 <listitem><para>
871 <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
872 Indicates a filesystem image to include as the root filesystem
873 (optional).</para></listitem>
874 <listitem><para>
875 <link linkend='var-GRUB_GFXSERIAL'><filename>GRUB_GFXSERIAL</filename></link>:
876 Set this to "1" to have graphics and serial in the boot menu.
877 </para></listitem>
878 <listitem><para>
879 <link linkend='var-LABELS'><filename>LABELS</filename></link>:
880 A list of targets for the automatic configuration.
881 </para></listitem>
882 <listitem><para>
883 <link linkend='var-APPEND'><filename>APPEND</filename></link>:
884 An override list of append strings for each
885 <filename>LABEL</filename>.
886 </para></listitem>
887 <listitem><para>
888 <link linkend='var-GRUB_OPTS'><filename>GRUB_OPTS</filename></link>:
889 Additional options to add to the configuration (optional).
890 Options are delimited using semi-colon characters
891 (<filename>;</filename>).</para></listitem>
892 <listitem><para>
893 <link linkend='var-GRUB_TIMEOUT'><filename>GRUB_TIMEOUT</filename></link>:
894 Timeout before executing the default <filename>LABEL</filename>
895 (optional).
896 </para></listitem>
897 </itemizedlist>
898 </para>
899</section>
900
901<section id='ref-classes-gsettings'>
902 <title><filename>gsettings.bbclass</filename></title>
903
904 <para>
905 The <filename>gsettings</filename> class
906 provides common functionality for recipes that need to install
907 GSettings (glib) schemas.
908 The schemas are assumed to be part of the main package.
909 Appropriate post-install and post-remove (postinst/postrm)
910 scriptlets are added to register and unregister the schemas in the
911 target image.
912 </para>
913</section>
914
915<section id='ref-classes-gtk-doc'>
916 <title><filename>gtk-doc.bbclass</filename></title>
917
918 <para>
919 The <filename>gtk-doc</filename> class
920 is a helper class to pull in the appropriate
921 <filename>gtk-doc</filename> dependencies and disable
922 <filename>gtk-doc</filename>.
923 </para>
924</section>
925
926<section id='ref-classes-gtk-icon-cache'>
927 <title><filename>gtk-icon-cache.bbclass</filename></title>
928
929 <para>
930 The <filename>gtk-icon-cache</filename> class
931 generates the proper post-install and post-remove (postinst/postrm)
932 scriptlets for packages that use GTK+ and install icons.
933 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
934 the fonts to GTK+'s icon cache.
935 Since the cache files are architecture-specific,
936 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
937 postinst scriptlets need to be run on the build host during image
938 creation.
939 </para>
940</section>
941
942<section id='ref-classes-gtk-immodules-cache'>
943 <title><filename>gtk-immodules-cache.bbclass</filename></title>
944
945 <para>
946 The <filename>gtk-immodules-cache</filename> class
947 generates the proper post-install and post-remove (postinst/postrm)
948 scriptlets for packages that install GTK+ input method modules for
949 virtual keyboards.
950 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
951 the input method modules to the cache.
952 Since the cache files are architecture-specific,
953 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
954 postinst scriptlets need to be run on the build host during image
955 creation.
956 </para>
957
958 <para>
959 If the input method modules being installed are in packages other than
960 the main package, set
961 <link linkend='var-GTKIMMODULES_PACKAGES'><filename>GTKIMMODULES_PACKAGES</filename></link>
962 to specify the packages containing the modules.
963 </para>
964</section>
965
966<section id='ref-classes-gzipnative'>
967 <title><filename>gzipnative.bbclass</filename></title>
968
969 <para>
970 The <filename>gzipnative</filename>
971 class enables the use of native versions of <filename>gzip</filename>
972 and <filename>pigz</filename> rather than the versions of these tools
973 from the build host.
974 </para>
975</section>
976
977<section id='ref-classes-icecc'>
978 <title><filename>icecc.bbclass</filename></title>
979
980 <para>
981 The <filename>icecc</filename> class supports
982 <ulink url='https://github.com/icecc/icecream'>Icecream</ulink>, which
983 facilitates taking compile jobs and distributing them among remote
984 machines.
985 </para>
986
987 <para>
988 The class stages directories with symlinks from <filename>gcc</filename>
989 and <filename>g++</filename> to <filename>icecc</filename>, for both
990 native and cross compilers.
991 Depending on each configure or compile, the OpenEmbedded build system
992 adds the directories at the head of the <filename>PATH</filename> list
993 and then sets the <filename>ICECC_CXX</filename> and
994 <filename>ICEC_CC</filename> variables, which are the paths to the
995 <filename>g++</filename> and <filename>gcc</filename> compilers,
996 respectively.
997 </para>
998
999 <para>
1000 For the cross compiler, the class creates a <filename>tar.gz</filename>
1001 file that contains the Yocto Project toolchain and sets
1002 <filename>ICECC_VERSION</filename>, which is the version of the
1003 cross-compiler used in the cross-development toolchain, accordingly.
1004 </para>
1005
1006 <para>
1007 The class handles all three different compile stages
1008 (i.e native ,cross-kernel and target) and creates the necessary
1009 environment <filename>tar.gz</filename> file to be used by the remote
1010 machines.
1011 The class also supports SDK generation.
1012 </para>
1013
1014 <para>
1015 If <link linkend='var-ICECC_PATH'><filename>ICECC_PATH</filename></link>
1016 is not set in your <filename>local.conf</filename> file, then the
1017 class tries to locate the <filename>icecc</filename> binary
1018 using <filename>which</filename>.
1019
1020 If
1021 <link linkend='var-ICECC_ENV_EXEC'><filename>ICECC_ENV_EXEC</filename></link>
1022 is set in your <filename>local.conf</filename> file, the variable should
1023 point to the <filename>icecc-create-env</filename> script
1024 provided by the user.
1025 If you do not point to a user-provided script, the build system
1026 uses the default script provided by the recipe
1027 <filename>icecc-create-env-native.bb</filename>.
1028 <note>
1029 This script is a modified version and not the one that comes with
1030 <filename>icecc</filename>.
1031 </note>
1032 </para>
1033
1034 <para>
1035 If you do not want the Icecream distributed compile support to apply
1036 to specific recipes or classes, you can effectively "blacklist" them
1037 by listing the recipes and classes using the
1038 <link linkend='var-ICECC_USER_PACKAGE_BL'><filename>ICECC_USER_PACKAGE_BL</filename></link>
1039 and
1040 <link linkend='var-ICECC_USER_CLASS_BL'><filename>ICECC_USER_CLASS_BL</filename></link>,
1041 variables, respectively, in your <filename>local.conf</filename> file.
1042 Doing so causes the OpenEmbedded build system to handle these
1043 compilations locally.
1044 </para>
1045
1046 <para>
1047 Additionally, you can list recipes using the
1048 <link linkend='var-ICECC_USER_PACKAGE_WL'><filename>ICECC_USER_PACKAGE_WL</filename></link>
1049 variable in your <filename>local.conf</filename> file to force
1050 <filename>icecc</filename> to be enabled for recipes using an empty
1051 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
1052 variable.
1053 </para>
1054
1055 <para>
1056 Inheriting the <filename>icecc</filename> class changes all sstate
1057 signatures.
1058 Consequently, if a development team has a dedicated build system
1059 that populates
1060 <link linkend='var-SSTATE_MIRRORS'><filename>STATE_MIRRORS</filename></link>
1061 and they want to reuse sstate from
1062 <filename>STATE_MIRRORS</filename>, then all developers and the
1063 build system need to either inherit the <filename>icecc</filename>
1064 class or nobody should.
1065 </para>
1066
1067 <para>
1068 At the distribution level, you can inherit the
1069 <filename>icecc</filename> class to be sure that all builders start
1070 with the same sstate signatures.
1071 After inheriting the class, you can then disable the feature by setting
1072 the
1073 <link linkend='var-ICECC_DISABLED'><filename>ICECC_DISABLED</filename></link>
1074 variable to "1" as follows:
1075 <literallayout class='monospaced'>
1076 INHERIT_DISTRO += "icecc"
1077 ICECC_DISABLED ??= "1"
1078 </literallayout>
1079 This practice makes sure everyone is using the same signatures but also
1080 requires individuals that do want to use Icecream to enable the feature
1081 individually as follows in your <filename>local.conf</filename> file:
1082 <literallayout class='monospaced'>
1083 ICECC_DISABLED = ""
1084 </literallayout>
1085 </para>
1086</section>
1087
1088<section id='ref-classes-image'>
1089 <title><filename>image.bbclass</filename></title>
1090
1091 <para>
1092 The <filename>image</filename> class helps support creating images
1093 in different formats.
1094 First, the root filesystem is created from packages using
1095 one of the <filename>rootfs*.bbclass</filename>
1096 files (depending on the package format used) and then one or more image
1097 files are created.
1098 <itemizedlist>
1099 <listitem><para>The
1100 <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
1101 variable controls the types of images to generate.
1102 </para></listitem>
1103 <listitem><para>The
1104 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
1105 variable controls the list of packages to install into the
1106 image.</para></listitem>
1107 </itemizedlist>
1108 For information on customizing images, see the
1109 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>"
1110 section in the Yocto Project Development Manual.
1111 For information on how images are created, see the
1112 "<link linkend='images-dev-environment'>Images</link>" section elsewhere
1113 in this manual.
1114 </para>
1115</section>
1116
1117<section id='ref-classes-image_types'>
1118 <title><filename>image_types.bbclass</filename></title>
1119
1120 <para>
1121 The <filename>image_types</filename> class defines all of
1122 the standard image output types that you can enable through the
1123 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1124 variable.
1125 You can use this class as a reference on how to add support for custom
1126 image output types.
1127 </para>
1128
1129 <para>
1130 By default, this class is enabled through the
1131 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
1132 variable in
1133 <link linkend='ref-classes-image'><filename>image.bbclass</filename></link>.
1134 If you define your own image types using a custom BitBake class and
1135 then use <filename>IMAGE_CLASSES</filename> to enable it, the custom
1136 class must either inherit <filename>image_types</filename> or
1137 <filename>image_types</filename> must also appear in
1138 <filename>IMAGE_CLASSES</filename>.
1139 </para>
1140</section>
1141
1142<section id='ref-classes-image_types_uboot'>
1143 <title><filename>image_types_uboot.bbclass</filename></title>
1144
1145 <para>
1146 The <filename>image_types_uboot</filename> class
1147 defines additional image types specifically for the U-Boot bootloader.
1148 </para>
1149</section>
1150
1151<section id='ref-classes-image-live'>
1152 <title><filename>image-live.bbclass</filename></title>
1153
1154 <para>
1155 The <filename>image-live</filename> class supports building "live"
1156 images.
1157 </para>
1158
1159 <para>
1160 Normally, you do not use this class directly.
1161 Instead, you add "live" to
1162 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
1163 For example, if you were building an ISO image, you would add "live"
1164 to <filename>IMAGE_FSTYPES</filename>, set the
1165 <link linkend='var-NOISO'><filename>NOISO</filename></link> variable to
1166 "0" and the build system would use the <filename>image-live</filename>
1167 class to build the ISO image.
1168 </para>
1169</section>
1170
1171<section id='ref-classes-image-mklibs'>
1172 <title><filename>image-mklibs.bbclass</filename></title>
1173
1174 <para>
1175 The <filename>image-mklibs</filename> class
1176 enables the use of the <filename>mklibs</filename> utility during the
1177 <filename>do_rootfs</filename> task, which optimizes the size of
1178 libraries contained in the image.
1179 </para>
1180
1181 <para>
1182 By default, the class is enabled in the
1183 <filename>local.conf.template</filename> using the
1184 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1185 variable as follows:
1186 <literallayout class='monospaced'>
1187 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1188 </literallayout>
1189 </para>
1190</section>
1191
1192<section id='ref-classes-image-prelink'>
1193 <title><filename>image-prelink.bbclass</filename></title>
1194
1195 <para>
1196 The <filename>image-prelink</filename> class
1197 enables the use of the <filename>prelink</filename> utility during
1198 the <filename>do_rootfs</filename> task, which optimizes the dynamic
1199 linking of shared libraries to reduce executable startup time.
1200 </para>
1201
1202 <para>
1203 By default, the class is enabled in the
1204 <filename>local.conf.template</filename> using the
1205 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1206 variable as follows:
1207 <literallayout class='monospaced'>
1208 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1209 </literallayout>
1210 </para>
1211</section>
1212
1213<section id='ref-classes-image-swab'>
1214 <title><filename>image-swab.bbclass</filename></title>
1215
1216 <para>
1217 The <filename>image-swab</filename> class enables the
1218 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/swabber'>Swabber</ulink>
1219 tool in order to detect and log accesses to the host system during
1220 the OpenEmbedded build process.
1221 <note>
1222 This class is currently unmaintained.
1223 </note>
1224 </para>
1225</section>
1226
1227<section id='ref-classes-image-vmdk'>
1228 <title><filename>image-vmdk.bbclass</filename></title>
1229
1230 <para>
1231 The <filename>image-vmdk</filename> class supports building VMware
1232 VMDK images.
1233 Normally, you do not use this class directly.
1234 Instead, you add "vmdk" to
1235 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
1236 </para>
1237</section>
1238
1239<section id='ref-classes-insane'>
1240 <title><filename>insane.bbclass</filename></title>
1241
1242 <para>
1243 The <filename>insane</filename> class adds a step to the package
1244 generation process so that output quality assurance checks are
1245 generated by the OpenEmbedded build system.
1246 A range of checks are performed that check the build's output
1247 for common problems that show up during runtime.
1248 Distribution policy usually dictates whether to include this class.
1249 </para>
1250
1251 <para>
1252 You can configure the sanity checks so that specific test failures
1253 either raise a warning or an error message.
1254 Typically, failures for new tests generate a warning.
1255 Subsequent failures for the same test would then generate an error
1256 message once the metadata is in a known and good condition.
1257 </para>
1258
1259 <para>
1260 Use the
1261 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
1262 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
1263 variables to control the behavior of
1264 these checks at the global level (i.e. in your custom distro
1265 configuration).
1266 However, to skip one or more checks in recipes, you should use
1267 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
1268 For example, to skip the check for symbolic link
1269 <filename>.so</filename> files in the main package of a recipe,
1270 add the following to the recipe.
1271 You need to realize that the package name override, in this example
1272 <filename>${PN}</filename>, must be used:
1273 <literallayout class='monospaced'>
1274 INSANE_SKIP_${PN} += "dev-so"
1275 </literallayout>
1276 Please keep in mind that the QA checks exist in order to detect real
1277 or potential problems in the packaged output.
1278 So exercise caution when disabling these checks.
1279 </para>
1280
1281 <para>
1282 The following list shows the tests you can list with the
1283 <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
1284 variables:
1285 <itemizedlist>
1286 <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
1287 Checks that produced binaries have not already been
1288 stripped prior to the build system extracting debug symbols.
1289 It is common for upstream software projects to default to
1290 stripping debug symbols for output binaries.
1291 In order for debugging to work on the target using
1292 <filename>-dbg</filename> packages, this stripping must be
1293 disabled.
1294 </para></listitem>
1295 <listitem><para><emphasis><filename>arch:</filename></emphasis>
1296 Checks the Executable and Linkable Format (ELF) type, bit size,
1297 and endianness of any binaries to ensure they match the target
1298 architecture.
1299 This test fails if any binaries do not match the type since
1300 there would be an incompatibility.
1301 The test could indicate that the
1302 wrong compiler or compiler options have been used.
1303 Sometimes software, like bootloaders, might need to bypass
1304 this check.
1305 </para></listitem>
1306 <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
1307 Checks for paths to locations on the build host inside the
1308 output files.
1309 Currently, this test triggers too many false positives and
1310 thus is not normally enabled.
1311 </para></listitem>
1312 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
1313 Checks the <filename>do_compile</filename> log for indications
1314 that paths to locations on the build host were used.
1315 Using such paths might result in host contamination of the
1316 build output.
1317 </para></listitem>
1318 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
1319 Checks that <filename>-dbg</filename> packages only depend on other
1320 <filename>-dbg</filename> packages and not on any other types of packages,
1321 which would cause a packaging bug.</para></listitem>
1322 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
1323 Checks for <filename>.debug</filename> directories in anything but the
1324 <filename>-dbg</filename> package.
1325 The debug files should all be in the <filename>-dbg</filename> package.
1326 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
1327 <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
1328 Checks for invalid version comparison statements in runtime
1329 dependency relationships between packages (i.e. in
1330 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1331 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1332 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1333 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1334 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1335 and
1336 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
1337 variable values).
1338 Any invalid comparisons might trigger failures or undesirable
1339 behavior when passed to the package manager.
1340 </para></listitem>
1341 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
1342 Runs the <filename>desktop-file-validate</filename> program
1343 against any <filename>.desktop</filename> files to validate
1344 their contents against the specification for
1345 <filename>.desktop</filename> files.</para></listitem>
1346 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
1347 Checks that <filename>-dev</filename> packages only depend on other
1348 <filename>-dev</filename> packages and not on any other types of packages,
1349 which would be a packaging bug.</para></listitem>
1350 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
1351 Checks that the <filename>.so</filename> symbolic links are in the
1352 <filename>-dev</filename> package and not in any of the other packages.
1353 In general, these symlinks are only useful for development purposes.
1354 Thus, the <filename>-dev</filename> package is the correct location for
1355 them.
1356 Some very rare cases do exist for dynamically loaded modules where
1357 these symlinks are needed instead in the main package.
1358 </para></listitem>
1359 <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
1360 Checks for
1361 <link linkend='var-FILES'><filename>FILES</filename></link>
1362 variable values that contain "//", which is invalid.
1363 </para></listitem>
1364 <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
1365 Report when packages are excluded from being created due to
1366 being marked with a license that is in
1367 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
1368 </para></listitem>
1369 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
1370 Checks the <filename>do_install</filename> log for indications
1371 that paths to locations on the build host were used.
1372 Using such paths might result in host contamination of the
1373 build output.
1374 </para></listitem>
1375 <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
1376 Reports when files have been installed within
1377 <filename>do_install</filename> but have not been included in
1378 any package by way of the
1379 <link linkend='var-FILES'><filename>FILES</filename></link>
1380 variable.
1381 Files that do not appear in any package cannot be present in
1382 an image later on in the build process.
1383 Ideally, all installed files should be packaged or not
1384 installed at all.
1385 These files can be deleted at the end of
1386 <filename>do_install</filename> if the files are not
1387 needed in any package.
1388 </para></listitem>
1389 <listitem><para><emphasis><filename>la:</filename></emphasis>
1390 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
1391 paths.
1392 Any <filename>.la</filename> file containing these paths is incorrect since
1393 <filename>libtool</filename> adds the correct sysroot prefix when using the
1394 files automatically itself.</para></listitem>
1395 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
1396 Ensures that the binaries were linked with the
1397 <filename>LDFLAGS</filename> options provided by the build system.
1398 If this test fails, check that the <filename>LDFLAGS</filename> variable
1399 is being passed to the linker command.</para></listitem>
1400 <listitem><para><emphasis><filename>libdir:</filename></emphasis>
1401 Checks for libraries being installed into incorrect
1402 (possibly hardcoded) installation paths.
1403 For example, this test will catch recipes that install
1404 <filename>/lib/bar.so</filename> when
1405 <filename>${base_libdir}</filename> is "lib32".
1406 Another example is when recipes install
1407 <filename>/usr/lib64/foo.so</filename> when
1408 <filename>${libdir}</filename> is "/usr/lib".
1409 </para></listitem>
1410 <listitem><para><emphasis><filename>libexec:</filename></emphasis>
1411 Checks if a package contains files in
1412 <filename>/usr/libexec</filename>.
1413 This check is not performed if the
1414 <filename>libexecdir</filename> variable has been set
1415 explicitly to <filename>/usr/libexec</filename>.
1416 </para></listitem>
1417 <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
1418 Checks for the same package being listed multiple times through
1419 the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1420 variable value.
1421 Installing the package in this manner can cause errors during
1422 packaging.
1423 </para></listitem>
1424 <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
1425 Reports lines in <filename>fs-perms.txt</filename> that have
1426 an invalid format.
1427 </para></listitem>
1428 <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
1429 Reports lines in <filename>fs-perms.txt</filename> that have
1430 an invalid format.
1431 </para></listitem>
1432 <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
1433 Reports lines in <filename>fs-perms.txt</filename> that
1434 specify 'link' where the specified target already exists.
1435 </para></listitem>
1436 <listitem><para><emphasis><filename>perms:</filename></emphasis>
1437 Currently, this check is unused but reserved.
1438 </para></listitem>
1439 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
1440 Checks <filename>.pc</filename> files for any
1441 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
1442 paths.
1443 Any <filename>.pc</filename> file containing these paths is incorrect
1444 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
1445 when the files are accessed.</para></listitem>
1446 <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
1447 Checks that all packages in
1448 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1449 have names that do not contain invalid characters (i.e.
1450 characters other than 0-9, a-z, ., +, and -).
1451 </para></listitem>
1452 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
1453 Checks to see if the <filename>PKGV</filename> variable
1454 is undefined during <filename>do_package</filename>.
1455 </para></listitem>
1456 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
1457 Checks through the variables
1458 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1459 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1460 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1461 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
1462 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1463 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1464 <link linkend='var-FILES'><filename>FILES</filename></link>,
1465 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
1466 <filename>pkg_preinst</filename>,
1467 <filename>pkg_postinst</filename>,
1468 <filename>pkg_prerm</filename>
1469 and <filename>pkg_postrm</filename>, and reports if there are
1470 variable sets that are not package-specific.
1471 Using these variables without a package suffix is bad practice,
1472 and might unnecessarily complicate dependencies of other packages
1473 within the same recipe or have other unintended consequences.
1474 </para></listitem>
1475 <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
1476 Checks that a recipe does not have a name
1477 (<link linkend='var-PN'><filename>PN</filename></link>) value
1478 that appears in
1479 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
1480 If a recipe is named such that its <filename>PN</filename>
1481 value matches something already in
1482 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
1483 happens to be the same as
1484 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
1485 or
1486 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
1487 it can have unexpected consequences.
1488 For example, assignments such as
1489 <filename>FILES_${PN} = "xyz"</filename> effectively turn into
1490 <filename>FILES = "xyz"</filename>.
1491 </para></listitem>
1492 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
1493 Checks for rpaths in the binaries that contain build system paths such
1494 as <filename>TMPDIR</filename>.
1495 If this test fails, bad <filename>-rpath</filename> options are being
1496 passed to the linker commands and your binaries have potential security
1497 issues.</para></listitem>
1498 <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
1499 Reports that splitting or stripping debug symbols from binaries
1500 has failed.
1501 </para></listitem>
1502 <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
1503 Checks for static library files (<filename>*.a</filename>) in
1504 non-<filename>staticdev</filename> packages.
1505 </para></listitem>
1506 <listitem><para><emphasis><filename>symlink-to-sysroot:</filename></emphasis>
1507 Checks for symlinks in packages that point into
1508 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1509 on the host.
1510 Such symlinks will work on the host, but are clearly invalid
1511 when running on the target.
1512 </para></listitem>
1513 <listitem><para><emphasis><filename>textrel:</filename></emphasis>
1514 Checks for ELF binaries that contain relocations in their
1515 <filename>.text</filename> sections, which can result in a
1516 performance impact at runtime.</para></listitem>
1517 <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
1518 Reports when a binary installed in
1519 <filename>${base_libdir}</filename>,
1520 <filename>${base_bindir}</filename>, or
1521 <filename>${base_sbindir}</filename>, depends on another
1522 binary installed under <filename>${exec_prefix}</filename>.
1523 This dependency is a concern if you want the system to remain
1524 basically operable if <filename>/usr</filename> is mounted
1525 separately and is not mounted.
1526 <note>
1527 Defaults for binaries installed in
1528 <filename>${base_libdir}</filename>,
1529 <filename>${base_bindir}</filename>, and
1530 <filename>${base_sbindir}</filename> are
1531 <filename>/lib</filename>, <filename>/bin</filename>, and
1532 <filename>/sbin</filename>, respectively.
1533 The default for a binary installed
1534 under <filename>${exec_prefix}</filename> is
1535 <filename>/usr</filename>.
1536 </note>
1537 </para></listitem>
1538 <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis>
1539 Reports when a script file installed in
1540 <filename>${base_libdir}</filename>,
1541 <filename>${base_bindir}</filename>, or
1542 <filename>${base_sbindir}</filename>, depends on files
1543 installed under <filename>${exec_prefix}</filename>.
1544 This dependency is a concern if you want the system to remain
1545 basically operable if <filename>/usr</filename> is mounted
1546 separately and is not mounted.
1547 <note>
1548 Defaults for binaries installed in
1549 <filename>${base_libdir}</filename>,
1550 <filename>${base_bindir}</filename>, and
1551 <filename>${base_sbindir}</filename> are
1552 <filename>/lib</filename>, <filename>/bin</filename>, and
1553 <filename>/sbin</filename>, respectively.
1554 The default for a binary installed
1555 under <filename>${exec_prefix}</filename> is
1556 <filename>/usr</filename>.
1557 </note>
1558 </para></listitem>
1559 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
1560 Checks for dynamic library load paths (rpaths) in the binaries that
1561 by default on a standard system are searched by the linker (e.g.
1562 <filename>/lib</filename> and <filename>/usr/lib</filename>).
1563 While these paths will not cause any breakage, they do waste space and
1564 are unnecessary.</para></listitem>
1565 <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
1566 Reports when variables fundamental to packaging (i.e.
1567 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
1568 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
1569 <link linkend='var-D'><filename>D</filename></link>,
1570 <link linkend='var-PN'><filename>PN</filename></link>, and
1571 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
1572 undefined during <filename>do_package</filename>.
1573 </para></listitem>
1574 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
1575 If Build History is enabled, reports when a package
1576 being written out has a lower version than the previously
1577 written package under the same name.
1578 If you are placing output packages into a feed and
1579 upgrading packages on a target system using that feed, the
1580 version of a package going backwards can result in the target
1581 system not correctly upgrading to the "new" version of the
1582 package.
1583 <note>
1584 If you are not using runtime package management on your
1585 target system, then you do not need to worry about
1586 this situation.
1587 </note>
1588 </para></listitem>
1589 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
1590 Checks that all packages containing Xorg drivers have ABI
1591 dependencies.
1592 The <filename>xserver-xorg</filename> recipe provides driver
1593 ABI names.
1594 All drivers should depend on the ABI versions that they have
1595 been built against.
1596 Driver recipes that include
1597 <filename>xorg-driver-input.inc</filename>
1598 or <filename>xorg-driver-video.inc</filename> will
1599 automatically get these versions.
1600 Consequently, you should only need to explicitly add
1601 dependencies to binary driver recipes.
1602 </para></listitem>
1603 </itemizedlist>
1604 </para>
1605</section>
1606
1607<section id='ref-classes-insserv'>
1608 <title><filename>insserv.bbclass</filename></title>
1609
1610 <para>
1611 The <filename>insserv</filename> class
1612 uses the <filename>insserv</filename> utility to update the order of
1613 symbolic links in <filename>/etc/rc?.d/</filename> within an image
1614 based on dependencies specified by LSB headers in the
1615 <filename>init.d</filename> scripts themselves.
1616 </para>
1617</section>
1618
1619<section id='ref-classes-kernel'>
1620 <title><filename>kernel.bbclass</filename></title>
1621
1622 <para>
1623 The <filename>kernel</filename> class handles building Linux kernels.
1624 The class contains code to build all kernel trees.
1625 All needed headers are staged into the
1626 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
1627 directory to allow out-of-tree module builds using
1628 the
1629 <link linkend='ref-classes-module'><filename>module</filename></link>
1630 class.
1631 </para>
1632
1633 <para>
1634 This means that each built kernel module is packaged separately and inter-module
1635 dependencies are created by parsing the <filename>modinfo</filename> output.
1636 If all modules are required, then installing the <filename>kernel-modules</filename>
1637 package installs all packages with modules and various other kernel packages
1638 such as <filename>kernel-vmlinux</filename>.
1639 </para>
1640
1641 <para>
1642 Various other classes are used by the <filename>kernel</filename>
1643 and <filename>module</filename> classes internally including the
1644 <link linkend='ref-classes-kernel-arch'><filename>kernel-arch</filename></link>,
1645 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>,
1646 and
1647 <link linkend='ref-classes-linux-kernel-base'><filename>linux-kernel-base</filename></link>
1648 classes.
1649 </para>
1650</section>
1651
1652<section id='ref-classes-kernel-arch'>
1653 <title><filename>kernel-arch.bbclass</filename></title>
1654
1655 <para>
1656 The <filename>kernel-arch</filename> class
1657 sets the <filename>ARCH</filename> environment variable for Linux
1658 kernel compilation (including modules).
1659 </para>
1660</section>
1661
1662<section id='ref-classes-kernel-module-split'>
1663 <title><filename>kernel-module-split.bbclass</filename></title>
1664
1665 <para>
1666 The <filename>kernel-module-split</filename> class
1667 provides common functionality for splitting Linux kernel modules into
1668 separate packages.
1669 </para>
1670</section>
1671
1672<section id='ref-classes-kernel-yocto'>
1673 <title><filename>kernel-yocto.bbclass</filename></title>
1674
1675 <para>
1676 The <filename>kernel-yocto</filename> class
1677 provides common functionality for building from linux-yocto style
1678 kernel source repositories.
1679 </para>
1680</section>
1681
1682<section id='ref-classes-lib_package'>
1683 <title><filename>lib_package.bbclass</filename></title>
1684
1685 <para>
1686 The <filename>lib_package</filename> class
1687 supports recipes that build libraries and produce executable
1688 binaries, where those binaries should not be installed by default
1689 along with the library.
1690 Instead, the binaries are added to a separate
1691 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-bin</filename>
1692 package to make their installation optional.
1693 </para>
1694</section>
1695
1696<section id='ref-classes-license'>
1697 <title><filename>license.bbclass</filename></title>
1698
1699 <para>
1700 The <filename>license</filename> class provides license
1701 manifest creation and license exclusion.
1702 This class is enabled by default using the default value for the
1703 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
1704 variable.
1705 </para>
1706</section>
1707
1708<section id='ref-classes-linux-kernel-base'>
1709 <title><filename>linux-kernel-base.bbclass</filename></title>
1710
1711 <para>
1712 The <filename>linux-kernel-base</filename> class
1713 provides common functionality for recipes that build out of the Linux
1714 kernel source tree.
1715 These builds goes beyond the kernel itself.
1716 For example, the Perf recipe also inherits this class.
1717 </para>
1718</section>
1719
1720<section id='ref-classes-logging'>
1721 <title><filename>logging.bbclass</filename></title>
1722
1723 <para>
1724 The <filename>logging</filename> class provides the standard
1725 shell functions used to log messages for various BitBake severity levels
1726 (i.e. <filename>bbplain</filename>, <filename>bbnote</filename>,
1727 <filename>bbwarn</filename>, <filename>bberror</filename>,
1728 <filename>bbfatal</filename>, and <filename>bbdebug</filename>).
1729 </para>
1730
1731 <para>
1732 This class is enabled by default since it is inherited by
1733 the <filename>base</filename> class.
1734 </para>
1735</section>
1736
1737<section id='ref-classes-meta'>
1738 <title><filename>meta.bbclass</filename></title>
1739
1740 <para>
1741 The <filename>meta</filename> class is inherited by recipes
1742 that do not build any output packages themselves, but act as a "meta"
1743 target for building other recipes.
1744 </para>
1745</section>
1746
1747<section id='ref-classes-metadata_scm'>
1748 <title><filename>metadata_scm.bbclass</filename></title>
1749
1750 <para>
1751 The <filename>metadata_scm</filename> class provides functionality for
1752 querying the branch and revision of a Source Code Manager (SCM)
1753 repository.
1754 </para>
1755
1756 <para>
1757 The <link linkend='ref-classes-base'><filename>base</filename></link>
1758 class uses this class to print the revisions of each layer before
1759 starting every build.
1760 The <filename>metadata_scm</filename> class is enabled by default
1761 because it is inherited by the <filename>base</filename> class.
1762 </para>
1763</section>
1764
1765<section id='ref-classes-mime'>
1766 <title><filename>mime.bbclass</filename></title>
1767
1768 <para>
1769 The <filename>mime</filename> class generates the proper
1770 post-install and post-remove (postinst/postrm) scriptlets for packages
1771 that install MIME type files.
1772 These scriptlets call <filename>update-mime-database</filename> to add
1773 the MIME types to the shared database.
1774 </para>
1775</section>
1776
1777<section id='ref-classes-mirrors'>
1778 <title><filename>mirrors.bbclass</filename></title>
1779
1780 <para>
1781 The <filename>mirrors</filename> class sets up some standard
1782 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> entries
1783 for source code mirrors.
1784 These mirrors provide a fall-back path in case the upstream source
1785 specified in
1786 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
1787 within recipes is unavailable.
1788 </para>
1789
1790 <para>
1791 This class is enabled by default since it is inherited by the
1792 <link linkend='ref-classes-base'><filename>base</filename></link> class.
1793 </para>
1794</section>
1795
1796<section id='ref-classes-module'>
1797 <title><filename>module.bbclass</filename></title>
1798
1799 <para>
1800 The <filename>module</filename> class provides support for building
1801 out-of-tree Linux kernel modules.
1802 The class inherits the
1803 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>
1804 and
1805 <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link>
1806 classes, and implements <filename>do_compile</filename> and
1807 <filename>do_install</filename> functions.
1808 The class provides everything needed to build and package a kernel
1809 module.
1810 </para>
1811
1812 <para>
1813 For general information on out-of-tree Linux kernel modules, see the
1814 "<ulink url='&YOCTO_DOCS_KERNEL_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
1815 section in the Yocto Project Linux Kernel Development Manual.
1816 </para>
1817</section>
1818
1819<section id='ref-classes-module-base'>
1820 <title><filename>module-base.bbclass</filename></title>
1821
1822 <para>
1823 The <filename>module-base</filename> class provides the base
1824 functionality for building Linux kernel modules.
1825 Typically, a recipe that builds software that includes one or
1826 more kernel modules and has its own means of building
1827 the module inherits this class as opposed to inheriting the
1828 <link linkend='ref-classes-module'><filename>module</filename></link>
1829 class.
1830 </para>
1831</section>
1832
1833<section id='ref-classes-multilib*'>
1834 <title><filename>multilib*.bbclass</filename></title>
1835
1836 <para>
1837 The <filename>multilib*</filename> classes provide support
1838 for building libraries with different target optimizations or target
1839 architectures and installing them side-by-side in the same image.
1840 </para>
1841
1842 <para>
1843 For more information on using the Multilib feature, see the
1844 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
1845 section in the Yocto Project Development Manual.
1846 </para>
1847</section>
1848
1849<section id='ref-classes-native'>
1850 <title><filename>native.bbclass</filename></title>
1851
1852 <para>
1853 The <filename>native</filename> class provides common
1854 functionality for recipes that wish to build tools to run on the build
1855 host (i.e. tools that use the compiler or other tools from the
1856 build host).
1857 </para>
1858
1859 <para>
1860 You can create a recipe that builds tools that run natively on the
1861 host a couple different ways:
1862 <itemizedlist>
1863 <listitem><para>Create a <filename>myrecipe-native.bb</filename>
1864 that inherits the <filename>native</filename> class.
1865 If you use this method, you must order the inherit statement
1866 in the recipe after all other inherit statements so that the
1867 <filename>native</filename> class is inherited last.
1868 </para></listitem>
1869 <listitem><para>Create or modify a target recipe that has adds
1870 the following:
1871 <literallayout class='monospaced'>
1872 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "native"
1873 </literallayout>
1874 Inside the recipe, use <filename>_class-native</filename> and
1875 <filename>_class-target</filename> overrides to specify any
1876 functionality specific to the respective native or target
1877 case.</para></listitem>
1878 </itemizedlist>
1879 </para>
1880
1881 <para>
1882 Although applied differently, the <filename>native</filename> class is
1883 used with both methods.
1884 The advantage of the second method is that you do not need to have two
1885 separate recipes (assuming you need both) for native and target.
1886 All common parts of the recipe are automatically shared.
1887 </para>
1888</section>
1889
1890<section id='ref-classes-nativesdk'>
1891 <title><filename>nativesdk.bbclass</filename></title>
1892
1893 <para>
1894 The <filename>nativesdk</filename> class provides common
1895 functionality for recipes that wish to build tools to run as part of
1896 an SDK (i.e. tools that run on
1897 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>).
1898 </para>
1899
1900 <para>
1901 You can create a recipe that builds tools that run on the SDK machine
1902 a couple different ways:
1903 <itemizedlist>
1904 <listitem><para>Create a <filename>myrecipe-nativesdk.bb</filename>
1905 recipe that inherits the <filename>nativesdk</filename> class.
1906 If you use this method, you must order the inherit statement
1907 in the recipe after all other inherit statements so that the
1908 <filename>nativesdk</filename> class is inherited last.
1909 </para></listitem>
1910 <listitem><para>Create a <filename>nativesdk</filename> variant
1911 of any recipe by adding the following:
1912 <literallayout class='monospaced'>
1913 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "nativesdk"
1914 </literallayout>
1915 Inside the recipe, use <filename>_class-nativesdk</filename> and
1916 <filename>_class-target</filename> overrides to specify any
1917 functionality specific to the respective SDK machine or target
1918 case.</para></listitem>
1919 </itemizedlist>
1920 </para>
1921
1922 <para>
1923 Although applied differently, the <filename>nativesdk</filename> class
1924 is used with both methods.
1925 The advantage of the second method is that you do not need to have two
1926 separate recipes (assuming you need both) for the SDK machine and the
1927 target.
1928 All common parts of the recipe are automatically shared.
1929 </para>
1930</section>
1931
1932<section id='ref-classes-oelint'>
1933 <title><filename>oelint.bbclass</filename></title>
1934
1935 <para>
1936 The <filename>oelint</filename> class is an
1937 obsolete lint checking tool that exists in
1938 <filename>meta/classes</filename> in the
1939 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1940 </para>
1941
1942 <para>
1943 A number of classes exist that are could be generally useful in
1944 OE-Core but are never actually used within OE-Core itself.
1945 The <filename>oelint</filename> class is one such example.
1946 However, being aware of this class can reduce the proliferation of
1947 different versions of similar classes across multiple layers.
1948 </para>
1949</section>
1950
1951<section id='ref-classes-own-mirrors'>
1952 <title><filename>own-mirrors.bbclass</filename></title>
1953
1954 <para>
1955 The <filename>own-mirrors</filename> class makes it
1956 easier to set up your own
1957 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
1958 from which to first fetch source before attempting to fetch it from the
1959 upstream specified in
1960 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
1961 within each recipe.
1962 </para>
1963
1964 <para>
1965 To use this class, inherit it globally and specify
1966 <link linkend='var-SOURCE_MIRROR_URL'><filename>SOURCE_MIRROR_URL</filename></link>.
1967 Here is an example:
1968 <literallayout class='monospaced'>
1969 INHERIT += "own-mirrors"
1970 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1971 </literallayout>
1972 You can specify only a single URL in
1973 <filename>SOURCE_MIRROR_URL</filename>.
1974 </para>
1975</section>
1976
1977<section id='ref-classes-package'>
1978 <title><filename>package.bbclass</filename></title>
1979
1980 <para>
1981 The <filename>package</filename> class supports generating
1982 packages from a build's output.
1983 The core generic functionality is in
1984 <filename>package.bbclass</filename>.
1985 The code specific to particular package types resides in these
1986 package-specific classes:
1987 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
1988 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
1989 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
1990 and
1991 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>.
1992 </para>
1993
1994 <para>
1995 You can control the list of resulting package formats by using the
1996 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
1997 variable defined in your <filename>conf/local.conf</filename>
1998 configuration file, which is located in the
1999 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2000 When defining the variable, you can specify one or more package types.
2001 Since images are generated from packages, a packaging class is
2002 needed to enable image generation.
2003 The first class listed in this variable is used for image generation.
2004 </para>
2005
2006 <para>
2007 If you take the optional step to set up a repository (package feed)
2008 on the development host that can be used by Smart, you can
2009 install packages from the feed while you are running the image
2010 on the target (i.e. runtime installation of packages).
2011 For more information, see the
2012 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
2013 section in the Yocto Project Development Manual.
2014 </para>
2015
2016 <para>
2017 The package-specific class you choose can affect build-time performance
2018 and has space ramifications.
2019 In general, building a package with IPK takes about thirty percent less
2020 time as compared to using RPM to build the same or similar package.
2021 This comparison takes into account a complete build of the package with
2022 all dependencies previously built.
2023 The reason for this discrepancy is because the RPM package manager
2024 creates and processes more
2025 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the
2026 IPK package manager.
2027 Consequently, you might consider setting
2028 <filename>PACKAGE_CLASSES</filename> to "package_ipk" if you are
2029 building smaller systems.
2030 </para>
2031
2032 <para>
2033 Before making your package manager decision, however, you should
2034 consider some further things about using RPM:
2035 <itemizedlist>
2036 <listitem><para>
2037 RPM starts to provide more abilities than IPK due to
2038 the fact that it processes more Metadata.
2039 For example, this information includes individual file types,
2040 file checksum generation and evaluation on install, sparse file
2041 support, conflict detection and resolution for Multilib systems,
2042 ACID style upgrade, and repackaging abilities for rollbacks.
2043 </para></listitem>
2044 <listitem><para>
2045 For smaller systems, the extra space used for the Berkeley
2046 Database and the amount of metadata when using RPM can affect
2047 your ability to perform on-device upgrades.
2048 </para></listitem>
2049 </itemizedlist>
2050 </para>
2051
2052 <para>
2053 You can find additional information on the effects of the package
2054 class at these two Yocto Project mailing list links:
2055 <itemizedlist>
2056 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
2057 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
2058 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
2059 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
2060 </itemizedlist>
2061 </para>
2062</section>
2063
2064<section id='ref-classes-package_deb'>
2065 <title><filename>package_deb.bbclass</filename></title>
2066
2067 <para>
2068 The <filename>package_deb</filename> class
2069 provides support for creating packages that use the
2070 <filename>.deb</filename> file format.
2071 The class ensures the packages are written out to the
2072 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/deb</filename>
2073 directory in a <filename>.deb</filename> file format.
2074 </para>
2075
2076 <para>
2077 This class inherits the
2078 <link linkend='ref-classes-package'><filename>package</filename></link>
2079 class and is enabled through the
2080 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2081 variable in the <filename>local.conf</filename> file.
2082 </para>
2083</section>
2084
2085<section id='ref-classes-package_ipk'>
2086 <title><filename>package_ipk.bbclass</filename></title>
2087
2088 <para>
2089 The <filename>package_ipk</filename> class
2090 provides support for creating packages that use the
2091 <filename>.ipk</filename> file format.
2092 The class ensures the packages are written out to the
2093 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/ipk</filename>
2094 directory in a <filename>.ipk</filename> file format.
2095 </para>
2096
2097 <para>
2098 This class inherits the
2099 <link linkend='ref-classes-package'><filename>package</filename></link>
2100 class and is enabled through the
2101 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2102 variable in the <filename>local.conf</filename> file.
2103 </para>
2104</section>
2105
2106<section id='ref-classes-package_rpm'>
2107 <title><filename>package_rpm.bbclass</filename></title>
2108
2109 <para>
2110 The <filename>package_deb</filename> class
2111 provides support for creating packages that use the
2112 <filename>.rpm</filename> file format.
2113 The class ensures the packages are written out to the
2114 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/rpm</filename>
2115 directory in a <filename>.rpm</filename> file format.
2116 </para>
2117
2118 <para>
2119 This class inherits the
2120 <link linkend='ref-classes-package'><filename>package</filename></link>
2121 class and is enabled through the
2122 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2123 variable in the <filename>local.conf</filename> file.
2124 </para>
2125</section>
2126
2127<section id='ref-classes-package_tar'>
2128 <title><filename>package_tar.bbclass</filename></title>
2129
2130 <para>
2131 The <filename>package_tar</filename>
2132 class provides support for creating packages that use the
2133 <filename>.tar</filename> file format.
2134 The class ensures the packages are written out to the
2135 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/tar</filename>
2136 directory in a <filename>.tar</filename> file format.
2137 </para>
2138
2139 <para>
2140 This class inherits the
2141 <link linkend='ref-classes-package'><filename>package</filename></link>
2142 class and is enabled through the
2143 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2144 variable in the <filename>local.conf</filename> file.
2145 <note>
2146 You cannot specify the <filename>package_tar</filename> class
2147 first using the <filename>PACKAGE_CLASSES</filename> variable.
2148 You must use <filename>.deb</filename>,
2149 <filename>.ipk</filename>, or <filename>.rpm</filename> file
2150 formats for your image or SDK.
2151 </note>
2152 </para>
2153</section>
2154
2155<section id='ref-classes-packagedata'>
2156 <title><filename>packagedata.bbclass</filename></title>
2157
2158 <para>
2159 The <filename>packagedata</filename> class provides
2160 common functionality for reading <filename>pkgdata</filename> files
2161 found in
2162 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
2163 These files contain information about each output package produced by
2164 the OpenEmbedded build system.
2165 </para>
2166
2167 <para>
2168 This class is enabled by default because it is inherited by the
2169 <link linkend='ref-classes-package'><filename>package</filename></link>
2170 class.
2171 </para>
2172</section>
2173
2174<section id='ref-classes-packagegroup'>
2175 <title><filename>packagegroup.bbclass</filename></title>
2176
2177 <para>
2178 The <filename>packagegroup</filename> class sets default values
2179 appropriate for package group recipes (e.g.
2180 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
2181 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
2182 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
2183 and so forth).
2184 It is highly recommended that all package group recipes inherit this class.
2185 </para>
2186
2187 <para>
2188 For information on how to use this class, see the
2189 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
2190 section in the Yocto Project Development Manual.
2191 </para>
2192
2193 <para>
2194 Previously, this class was called the <filename>task</filename> class.
2195 </para>
2196</section>
2197
2198<section id='ref-classes-packageinfo'>
2199 <title><filename>packageinfo.bbclass</filename></title>
2200
2201 <para>
2202 The <filename>packageinfo</filename> class
2203 gives a BitBake user interface the ability to retrieve information
2204 about output packages from the <filename>pkgdata</filename> files.
2205 </para>
2206
2207 <para>
2208 This class is enabled automatically when using the
2209 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>
2210 user interface.
2211 </para>
2212</section>
2213
2214<section id='ref-classes-patch'>
2215 <title><filename>patch.bbclass</filename></title>
2216
2217 <para>
2218 The <filename>patch</filename> class provides all functionality for
2219 applying patches during the <filename>do_patch</filename> task.
2220 </para>
2221
2222 <para>
2223 This class is enabled by default because it is inherited by the
2224 <link linkend='ref-classes-base'><filename>base</filename></link>
2225 class.
2226 </para>
2227</section>
2228
2229<section id='ref-classes-perlnative'>
2230 <title><filename>perlnative.bbclass</filename></title>
2231
2232 <para>
2233 When inherited by a recipe, the <filename>perlnative</filename> class
2234 supports using the native version of Perl built by the build system
2235 rather than using the version provided by the build host.
2236 </para>
2237</section>
2238
2239<section id='ref-classes-pixbufcache'>
2240 <title><filename>pixbufcache.bbclass</filename></title>
2241
2242 <para>
2243 The <filename>pixbufcache</filename> class generates the proper
2244 post-install and post-remove (postinst/postrm) scriptlets for packages
2245 that install pixbuf loaders, which are used with
2246 <filename>gdk-pixbuf</filename>.
2247 These scriptlets call <filename>update_pixbuf_cache</filename>
2248 to add the pixbuf loaders to the cache.
2249 Since the cache files are architecture-specific,
2250 <filename>update_pixbuf_cache</filename> is run using QEMU if the
2251 postinst scriptlets need to be run on the build host during image
2252 creation.
2253 </para>
2254
2255 <para>
2256 If the pixbuf loaders being installed are in packages other
2257 than the recipe's main package, set
2258 <link linkend='var-PIXBUF_PACKAGES'><filename>PIXBUF_PACKAGES</filename></link>
2259 to specify the packages containing the loaders.
2260 </para>
2261</section>
2262
2263<section id='ref-classes-pkgconfig'>
2264 <title><filename>pkgconfig.bbclass</filename></title>
2265
2266 <para>
2267 The <filename>pkg-config</filename> class provides a standard way to get
2268 header and library information.
2269 This class aims to smooth integration of
2270 <filename>pkg-config</filename> into libraries that use it.
2271 </para>
2272
2273 <para>
2274 During staging, BitBake installs <filename>pkg-config</filename> data into the
2275 <filename>sysroots/</filename> directory.
2276 By making use of sysroot functionality within <filename>pkg-config</filename>,
2277 this class no longer has to manipulate the files.
2278 </para>
2279</section>
2280
2281<section id='ref-classes-populate-sdk'>
2282 <title><filename>populate_sdk.bbclass</filename></title>
2283
2284 <para>
2285 The <filename>populate_sdk</filename> class provides support for
2286 SDK-only recipes.
2287 For information on advantages gained when building a cross-development
2288 toolchain using the <filename>do_populate_sdk</filename> task, see the
2289 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
2290 section in the Yocto Project Application Developer's Guide.
2291 </para>
2292</section>
2293
2294<section id='ref-classes-populate-sdk-*'>
2295 <title><filename>populate_sdk_*.bbclass</filename></title>
2296
2297 <para>
2298 The <filename>populate_sdk_*</filename> classes support SDK creation
2299 and consist of the following classes:
2300 <itemizedlist>
2301 <listitem><para><emphasis><filename>populate_sdk_base</filename>:</emphasis>
2302 The base class supporting SDK creation under all package
2303 managers (i.e. DEB, RPM, and IPK).</para></listitem>
2304 <listitem><para><emphasis><filename>populate_sdk_deb</filename>:</emphasis>
2305 Supports creation of the SDK given the Debian package manager.
2306 </para></listitem>
2307 <listitem><para><emphasis><filename>populate_sdk_rpm</filename>:</emphasis>
2308 Supports creation of the SDK given the RPM package manager.
2309 </para></listitem>
2310 <listitem><para><emphasis><filename>populate_sdk_ipk</filename>:</emphasis>
2311 Supports creation of the SDK given the IPK package manager.
2312 </para></listitem>
2313 </itemizedlist>
2314 </para>
2315
2316 <para>
2317 The <filename>populate_sdk_base</filename> package inherits the
2318 appropriate <filename>populate_sdk_*</filename> (i.e.
2319 <filename>deb</filename>, <filename>rpm</filename>, and
2320 <filename>ipk</filename>) based on
2321 <link linkend='var-IMAGE_PKGTYPE'><filename>IMAGE_PKGTYPE</filename></link>.
2322 </para>
2323
2324 <para>
2325 The base class ensures all source and destination directories are
2326 established and then populates the SDK.
2327 After populating the SDK, the <filename>populate_sdk_base</filename>
2328 class constructs two images:
2329 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>-nativesdk</filename>,
2330 which contains the cross-compiler and associated tooling, and the
2331 target, which contains a target root filesystem that is configured for
2332 the SDK usage.
2333 These two images reside in
2334 <link linkend='var-SDK_OUTPUT'><filename>SDK_OUTPUT</filename></link>,
2335 which consists of the following:
2336 <literallayout class='monospaced'>
2337 ${SDK_OUTPUT}/&lt;sdk_arch-nativesdk pkgs&gt;
2338 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/&lt;target pkgs&gt;
2339 </literallayout>
2340 </para>
2341
2342 <para>
2343 Finally, the base populate SDK class creates the toolchain
2344 environment setup script, the tarball of the SDK, and the installer.
2345 </para>
2346
2347 <para>
2348 The respective <filename>populate_sdk_deb</filename>,
2349 <filename>populate_sdk_rpm</filename>, and
2350 <filename>populate_sdk_ipk</filename> classes each support the
2351 specific type of SDK.
2352 These classes are inherited by and used with the
2353 <filename>populate_sdk_base</filename> class.
2354 </para>
2355
2356 <para>
2357 For more information on the cross-development toolchain
2358 generation, see the
2359 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
2360 section.
2361 For information on advantages gained when building a
2362 cross-development toolchain using the
2363 <filename>do_populate_sdk</filename> task, see the
2364 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
2365 section in the Yocto Project Application Developer's Guide.
2366 </para>
2367</section>
2368
2369<section id='ref-classes-prexport'>
2370 <title><filename>prexport.bbclass</filename></title>
2371
2372 <para>
2373 The <filename>prexport</filename> class provides functionality for
2374 exporting
2375 <link linkend='var-PR'><filename>PR</filename></link> values.
2376 <note>
2377 This class is not intended to be used directly.
2378 Rather, it is enabled when using
2379 "<filename>bitbake-prserv-tool export</filename>".
2380 </note>
2381 </para>
2382</section>
2383
2384<section id='ref-classes-primport'>
2385 <title><filename>primport.bbclass</filename></title>
2386
2387 <para>
2388 The <filename>primport</filename> class provides functionality for
2389 importing
2390 <link linkend='var-PR'><filename>PR</filename></link> values.
2391 <note>
2392 This class is not intended to be used directly.
2393 Rather, it is enabled when using
2394 "<filename>bitbake-prserv-tool import</filename>".
2395 </note>
2396 </para>
2397</section>
2398
2399<section id='ref-classes-prserv'>
2400 <title><filename>prserv.bbclass</filename></title>
2401
2402 <para>
2403 The <filename>prserv</filename> class provides functionality for
2404 using a
2405 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>
2406 in order to automatically manage the incrementing of the
2407 <link linkend='var-PR'><filename>PR</filename></link> variable for
2408 each recipe.
2409 </para>
2410
2411 <para>
2412 This class is enabled by default because it is inherited by the
2413 <link linkend='ref-classes-package'><filename>package</filename></link>
2414 class.
2415 However, the OpenEmbedded build system will not enable the
2416 functionality of this class unless
2417 <link linkend='var-PRSERV_HOST'><filename>PRSERV_HOST</filename></link>
2418 has been set.
2419 </para>
2420</section>
2421
2422<section id='ref-classes-ptest'>
2423 <title><filename>ptest.bbclass</filename></title>
2424
2425 <para>
2426 The <filename>ptest</filename> class provides functionality for
2427 packaging and installing runtime tests for recipes that build software
2428 that provides these tests.
2429 </para>
2430
2431 <para>
2432 This class is intended to be inherited by individual recipes.
2433 However, the class' functionality is largely disabled unless "ptest"
2434 appears in
2435 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2436 See the
2437 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
2438 section in the Yocto Project Development Manual for more information
2439 on ptest.
2440 </para>
2441</section>
2442
2443<section id='ref-classes-python-dir'>
2444 <title><filename>python-dir.bbclass</filename></title>
2445
2446 <para>
2447 The <filename>python-dir</filename> class provides the base version,
2448 location, and site package location for Python.
2449 </para>
2450</section>
2451
2452<section id='ref-classes-pythonnative'>
2453 <title><filename>pythonnative.bbclass</filename></title>
2454
2455 <para>
2456 When inherited by a recipe, the <filename>pythonnative</filename> class
2457 supports using the native version of Python built by the build system
2458 rather than using the version provided by the build host.
2459 </para>
2460</section>
2461
2462<section id='ref-classes-qemu'>
2463 <title><filename>qemu.bbclass</filename></title>
2464
2465 <para>
2466 The <filename>qemu</filename> class provides functionality for recipes
2467 that either need QEMU or test for the existence of QEMU.
2468 Typically, this class is used to run programs for a target system on
2469 the build host using QEMU's application emulation mode.
2470 </para>
2471</section>
2472
2473<section id='ref-classes-qmake*'>
2474 <title><filename>qmake*.bbclass</filename></title>
2475
2476 <para>
2477 The <filename>qmake*</filename> classes support recipes that
2478 need to build software that uses Qt's <filename>qmake</filename>
2479 build system and are comprised of the following:
2480 <itemizedlist>
2481 <listitem><para><emphasis><filename>qmake_base</filename>:</emphasis>
2482 Provides base functionality for all versions of
2483 <filename>qmake</filename>.</para></listitem>
2484 <listitem><para><emphasis><filename>qmake2</filename>:</emphasis>
2485 Extends base functionality for <filename>qmake</filename> 2.x as
2486 used by Qt 4.x.</para></listitem>
2487 </itemizedlist>
2488 </para>
2489
2490 <para>
2491 If you need to set any configuration variables or pass any options to
2492 <filename>qmake</filename>, you can add these to the
2493 <link linkend='var-EXTRA_QMAKEVARS_PRE'><filename>EXTRA_QMAKEVARS_PRE</filename></link>
2494 or
2495 <link linkend='var-EXTRA_QMAKEVARS_POST'><filename>EXTRA_QMAKEVARS_POST</filename></link>
2496 variables, depending on whether the arguments need to be before or
2497 after the <filename>.pro</filename> file list on the command line,
2498 respectively.
2499 </para>
2500
2501 <para>
2502 By default, all <filename>.pro</filename> files are built.
2503 If you want to specify your own subset of <filename>.pro</filename>
2504 files to be built, specify them in the
2505 <link linkend='var-QMAKE_PROFILES'><filename>QMAKE_PROFILES</filename></link>
2506 variable.
2507 </para>
2508</section>
2509
2510<section id='ref-classes-qt4*'>
2511 <title><filename>qt4*.bbclass</filename></title>
2512
2513 <para>
2514 The <filename>qt4*</filename> classes support recipes that need to
2515 build software that uses the Qt development framework version 4.x
2516 and consist of the following:
2517 <itemizedlist>
2518 <listitem><para><emphasis><filename>qt4e</filename>:</emphasis>
2519 Supports building against Qt/Embedded, which uses the
2520 framebuffer for graphical output.</para></listitem>
2521 <listitem><para><emphasis><filename>qt4x11</filename>:</emphasis>
2522 Supports building against Qt/X11.</para></listitem>
2523 </itemizedlist>
2524 </para>
2525
2526 <para>
2527 The classes inherit the
2528 <link linkend='ref-classes-qmake*'><filename>qmake2</filename></link>
2529 class.
2530 </para>
2531</section>
2532
2533<section id='ref-classes-relocatable'>
2534 <title><filename>relocatable.bbclass</filename></title>
2535
2536 <para>
2537 The <filename>relocatable</filename> class enables relocation of
2538 binaries when they are installed into the sysroot.
2539 </para>
2540
2541 <para>
2542 This class makes use of the
2543 <link linkend='ref-classes-chrpath'><filename>chrpath</filename></link>
2544 class and is used by both the
2545 <link linkend='ref-classes-cross'><filename>cross</filename></link>
2546 and
2547 <link linkend='ref-classes-native'><filename>native</filename></link>
2548 classes.
2549 </para>
2550</section>
2551
2552<section id='ref-classes-report-error'>
2553 <title><filename>report-error.bbclass</filename></title>
2554
2555 <para>
2556 The <filename>report-error</filename> class supports enabling the
2557 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
2558 which allows you to submit build error information to a central
2559 database.
2560 </para>
2561
2562 <para>
2563 The class collects debug information for recipe, recipe version, task,
2564 machine, distro, build system, target system, host distro, branch,
2565 commit, and log.
2566 From the information, report files using a JSON format are created and
2567 stored in
2568 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
2569 </para>
2570</section>
2571
2572<section id='ref-classes-rm-work'>
2573 <title><filename>rm_work.bbclass</filename></title>
2574
2575 <para>
2576 The <filename>rm_work</filename> class supports deletion of temporary
2577 workspace, which can ease your hard drive demands during builds.
2578 </para>
2579
2580 <para>
2581 The OpenEmbedded build system can use a substantial amount of disk
2582 space during the build process.
2583 A portion of this space is the work files under the
2584 <filename>${TMPDIR}/work</filename> directory for each recipe.
2585 Once the build system generates the packages for a recipe, the work
2586 files for that recipe are no longer needed.
2587 However, by default, the build system preserves these files
2588 for inspection and possible debugging purposes.
2589 If you would rather have these files deleted to save disk space
2590 as the build progresses, you can enable <filename>rm_work</filename>
2591 by adding the following to your <filename>local.conf</filename> file,
2592 which is found in the
2593 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2594 <literallayout class='monospaced'>
2595 INHERIT += "rm_work"
2596 </literallayout>
2597 If you are modifying and building source code out of the work directory
2598 for a recipe, enabling <filename>rm_work</filename> will potentially
2599 result in your changes to the source being lost.
2600 To exclude some recipes from having their work directories deleted by
2601 <filename>rm_work</filename>, you can add the names of the recipe or
2602 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
2603 variable, which can also be set in your <filename>local.conf</filename>
2604 file.
2605 Here is an example:
2606 <literallayout class='monospaced'>
2607 RM_WORK_EXCLUDE += "busybox eglibc"
2608 </literallayout>
2609 </para>
2610</section>
2611
2612<section id='ref-classes-rootfs*'>
2613 <title><filename>rootfs*.bbclass</filename></title>
2614
2615 <para>
2616 The <filename>rootfs*</filename> classes support creating
2617 the root filesystem for an image and consist of the following classes:
2618 <itemizedlist>
2619 <listitem><para>
2620 The <filename>rootfs_deb</filename> class, which supports
2621 creation of root filesystems for images built using
2622 <filename>.deb</filename> packages.</para></listitem>
2623 <listitem><para>
2624 The <filename>rootfs_rpm</filename> class, which supports
2625 creation of root filesystems for images built using
2626 <filename>.rpm</filename> packages.</para></listitem>
2627 <listitem><para>
2628 The <filename>rootfs_ipk</filename> class, which supports
2629 creation of root filesystems for images built using
2630 <filename>.ipk</filename> packages.</para></listitem>
2631 </itemizedlist>
2632 </para>
2633
2634 <para>
2635 The root filesystem is created from packages using one of the
2636 <filename>rootfs*.bbclass</filename> files as determined by the
2637 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2638 variable.
2639 </para>
2640
2641 <para>
2642 For information on how root filesystem images are created, see the
2643 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
2644 section.
2645 </para>
2646</section>
2647
2648<section id='ref-classes-sanity'>
2649 <title><filename>sanity.bbclass</filename></title>
2650
2651 <para>
2652 The <filename>sanity</filename> class checks to see if prerequisite
2653 software is present on the host system so that users can be notified
2654 of potential problems that might affect their build.
2655 The class also performs basic user configuration checks from
2656 the <filename>local.conf</filename> configuration file to
2657 prevent common mistakes that cause build failures.
2658 Distribution policy usually determines whether to include this class.
2659 </para>
2660</section>
2661
2662<section id='ref-classes-scons'>
2663 <title><filename>scons.bbclass</filename></title>
2664
2665 <para>
2666 The <filename>scons</filename> class supports recipes that need to
2667 build software that uses the SCons build system.
2668 You can use the
2669 <link linkend='var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></link>
2670 variable to specify additional configuration options you want to pass
2671 SCons command line.
2672 </para>
2673</section>
2674
2675<section id='ref-classes-sdl'>
2676 <title><filename>sdl.bbclass</filename></title>
2677
2678 <para>
2679 The <filename>sdl</filename> class supports recipes that need to build
2680 software that uses the Simple DirectMedia Layer (SDL) library.
2681 </para>
2682</section>
2683
2684<section id='ref-classes-setuptools'>
2685 <title><filename>setuptools.bbclass</filename></title>
2686
2687 <para>
2688 The <filename>setuptools</filename> class supports Python
2689 version 2.x extensions that use build systems based on
2690 <filename>setuptools</filename>.
2691 If your recipe uses these build systems, the recipe needs to
2692 inherit the <filename>setuptools</filename> class.
2693 </para>
2694</section>
2695
2696<section id='ref-classes-setuptools3'>
2697 <title><filename>setuptools3.bbclass</filename></title>
2698
2699 <para>
2700 The <filename>setuptools3</filename> class supports Python
2701 version 3.x extensions that use build systems based on
2702 <filename>setuptools3</filename>.
2703 If your recipe uses these build systems, the recipe needs to
2704 inherit the <filename>setuptools3</filename> class.
2705 </para>
2706</section>
2707
2708<section id='ref-classes-sip'>
2709 <title><filename>sip.bbclass</filename></title>
2710
2711 <para>
2712 The <filename>sip</filename> class
2713 supports recipes that build or package SIP-based Python bindings.
2714 </para>
2715</section>
2716
2717<section id='ref-classes-siteconfig'>
2718 <title><filename>siteconfig.bbclass</filename></title>
2719
2720 <para>
2721 The <filename>siteconfig</filename> class
2722 provides functionality for handling site configuration.
2723 The class is used by the
2724 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2725 class to accelerate the <filename>do_configure</filename> task.
2726 </para>
2727</section>
2728
2729<section id='ref-classes-siteinfo'>
2730 <title><filename>siteinfo.bbclass</filename></title>
2731
2732 <para>
2733 The <filename>siteinfo</filename> class provides information about
2734 the targets that might be needed by other classes or recipes.
2735 </para>
2736
2737 <para>
2738 As an example, consider Autotools, which can require tests that must
2739 execute on the target hardware.
2740 Since this is not possible in general when cross compiling, site
2741 information is used to provide cached test results so these tests can
2742 be skipped over but still make the correct values available.
2743 The
2744 <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
2745 contains test results sorted into different categories such as
2746 architecture, endianness, and the <filename>libc</filename> used.
2747 Site information provides a list of files containing data relevant to
2748 the current build in the
2749 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
2750 that Autotools automatically picks up.
2751 </para>
2752
2753 <para>
2754 The class also provides variables like
2755 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
2756 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
2757 that can be used elsewhere in the metadata.
2758 </para>
2759
2760 <para>
2761 Because the
2762 <link linkend='ref-classes-base'><filename>base</filename></link> class
2763 includes the <filename>siteinfo</filename> class, it is always active.
2764 </para>
2765</section>
2766
2767<section id='ref-classes-spdx'>
2768 <title><filename>spdx.bbclass</filename></title>
2769
2770 <para>
2771 The <filename>spdx</filename> class integrates real-time license
2772 scanning, generation of SPDX standard output, and verification
2773 of license information during the build.
2774 <note>
2775 This class is currently at the prototype stage in the 1.5
2776 release.
2777 </note>
2778 </para>
2779</section>
2780
2781<section id='ref-classes-sstate'>
2782 <title><filename>sstate.bbclass</filename></title>
2783
2784 <para>
2785 The <filename>sstate</filename> class provides support for Shared
2786 State (sstate).
2787 By default, the class is enabled through the
2788 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
2789 variable's default value.
2790 </para>
2791
2792 <para>
2793 For more information on sstate, see the
2794 "<link linkend='shared-state-cache'>Shared State Cache</link>"
2795 section.
2796 </para>
2797</section>
2798
2799<section id='ref-classes-staging'>
2800 <title><filename>staging.bbclass</filename></title>
2801
2802 <para>
2803 The <filename>staging</filename> class provides support for staging
2804 files into the sysroot during the
2805 <filename>do_populate_sysroot</filename> task.
2806 The class is enabled by default because it is inherited by the
2807 <link linkend='ref-classes-base'><filename>base</filename></link>
2808 class.
2809 </para>
2810</section>
2811
2812<section id='ref-classes-syslinux'>
2813 <title><filename>syslinux.bbclass</filename></title>
2814
2815 <para>
2816 The <filename>syslinux</filename> class provides syslinux-specific
2817 functions for building bootable images.
2818 </para>
2819
2820 <para>
2821 The class supports the following variables:
2822 <itemizedlist>
2823 <listitem><para><emphasis><link linkend='var-INITRD'><filename>INITRD</filename></link>:</emphasis>
2824 Indicates a filesystem image to use as an initial RAM disk
2825 (initrd).
2826 This variable is optional.</para></listitem>
2827 <listitem><para><emphasis><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:</emphasis>
2828 Indicates a filesystem image to include as the root filesystem.
2829 This variable is optional.</para></listitem>
2830 <listitem><para><emphasis><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>:</emphasis>
2831 Enables creating an automatic menu when set to "1".
2832 </para></listitem>
2833 <listitem><para><emphasis><link linkend='var-LABELS'><filename>LABELS</filename></link>:</emphasis>
2834 Lists targets for automatic configuration.
2835 </para></listitem>
2836 <listitem><para><emphasis><link linkend='var-APPEND'><filename>APPEND</filename></link>:</emphasis>
2837 Lists append string overrides for each label.
2838 </para></listitem>
2839 <listitem><para><emphasis><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>:</emphasis>
2840 Lists additional options to add to the syslinux file.
2841 Semicolon characters separate multiple options.
2842 </para></listitem>
2843 <listitem><para><emphasis><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>:</emphasis>
2844 Lists a background for the VGA boot menu when you are using the
2845 boot menu.</para></listitem>
2846 <listitem><para><emphasis><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>:</emphasis>
2847 Set to "console=ttyX" to change kernel boot default console.
2848 </para></listitem>
2849 <listitem><para><emphasis><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>:</emphasis>
2850 Sets an alternate serial port.
2851 Or, turns off serial when the variable is set with an
2852 empty string.</para></listitem>
2853 <listitem><para><emphasis><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>:</emphasis>
2854 Sets an alternate "console=tty..." kernel boot argument.
2855 </para></listitem>
2856 </itemizedlist>
2857 </para>
2858</section>
2859
2860<section id='ref-classes-systemd'>
2861 <title><filename>systemd.bbclass</filename></title>
2862
2863 <para>
2864 The <filename>systemd</filename> class provides support for recipes
2865 that install systemd unit files.
2866 </para>
2867
2868 <para>
2869 The functionality for this class is disabled unless you have "systemd"
2870 in
2871 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2872 </para>
2873
2874 <para>
2875 Under this class, the recipe or Makefile (i.e. whatever the recipe is
2876 calling during the <filename>do_install</filename> task) installs unit
2877 files into
2878 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>.
2879 If the unit files being installed go into packages other than the
2880 main package, you need to set
2881 <link linkend='var-SYSTEMD_PACKAGES'><filename>SYSTEMD_PACKAGES</filename></link>
2882 in your recipe to identify the packages in which the files will be
2883 installed.
2884 </para>
2885
2886 <para>
2887 You should set
2888 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
2889 to the name of the service file.
2890 You should also use a package name override to indicate the package
2891 to which the value applies.
2892 If the value applies to the recipe's main package, use
2893 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>.
2894 Here is an example from the connman recipe:
2895 <literallayout class='monospaced'>
2896 SYSTEMD_SERVICE_${PN} = "connman.service"
2897 </literallayout>
2898 Services are set up to start on boot automatically unless
2899 you have set
2900 <link linkend='var-SYSTEMD_AUTO_ENABLE'><filename>SYSTEMD_AUTO_ENABLE</filename></link>
2901 to "disable".
2902 </para>
2903
2904 <para>
2905 For more information on <filename>systemd</filename>, see the
2906 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager'>Selecting an Initialization Manager</ulink>"
2907 section in the Yocto Project Development Manual.
2908 </para>
2909</section>
2910
2911<section id='ref-classes-terminal'>
2912 <title><filename>terminal.bbclass</filename></title>
2913
2914 <para>
2915 The <filename>terminal</filename> class provides support for starting
2916 a terminal session.
2917 The
2918 <link linkend='var-OE_TERMINAL'><filename>OE_TERMINAL</filename></link>
2919 variable controls which terminal emulator is used for the session.
2920 </para>
2921
2922 <para>
2923 Other classes use the <filename>terminal</filename> class anywhere a
2924 separate terminal session needs to be started.
2925 For example, the
2926 <link linkend='ref-classes-patch'><filename>patch</filename></link>
2927 class assuming
2928 <link linkend='var-PATCHRESOLVE'><filename>PATCHRESOLVE</filename></link>
2929 is set to "user", the
2930 <link linkend='ref-classes-cml1'><filename>cml1</filename></link>
2931 class, and the
2932 <link linkend='ref-classes-devshell'><filename>devshell</filename></link>
2933 class all use the <filename>terminal</filename> class.
2934 </para>
2935</section>
2936
2937<section id='ref-classes-testimage'>
2938 <title><filename>testimage.bbclass</filename></title>
2939
2940 <para>
2941 The <filename>testimage</filename> class supports running automated
2942 tests against images using QEMU and on actual hardware.
2943 The class handles loading the tests and starting the image.
2944 </para>
2945
2946 <para>
2947 To use the class, you need to perform steps to set up the
2948 environment.
2949 The tests are commands that run on the target system over
2950 <filename>ssh</filename>.
2951 they are written in Python and make use of the
2952 <filename>unittest</filename> module.
2953 </para>
2954
2955 <para>
2956 For information on how to enable, run, and create new tests, see the
2957 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
2958 section.
2959 </para>
2960</section>
2961
2962<section id='ref-classes-tinderclient'>
2963 <title><filename>tinderclient.bbclass</filename></title>
2964
2965 <para>
2966 The <filename>tinderclient</filename> class submits build results to
2967 an external Tinderbox instance.
2968 <note>
2969 This class is currently unmaintained.
2970 </note>
2971 </para>
2972</section>
2973
2974<section id='ref-classes-toaster'>
2975 <title><filename>toaster.bbclass</filename></title>
2976
2977 <para>
2978 The <filename>toaster</filename> class collects information about
2979 packages and images and sends them as events that the BitBake
2980 user interface can receive.
2981 The class is enabled when the Toaster user interface is running.
2982 </para>
2983
2984 <para>
2985 This class is not intended to be used directly.
2986 </para>
2987</section>
2988
2989<section id='ref-classes-toolchain-scripts'>
2990 <title><filename>toolchain-scripts.bbclass</filename></title>
2991
2992 <para>
2993 The <filename>toolchain-scripts</filename> class provides the scripts
2994 used for setting up the environment for installed SDKs.
2995 </para>
2996</section>
2997
2998<section id='ref-classes-typecheck'>
2999 <title><filename>typecheck.bbclass</filename></title>
3000
3001 <para>
3002 The <filename>typecheck</filename> class provides support for
3003 validating the values of variables set at the configuration level
3004 against their defined types.
3005 The OpenEmbedded build system allows you to define the type of a
3006 variable using the "type" varflag.
3007 Here is an example:
3008 <literallayout class='monospaced'>
3009 IMAGE_FEATURES[type] = "list"
3010 </literallayout>
3011 </para>
3012</section>
3013
3014<section id='ref-classes-uboot-config'>
3015 <title><filename>uboot-config.bbclass</filename></title>
3016
3017 <para>
3018 The <filename>uboot-config</filename> class provides support for
3019 U-Boot configuration for a machine.
3020 Specify the machine in your recipe as follows:
3021 <literallayout class='monospaced'>
3022 UBOOT_CONFIG ??= &lt;default&gt;
3023 UBOOT_CONFIG[foo] = "config,images"
3024 </literallayout>
3025 You can also specify the machine using this method:
3026 <literallayout class='monospaced'>
3027 UBOOT_MACHINE = "config"
3028 </literallayout>
3029 See the
3030 <link linkend='var-UBOOT_CONFIG'><filename>UBOOT_CONFIG</filename></link>
3031 and
3032 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
3033 variables for additional information.
3034 </para>
3035</section>
3036
3037<section id='ref-classes-update-alternatives'>
3038 <title><filename>update-alternatives.bbclass</filename></title>
3039
3040 <para>
3041 The <filename>update-alternatives</filename> class helps the
3042 alternatives system when multiple sources provide the same command.
3043 This situation occurs when several programs that have the same or
3044 similar function are installed with the same name.
3045 For example, the <filename>ar</filename> command is available from the
3046 <filename>busybox</filename>, <filename>binutils</filename> and
3047 <filename>elfutils</filename> packages.
3048 The <filename>update-alternatives</filename> class handles
3049 renaming the binaries so that multiple packages can be installed
3050 without conflicts.
3051 The <filename>ar</filename> command still works regardless of which
3052 packages are installed or subsequently removed.
3053 The class renames the conflicting binary in each package and symlinks
3054 the highest priority binary during installation or removal of packages.
3055 </para>
3056
3057 <para>
3058 To use this class, you need to define a number of variables:
3059 <itemizedlist>
3060 <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
3061 </para></listitem>
3062 <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
3063 </para></listitem>
3064 <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
3065 </para></listitem>
3066 <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
3067 </para></listitem>
3068 </itemizedlist>
3069 These variables list alternative commands needed by a package,
3070 provide pathnames for links, default links for targets, and
3071 so forth.
3072 For details on how to use this class, see the comments in the
3073 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>.
3074 </para>
3075
3076 <note>
3077 You can use the <filename>update-alternatives</filename> command
3078 directly in your recipes.
3079 However, this class simplifies things in most cases.
3080 </note>
3081</section>
3082
3083<section id='ref-classes-update-rc.d'>
3084 <title><filename>update-rc.d.bbclass</filename></title>
3085
3086 <para>
3087 The <filename>update-rc.d</filename> class uses
3088 <filename>update-rc.d</filename> to safely install an
3089 initialization script on behalf of the package.
3090 The OpenEmbedded build system takes care of details such as making
3091 sure the script is stopped before a package is removed and started when
3092 the package is installed.
3093 </para>
3094
3095 <para>
3096 Three variables control this class:
3097 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
3098 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
3099 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
3100 See the variable links for details.
3101 </para>
3102</section>
3103
3104<section id='ref-classes-useradd'>
3105 <title><filename>useradd.bbclass</filename></title>
3106
3107 <para>
3108 The <filename>useradd</filename> class supports the addition of users
3109 or groups for usage by the package on the target.
3110 For example, if you have packages that contain system services that
3111 should be run under their own user or group, you can use this class to
3112 enable creation of the user or group.
3113 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
3114 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3115 provides a simple example that shows how to add three
3116 users and groups to two packages.
3117 See the <filename>useradd-example.bb</filename> recipe for more
3118 information on how to use this class.
3119 </para>
3120
3121 <para>
3122 The <filename>useradd</filename> class supports the
3123 <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>,
3124 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
3125 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
3126 and
3127 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
3128 variables.
3129 </para>
3130</section>
3131
3132<section id='ref-classes-useradd-staticids'>
3133 <title><filename>useradd-staticids.bbclass</filename></title>
3134
3135 <para>
3136 The <filename>useradd-staticids</filename> class supports the addition
3137 of users or groups that have static user identification
3138 (<filename>uid</filename>) and group identification
3139 (<filename>gid</filename>) values.
3140 </para>
3141
3142 <para>
3143 The default behavior of the OpenEmbedded build system for assigning
3144 <filename>uid</filename> and <filename>gid</filename> values when
3145 packages add users and groups during package install time is to
3146 add them dynamically.
3147 This works fine for programs that do not care what the values of the
3148 resulting users and groups become.
3149 In these cases, the order of the installation determines the final
3150 <filename>uid</filename> and <filename>gid</filename> values.
3151 However, if non-deterministic
3152 <filename>uid</filename> and <filename>gid</filename> values are a
3153 problem, you can override the default, dynamic application of these
3154 values by setting static values.
3155 When you set static values, the OpenEmbedded build system looks in
3156 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
3157 <filename>files/passwd</filename> and <filename>files/group</filename>
3158 files for the values.
3159 </para>
3160
3161 <para>
3162 To use static <filename>uid</filename> and <filename>gid</filename>
3163 values, you need to set some variables.
3164 See the
3165 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
3166 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
3167 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>,
3168 and
3169 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
3170 variables.
3171 You can also see the
3172 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
3173 class for additional information.
3174 </para>
3175
3176 <note><title>Notes</title>
3177 You do not use this class directly.
3178 You either enable or disable the class by setting the
3179 <filename>USERADDEXTENSION</filename> variable.
3180 If you enable or disable the class in a configured system,
3181 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
3182 might contain incorrect <filename>uid</filename> and
3183 <filename>gid</filename> values.
3184 Deleting the <filename>TMPDIR</filename> directory
3185 will correct this condition.
3186 </note>
3187</section>
3188
3189<section id='ref-classes-utility-tasks'>
3190 <title><filename>utility-tasks.bbclass</filename></title>
3191
3192 <para>
3193 The <filename>utility-tasks</filename> class provides support for
3194 various "utility" type tasks that are applicable to all recipes,
3195 such as <filename>do_clean</filename> and
3196 <filename>do_listtasks</filename>.
3197 </para>
3198
3199 <para>
3200 This class is enabled by default because it is inherited by
3201 the
3202 <link linkend='ref-classes-base'><filename>base</filename></link>
3203 class.
3204 </para>
3205</section>
3206
3207<section id='ref-classes-utils'>
3208 <title><filename>utils.bbclass</filename></title>
3209
3210 <para>
3211 The <filename>utils</filename> class provides some useful Python
3212 functions that are typically used in inline Python expressions
3213 (e.g. <filename>${@...}</filename>).
3214 One example use is for <filename>base_contains()</filename>.
3215 </para>
3216
3217 <para>
3218 This class is enabled by default because it is inherited by the
3219 <link linkend='ref-classes-base'><filename>base</filename></link>
3220 class.
3221 </para>
3222</section>
3223
3224<section id='ref-classes-vala'>
3225 <title><filename>vala.bbclass</filename></title>
3226
3227 <para>
3228 The <filename>vala</filename> class supports recipes that need to
3229 build software written using the Vala programming language.
3230 </para>
3231</section>
3232
3233<section id='ref-classes-waf'>
3234 <title><filename>waf.bbclass</filename></title>
3235
3236 <para>
3237 The <filename>waf</filename> class supports recipes that need to build
3238 software that uses the Waf build system.
3239 You can use the
3240 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
3241 variable to specify additional configuration options to be passed on
3242 the Waf command line.
3243 </para>
3244</section>
3245
3246<!-- Undocumented classes are:
3247 image-empty.bbclass (possibly being dropped)
3248 migrate_localcount.bbclass (still need a description)
3249-->
3250
3251
3252</chapter>
3253<!--
3254vim: expandtab tw=80 ts=4
3255-->
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
new file mode 100644
index 0000000..f351931
--- /dev/null
+++ b/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,344 @@
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>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 poky
42 $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
43 </literallayout>
44 </para>
45
46 <section id='ref-features-machine'>
47 <title>Machine Features</title>
48
49 <para>
50 The items below are features you can use with
51 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_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 feature list only represents features as shipped with the Yocto Project metadata:
62 <itemizedlist>
63 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
64 </para></listitem>
65 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
66 </para></listitem>
67 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
68 </para></listitem>
69 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
70 </para></listitem>
71 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
72 </para></listitem>
73 <listitem><para><emphasis>irda:</emphasis> Hardware has IrDA support
74 </para></listitem>
75 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
76 </para></listitem>
77 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
78 </para></listitem>
79 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
80 </para></listitem>
81 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
82 </para></listitem>
83 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
84 </para></listitem>
85 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
86 </para></listitem>
87 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
88 </para></listitem>
89 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
90 </para></listitem>
91 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
92 </para></listitem>
93 </itemizedlist>
94 </para>
95 </section>
96
97 <section id='ref-features-distro'>
98 <title>Distro Features</title>
99
100 <para>
101 The items below are features you can use with
102 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
103 to enable features across your distribution.
104 Features do not have a one-to-one correspondence to packages,
105 and they can go beyond simply controlling the installation of a
106 package or packages.
107 In most cases, the presence or absence of a feature translates to
108 the appropriate option supplied to the configure script during
109 <filename>do_configure</filename> for the recipes that optionally
110 support the feature.
111 </para>
112
113 <para>
114 Some distro features are also machine features.
115 These select features make sense to be controlled both at
116 the machine and distribution configuration level.
117 See the
118 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></ulink>
119 variable for more information.
120 </para>
121
122 <para>
123 This list only represents features as shipped with the Yocto Project metadata:
124 <itemizedlist>
125 <listitem><para><emphasis>alsa:</emphasis> Include ALSA support
126 (OSS compatibility kernel modules installed if available).
127 </para></listitem>
128 <listitem><para><emphasis>bluetooth:</emphasis> Include
129 bluetooth support (integrated BT only).</para></listitem>
130 <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
131 support.</para></listitem>
132 <listitem><para><emphasis>directfb:</emphasis>
133 Include DirectFB support.
134 </para></listitem>
135 <listitem><para><emphasis>ext2:</emphasis> Include tools for
136 supporting for devices with internal HDD/Microdrive for
137 storing files (instead of Flash only devices).
138 </para></listitem>
139 <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
140 support.</para></listitem>
141 <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
142 </para></listitem>
143 <listitem><para><emphasis>irda:</emphasis> Include IrDA support.
144 </para></listitem>
145 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
146 support (e.g. keymaps will be loaded during boot).
147 </para></listitem>
148 <listitem><para><emphasis>nfs:</emphasis> Include NFS client
149 support (for mounting NFS exports on device).
150 </para></listitem>
151 <listitem><para><emphasis>opengl:</emphasis>
152 Include the Open Graphics Library, which is a
153 cross-language, multi-platform application programming
154 interface used for rendering two and three-dimensional
155 graphics.</para></listitem>
156 <listitem><para><emphasis>pci:</emphasis> Include PCI bus
157 support.</para></listitem>
158 <listitem><para><emphasis>pcmcia:</emphasis> Include
159 PCMCIA/CompactFlash support.</para></listitem>
160 <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
161 support.</para></listitem>
162 <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
163 client support (for mounting Samba/Microsoft Windows shares
164 on device).</para></listitem>
165 <listitem><para><emphasis>systemd:</emphasis> Include support
166 for this <filename>init</filename> manager, which is a full
167 replacement of for <filename>init</filename> with parallel
168 starting of services, reduced shell overhead, and other
169 features.
170 This <filename>init</filename> manager is used by many
171 distributions.</para></listitem>
172 <listitem><para><emphasis>usbgadget:</emphasis> Include USB
173 Gadget Device support (for USB networking/serial/storage).
174 </para></listitem>
175 <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
176 support (allows to connect external keyboard, mouse,
177 storage, network etc).</para></listitem>
178 <listitem><para><emphasis>wayland:</emphasis> Include the
179 Wayland display server protocol and the library that
180 supports it.</para></listitem>
181 <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
182 (integrated only).</para></listitem>
183 <listitem><para><emphasis>x11:</emphasis> Include the X server
184 and libraries.</para></listitem>
185 </itemizedlist>
186 </para>
187 </section>
188
189 <section id='ref-features-image'>
190 <title>Image Features</title>
191
192 <para>
193 The contents of images generated by the OpenEmbedded build system can be controlled by the
194 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
195 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
196 variables that you typically configure in your image recipes.
197 Through these variables, you can add several different
198 predefined packages such as development utilities or packages with debug
199 information needed to investigate application problems or profile applications.
200 </para>
201
202 <para>
203 Current list of
204 <filename>IMAGE_FEATURES</filename> contains the following:
205 <itemizedlist>
206 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages
207 installed in a given image.</para></listitem>
208 <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and
209 extra library links) for all packages installed in a given image.</para></listitem>
210 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages
211 installed in a given image.</para></listitem>
212 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem>
213 <listitem><para><emphasis>read-only-rootfs:</emphasis> Creates
214 an image whose root filesystem is read-only.
215 See the
216 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
217 section in the Yocto Project Development Manual for more
218 information.</para></listitem>
219 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot.
220 By default, this screen is provided by <filename>psplash</filename>, which does
221 allow customization.
222 If you prefer to use an alternative splash screen package, you can do so by
223 setting the <filename>SPLASH</filename> variable
224 to a different package name (or names) within the image recipe or at the distro
225 configuration level.</para></listitem>
226 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
227 SSH server.
228 </para></listitem>
229 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
230 which is more full-featured than Dropbear.
231 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
232 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
233 precedence and Dropbear will not be installed.</para></listitem>
234 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
235 packages (i.e. static libraries containing <filename>*.a</filename> files) for all
236 packages installed in a given image.</para></listitem>
237 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
238 <filename>strace</filename> and <filename>gdb</filename>.
239 For information on GDB, see the
240 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
241 section in the Yocto Project Development Manual.
242 For information on tracing and profiling, see the
243 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
244 </para></listitem>
245 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
246 <filename>oprofile</filename>, <filename>exmap</filename>, and
247 <filename>LTTng</filename>.
248 For general information on user-space tools, see the
249 "<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>"
250 section in the Yocto Project Application Developer's Guide.</para></listitem>
251 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
252 </para></listitem>
253 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
254 touchscreen debugging).</para></listitem>
255 <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem>
256 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
257 minimal environment.</para></listitem>
258 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
259 </para></listitem>
260 </itemizedlist>
261 </para>
262 </section>
263
264 <section id='ref-features-backfill'>
265 <title>Feature Backfilling</title>
266
267 <para>
268 Sometimes it is necessary in the OpenEmbedded build system to extend
269 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
270 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
271 to control functionality that was previously enabled and not able
272 to be disabled.
273 For these cases, we need to add an
274 additional feature item to appear in one of these variables,
275 but we do not want to force developers who have existing values
276 of the variables in their configuration to add the new feature
277 in order to retain the same overall level of functionality.
278 Thus, the OpenEmbedded build system has a mechanism to
279 automatically "backfill" these added features into existing
280 distro or machine configurations.
281 You can see the list of features for which this is done by
282 finding the
283 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
284 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
285 variables in the <filename>meta/conf/bitbake.conf</filename> file.
286 </para>
287
288 <para>
289 Because such features are backfilled by default into all
290 configurations as described in the previous paragraph, developers
291 who wish to disable the new features need to be able to selectively
292 prevent the backfilling from occurring.
293 They can do this by adding the undesired feature or features to the
294 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
295 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
296 variables for distro features and machine features respectively.
297 </para>
298
299 <para>
300 Here are two examples to help illustrate feature backfilling:
301 <itemizedlist>
302 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
303 Previously, PulseAudio support was enabled within the Qt and
304 GStreamer frameworks.
305 Because of this, the feature is backfilled and thus
306 enabled for all distros through the
307 <filename>DISTRO_FEATURES_BACKFILL</filename>
308 variable in the <filename>meta/conf/bitbake.conf</filename> file.
309 However, your distro needs to disable the feature.
310 You can disable the feature without affecting
311 other existing distro configurations that need PulseAudio support
312 by adding "pulseaudio" to
313 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
314 in your distro's <filename>.conf</filename> file.
315 Adding the feature to this variable when it also
316 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
317 variable prevents the build system from adding the feature to
318 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
319 the feature for that particular distro.</para></listitem>
320 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
321 Previously, real time clock (RTC) support was enabled for all
322 target devices.
323 Because of this, the feature is backfilled and thus enabled
324 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
325 variable in the <filename>meta/conf/bitbake.conf</filename> file.
326 However, your target device does not have this capability.
327 You can disable RTC support for your device without
328 affecting other machines that need RTC support
329 by adding the feature to your machine's
330 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
331 list in the machine's <filename>.conf</filename> file.
332 Adding the feature to this variable when it also
333 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
334 variable prevents the build system from adding the feature to
335 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
336 disabling RTC support for that particular machine.</para></listitem>
337 </itemizedlist>
338 </para>
339 </section>
340</chapter>
341
342<!--
343vim: expandtab tw=80 ts=4 spell spelllang=en_gb
344-->
diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml
new file mode 100644
index 0000000..e7d76f2
--- /dev/null
+++ b/documentation/ref-manual/ref-images.xml
@@ -0,0 +1,167 @@
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 id='images-core-image-minimal-initramfs'><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 (initramfs) as part of the kernel,
67 which allows the system to find the first “init” program more efficiently.
68 See the
69 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
70 variable for additional information helpful when working with
71 initramfs images.
72 </para></listitem>
73 <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis>
74 A <filename>core-image-minimal</filename> image that has support
75 for the Minimal MTD Utilities, which let the user interact with the
76 MTD subsystem in the kernel to perform operations on flash devices.
77 </para></listitem>
78 <listitem><para><emphasis><filename>core-image-full-cmdline</filename>:</emphasis>
79 A console-only image with more full-featured Linux system
80 functionality installed.</para></listitem>
81 <listitem><para><emphasis><filename>core-image-lsb</filename>:</emphasis>
82 An image that conforms to the Linux Standard Base (LSB) specification.
83 </para></listitem>
84 <listitem><para><emphasis><filename>core-image-testmaster</filename>:</emphasis>
85 A "master" image designed to be used for automated runtime testing.
86 Provides a "known good" image that is deployed to a separate
87 partition so that you can boot into it and use it to deploy a
88 second image to be tested.
89 You can find more information about runtime testing in the
90 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
91 section in the Yocto Project Development Manual.
92 </para></listitem>
93 <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis>
94 A <filename>core-image-lsb</filename> image that is suitable for development work
95 using the host.
96 The image includes headers and libraries you can use in a host development
97 environment.
98 </para></listitem>
99 <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis>
100 A <filename>core-image-lsb</filename> that includes everything in meta-toolchain
101 but also includes development headers and libraries to form a complete standalone SDK.
102 This image is suitable for development using the target.</para></listitem>
103 <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis>
104 An image with support for the Open GL-based toolkit Clutter, which enables development of
105 rich and animated graphical user interfaces.</para></listitem>
106 <listitem><para><emphasis><filename>core-image-directfb</filename>:</emphasis>
107 An image that uses <filename>directfb</filename> instead of X11.
108 </para></listitem>
109 <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis>
110 A very basic X11 image with a terminal.
111 </para></listitem>
112 <listitem><para><emphasis><filename>core-image-weston</filename>:</emphasis>
113 An image that provides the Wayland protocol libraries and the
114 reference Weston compositor.
115 For more information, see the
116 "<link linkend='wayland'>Wayland</link>" section.
117 </para></listitem>
118 <listitem><para><emphasis><filename>qt4e-demo-image</filename>:</emphasis>
119 An image that launches into the demo application for the embedded
120 (not based on X11) version of Qt.</para></listitem>
121 <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis>
122 A <filename>core-image-minimal</filename> image plus a real-time test suite and
123 tools appropriate for real-time use.</para></listitem>
124 <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis>
125 A <filename>core-image-rt</filename> image that includes everything in
126 <filename>meta-toolchain</filename>.
127 The image also includes development headers and libraries to form a complete
128 stand-alone SDK and is suitable for development using the target.
129 </para></listitem>
130 <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis>
131 An image with Sato support, a mobile environment and visual style that works well
132 with mobile devices.
133 The image supports X11 with a Sato theme and applications such as
134 a terminal, editor, file manager, media player, and so forth.
135 </para></listitem>
136 <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis>
137 A <filename>core-image-sato</filename> image suitable for development
138 using the host.
139 The image includes libraries needed to build applications on the device itself,
140 testing and profiling tools, and debug symbols.
141 This image was formerly <filename>core-image-sdk</filename>.
142 </para></listitem>
143 <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis>
144 A <filename>core-image-sato</filename> image that includes everything in meta-toolchain.
145 The image also includes development headers and libraries to form a complete standalone SDK
146 and is suitable for development using the target.</para></listitem>
147 <listitem><para><emphasis><filename>core-image-multilib-example</filename>:</emphasis>
148 An example image that includes a <filename>lib32</filename> version
149 of Bash into an otherwise standard <filename>sato</filename> image.
150 The image assumes a "lib32" multilib has been enabled in the your
151 configuration.</para></listitem>
152 </itemizedlist>
153
154 <tip>
155 From the Yocto Project release 1.1 onwards, <filename>-live</filename> and
156 <filename>-directdisk</filename> images have been replaced by a "live"
157 option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an
158 image file that can be
159 copied directly to a CD or USB device and run as is.
160 To build a live image, simply add
161 "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename>
162 file or wherever appropriate and then build the desired image as normal.
163 </tip>
164</chapter>
165<!--
166vim: expandtab tw=80 ts=4
167-->
diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl
new file mode 100644
index 0000000..3ad3a31
--- /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 0000000..4e6b799
--- /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 0000000..2574d8c
--- /dev/null
+++ b/documentation/ref-manual/ref-manual.xml
@@ -0,0 +1,146 @@
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>January 2014</date>
78 <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
79 </revision>
80 <revision>
81 <revnumber>1.6</revnumber>
82 <date>April 2014</date>
83 <revremark>Released with the Yocto Project 1.6 Release.</revremark>
84 </revision>
85 <revision>
86 <revnumber>1.6.1</revnumber>
87 <date>Sometime in 2014</date>
88 <revremark>Released with the Yocto Project 1.6.1 Release.</revremark>
89 </revision>
90 </revhistory>
91
92 <copyright>
93 <year>&COPYRIGHT_YEAR;</year>
94 <holder>Linux Foundation</holder>
95 </copyright>
96
97 <legalnotice>
98 <para>
99 Permission is granted to copy, distribute and/or modify this document under
100 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.
101 </para>
102 <note>
103 For the latest version of this manual associated with this
104 Yocto Project release, see the
105 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>
106 from the Yocto Project website.
107 </note>
108 </legalnotice>
109
110 </bookinfo>
111
112 <xi:include href="introduction.xml"/>
113
114 <xi:include href="usingpoky.xml"/>
115
116 <xi:include href="closer-look.xml"/>
117
118 <xi:include href="technical-details.xml"/>
119
120 <xi:include href="migration.xml"/>
121
122 <xi:include href="ref-structure.xml"/>
123
124 <xi:include href="ref-classes.xml"/>
125
126 <xi:include href="ref-images.xml"/>
127
128 <xi:include href="ref-features.xml"/>
129
130 <xi:include href="ref-variables.xml"/>
131
132 <xi:include href="ref-varlocality.xml"/>
133
134 <xi:include href="faq.xml"/>
135
136 <xi:include href="resources.xml"/>
137
138<!-- <index id='index'>
139 <title>Index</title>
140 </index>
141-->
142
143</book>
144<!--
145vim: expandtab tw=80 ts=4
146-->
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
new file mode 100644
index 0000000..93cd45d
--- /dev/null
+++ b/documentation/ref-manual/ref-structure.xml
@@ -0,0 +1,1039 @@
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
43 the BitBake project.
44 BitBake, a
45 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
46 interpreter, reads the Yocto Project Metadata and runs the tasks
47 defined by that data.
48 Failures are usually from the Metadata and not from BitBake itself.
49 Consequently, most users do not need to worry about BitBake.
50 </para>
51
52 <para>
53 When you run the <filename>bitbake</filename> command, the
54 main BitBake executable, which resides in the
55 <filename>bitbake/bin/</filename> directory, starts.
56 Sourcing an environment setup script (e.g.
57 <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
58 or
59 <link linkend="structure-memres-core-script"><filename>oe-init-build-env-memres</filename></link>)
60 places the <filename>scripts</filename> and
61 <filename>bitbake/bin</filename> directories (in that order) into
62 the shell's <filename>PATH</filename> environment variable.
63 </para>
64
65 <para>
66 For more information on BitBake, see the BitBake documentation
67 included in the <filename>bitbake/doc/manual</filename> directory of the
68 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
69 </para>
70 </section>
71
72 <section id='structure-core-build'>
73 <title><filename>build/</filename></title>
74
75 <para>
76 This directory contains user configuration files and the output
77 generated by the OpenEmbedded build system in its standard configuration where
78 the source tree is combined with the output.
79 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
80 is created initially when you <filename>source</filename>
81 the OpenEmbedded build environment setup script
82 (i.e.
83 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
84 or
85 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
86 </para>
87
88 <para>
89 It is also possible to place output and configuration
90 files in a directory separate from the
91 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
92 by providing a directory name when you <filename>source</filename>
93 the setup script.
94 For information on separating output from your local
95 Source Directory files, see the
96 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
97 and
98 "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
99 sections.
100 </para>
101 </section>
102
103 <section id='handbook'>
104 <title><filename>documentation/</filename></title>
105
106 <para>
107 This directory holds the source for the Yocto Project documentation
108 as well as templates and tools that allow you to generate PDF and HTML
109 versions of the manuals.
110 Each manual is contained in a sub-folder.
111 For example, the files for this manual reside in
112 the <filename>ref-manual/</filename> directory.
113 </para>
114 </section>
115
116 <section id='structure-core-meta'>
117 <title><filename>meta/</filename></title>
118
119 <para>
120 This directory contains the OpenEmbedded Core metadata.
121 The directory holds recipes, common classes, and machine
122 configuration for emulated targets (<filename>qemux86</filename>,
123 <filename>qemuarm</filename>, and so forth.)
124 </para>
125 </section>
126
127 <section id='structure-core-meta-yocto'>
128 <title><filename>meta-yocto/</filename></title>
129
130 <para>
131 This directory contains the configuration for the Poky
132 reference distribution.
133 </para>
134 </section>
135
136 <section id='structure-core-meta-yocto-bsp'>
137 <title><filename>meta-yocto-bsp/</filename></title>
138
139 <para>
140 This directory contains the Yocto Project reference
141 hardware Board Support Packages (BSPs).
142 For more information on BSPs, see the
143 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support
144 Package (BSP) Developer's Guide</ulink>.
145 </para>
146 </section>
147
148 <section id='structure-meta-selftest'>
149 <title><filename>meta-selftest/</filename></title>
150
151 <para>
152 This directory adds additional recipes and append files
153 used by the OpenEmbedded selftests to verify the behavior
154 of the build system.
155 </para>
156
157 <para>
158 You do not have to add this layer to your
159 <filename>bblayers.conf</filename> file unless you want to run the
160 selftests.
161 </para>
162 </section>
163
164 <section id='structure-meta-skeleton'>
165 <title><filename>meta-skeleton/</filename></title>
166
167 <para>
168 This directory contains template recipes for BSP and kernel development.
169 </para>
170 </section>
171
172 <section id='structure-core-scripts'>
173 <title><filename>scripts/</filename></title>
174
175 <para>
176 This directory contains various integration scripts that implement
177 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
178 The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
179 and
180 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
181 scripts append this directory to the shell's
182 <filename>PATH</filename> environment variable.
183 </para>
184
185 <para>
186 The <filename>scripts</filename> directory has useful scripts that assist in contributing
187 back to the Yocto Project, such as <filename>create-pull-request</filename> and
188 <filename>send-pull-request</filename>.
189 </para>
190 </section>
191
192 <section id='structure-core-script'>
193 <title><filename>&OE_INIT_FILE;</filename></title>
194
195 <para>
196 This script is one of two scripts that set up the OpenEmbedded build
197 environment.
198 For information on the other script, see the
199 "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
200 section.
201 </para>
202
203 <para>
204 Running this script with the <filename>source</filename> command in
205 a shell makes changes to <filename>PATH</filename> and sets other
206 core BitBake variables based on the current working directory.
207 You need to run an environment setup script before running BitBake
208 commands.
209 The script uses other scripts within the
210 <filename>scripts</filename> directory to do the bulk of the work.
211 </para>
212
213 <para>
214 By default, running this script without a
215 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
216 argument creates the <filename>build</filename> directory
217 in your current working directory.
218 If you provide a Build Directory argument when you
219 <filename>source</filename> the script, you direct the OpenEmbedded
220 build system to create a Build Directory of your choice.
221 For example, the following command creates a Build Directory named
222 <filename>mybuilds</filename> that is outside of the
223 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
224 <literallayout class='monospaced'>
225 $ source &OE_INIT_FILE; ~/mybuilds
226 </literallayout>
227 <note>
228 The OpenEmbedded build system does not support file or directory names that
229 contain spaces.
230 If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
231 from a Source Directory that contains spaces in either the filenames
232 or directory names, the script returns an error indicating no such
233 file or directory.
234 Be sure to use a Source Directory free of names containing spaces.
235 </note>
236 </para>
237 </section>
238
239 <section id='structure-memres-core-script'>
240 <title><filename>oe-init-build-env-memres</filename></title>
241
242 <para>
243 This script is one of two scripts that set up the OpenEmbedded
244 build environment.
245 Aside from setting up the environment, this script starts a
246 memory-resident BitBake server.
247 For information on the other setup script, see the
248 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
249 section.
250 </para>
251
252 <para>
253 Memory-resident BitBake resides in memory until you specifically
254 remove it using the following BitBake command:
255 <literallayout class='monospaced'>
256 $ bitbake -m
257 </literallayout>
258 </para>
259
260 <para>
261 Running this script with the <filename>source</filename> command in
262 a shell makes changes to <filename>PATH</filename> and sets other
263 core BitBake variables based on the current working directory.
264 One of these variables is the
265 <link linkend='var-BBSERVER'><filename>BBSERVER</filename></link>
266 variable, which allows the OpenEmbedded build system to locate
267 the server that is running BitBake.
268 </para>
269
270 <para>
271 You need to run an environment setup script before using BitBake
272 commands.
273 Following is the script syntax:
274 <literallayout class='monospaced'>
275 $ source oe-init-build-env-memres &lt;port_number&gt; &lt;build_dir&gt;
276 </literallayout>
277 The script uses other scripts within the
278 <filename>scripts</filename> directory to do the bulk of the work.
279 </para>
280
281 <para>
282 If you do not provide a port number with the script, the
283 BitBake server at port "12345" is started.
284 </para>
285
286 <para>
287 By default, running this script without a
288 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
289 argument creates a build directory named
290 <filename>build</filename>.
291 If you provide a Build Directory argument when you
292 <filename>source</filename> the script, the Build Directory is
293 created using that name.
294 For example, the following command starts the BitBake server using
295 the default port "12345" and creates a Build Directory named
296 <filename>mybuilds</filename> that is outside of the
297 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
298 <literallayout class='monospaced'>
299 $ source oe-init-build-env-memres ~/mybuilds
300 </literallayout>
301 <note>
302 The OpenEmbedded build system does not support file or
303 directory names that contain spaces.
304 If you attempt to run the
305 <filename>oe-init-build-env-memres</filename> script
306 from a Source Directory that contains spaces in either the
307 filenames or directory names, the script returns an error
308 indicating no such file or directory.
309 Be sure to use a Source Directory free of names containing
310 spaces.
311 </note>
312 </para>
313 </section>
314
315 <section id='structure-basic-top-level'>
316 <title><filename>LICENSE, README, and README.hardware</filename></title>
317
318 <para>
319 These files are standard top-level files.
320 </para>
321 </section>
322</section>
323
324<section id='structure-build'>
325 <title>The Build Directory - <filename>build/</filename></title>
326
327 <para>
328 The OpenEmbedded build system creates the
329 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
330 when you run one of the build environment setup scripts (i.e.
331 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
332 or
333 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
334 </para>
335
336 <para>
337 If you do not give the Build Directory a specific name when you run
338 a setup script, the name defaults to <filename>build</filename>.
339 </para>
340
341 <para>
342 The
343 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable
344 points to the Build Directory.
345 </para>
346
347 <section id='structure-build-buildhistory'>
348 <title><filename>build/buildhistory</filename></title>
349
350 <para>
351 The OpenEmbedded build system creates this directory when you
352 enable the build history feature.
353 The directory tracks build information into image, packages, and
354 SDK subdirectories.
355 For information on the build history feature, see the
356 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
357 section.
358 </para>
359 </section>
360
361 <section id='structure-build-conf-local.conf'>
362 <title><filename>build/conf/local.conf</filename></title>
363
364 <para>
365 This configuration file contains all the local user configurations
366 for your build environment.
367 The <filename>local.conf</filename> file contains documentation on
368 the various configuration options.
369 Any variable set here overrides any variable set elsewhere within
370 the environment unless that variable is hard-coded within a file
371 (e.g. by using '=' instead of '?=').
372 Some variables are hard-coded for various reasons but these
373 variables are relatively rare.
374 </para>
375
376 <para>
377 Edit this file to set the
378 <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
379 for which you want to build, which package types you wish to use
380 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
381 the location from which you want to access downloaded files
382 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
383 and how you want your host machine to use resources
384 (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
385 and
386 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
387 </para>
388
389 <para>
390 If <filename>local.conf</filename> is not present when you
391 start the build, the OpenEmbedded build system creates it from
392 <filename>local.conf.sample</filename> when
393 you <filename>source</filename> the top-level build environment
394 setup script (i.e.
395 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
396 or
397 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
398 </para>
399
400 <para>
401 The source <filename>local.conf.sample</filename> file used
402 depends on the <filename>$TEMPLATECONF</filename> script variable,
403 which defaults to <filename>meta-yocto/conf</filename>
404 when you are building from the Yocto Project development
405 environment and defaults to <filename>meta/conf</filename> when
406 you are building from the OpenEmbedded Core environment.
407 Because the script variable points to the source of the
408 <filename>local.conf.sample</filename> file, this implies that
409 you can configure your build environment from any layer by setting
410 the variable in the top-level build environment setup script as
411 follows:
412 <literallayout class='monospaced'>
413 TEMPLATECONF=&lt;your_layer&gt;/conf
414 </literallayout>
415 Once the build process gets the sample file, it uses
416 <filename>sed</filename> to substitute final
417 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
418 values for all <filename>##OEROOT##</filename> values.
419 <note>
420 You can see how the <filename>TEMPLATECONF</filename> variable
421 is used by looking at the
422 <filename>scripts/oe-setup-builddir</filename> script in the
423 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
424 You can find the Yocto Project version of the
425 <filename>local.conf.sample</filename> file in the
426 <filename>meta-yocto/conf</filename> directory.
427 </note>
428 </para>
429 </section>
430
431 <section id='structure-build-conf-bblayers.conf'>
432 <title><filename>build/conf/bblayers.conf</filename></title>
433
434 <para>
435 This configuration file defines
436 <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
437 which are directory trees, traversed (or walked) by BitBake.
438 The <filename>bblayers.conf</filename> file uses the
439 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
440 variable to list the layers BitBake tries to find, and uses the
441 <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
442 variable to list layers that must not be removed.
443 </para>
444
445 <para>
446 If <filename>bblayers.conf</filename> is not present when you
447 start the build, the OpenEmbedded build system creates it from
448 <filename>bblayers.conf.sample</filename> when
449 you <filename>source</filename> the top-level build environment
450 setup script (i.e.
451 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
452 or
453 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
454 </para>
455
456 <para>
457 The source <filename>bblayers.conf.sample</filename> file used
458 depends on the <filename>$TEMPLATECONF</filename> script variable,
459 which defaults to <filename>meta-yocto/conf</filename>
460 when you are building from the Yocto Project development
461 environment and defaults to <filename>meta/conf</filename> when
462 you are building from the OpenEmbedded Core environment.
463 Because the script variable points to the source of the
464 <filename>bblayers.conf.sample</filename> file, this implies that
465 you can base your build from any layer by setting the variable in
466 the top-level build environment setup script as follows:
467 <literallayout class='monospaced'>
468 TEMPLATECONF=&lt;your_layer&gt;/conf
469 </literallayout>
470 Once the build process gets the sample file, it uses
471 <filename>sed</filename> to substitute final
472 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
473 values for all <filename>##OEROOT##</filename> values.
474 <note>
475 You can see how the <filename>TEMPLATECONF</filename> variable
476 <filename>scripts/oe-setup-builddir</filename> script in the
477 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
478 You can find the Yocto Project version of the
479 <filename>bblayers.conf.sample</filename> file in the
480 <filename>meta-yocto/conf</filename> directory.
481 </note>
482 </para>
483 </section>
484
485 <section id='structure-build-conf-sanity_info'>
486 <title><filename>build/conf/sanity_info</filename></title>
487
488 <para>
489 This file indicates the state of the sanity checks and is created
490 during the build.
491 </para>
492 </section>
493
494 <section id='structure-build-downloads'>
495 <title><filename>build/downloads/</filename></title>
496
497 <para>
498 This directory contains downloaded upstream source tarballs.
499 You can reuse the directory for multiple builds or move
500 the directory to another location.
501 You can control the location of this directory through the
502 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
503 </para>
504 </section>
505
506 <section id='structure-build-sstate-cache'>
507 <title><filename>build/sstate-cache/</filename></title>
508
509 <para>
510 This directory contains the shared state cache.
511 You can reuse the directory for multiple builds or move
512 the directory to another location.
513 You can control the location of this directory through the
514 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
515 </para>
516 </section>
517
518 <section id='structure-build-tmp'>
519 <title><filename>build/tmp/</filename></title>
520
521 <para>
522 The OpenEmbedded build system creates and uses this directory
523 for all the build system's output.
524 The
525 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
526 variable points to this directory.
527 </para>
528
529 <para>
530 BitBake creates this directory if it does not exist.
531 As a last resort, to clean up a build and start it from scratch
532 (other than the downloads), you can remove everything in the
533 <filename>tmp</filename> directory or get rid of the
534 directory completely.
535 If you do, you should also completely remove the
536 <filename>build/sstate-cache</filename> directory.
537 </para>
538 </section>
539
540 <section id='structure-build-tmp-buildstats'>
541 <title><filename>build/tmp/buildstats/</filename></title>
542
543 <para>
544 This directory stores the build statistics.
545 </para>
546 </section>
547
548 <section id='structure-build-tmp-cache'>
549 <title><filename>build/tmp/cache/</filename></title>
550
551 <para>
552 When BitBake parses the metadata, it creates a cache file of the result that can
553 be used when subsequently running commands.
554 BitBake stores these results here on a per-machine basis.
555 </para>
556 </section>
557
558 <section id='structure-build-tmp-deploy'>
559 <title><filename>build/tmp/deploy/</filename></title>
560
561 <para>
562 This directory contains any "end result" output from the
563 OpenEmbedded build process.
564 The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
565 variable points to this directory.
566 For more detail on the contents of the <filename>deploy</filename>
567 directory, see the
568 "<link linkend='images-dev-environment'>Images</link>" and
569 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
570 sections.
571 </para>
572 </section>
573
574 <section id='structure-build-tmp-deploy-deb'>
575 <title><filename>build/tmp/deploy/deb/</filename></title>
576
577 <para>
578 This directory receives any <filename>.deb</filename> packages produced by
579 the build process.
580 The packages are sorted into feeds for different architecture types.
581 </para>
582 </section>
583
584 <section id='structure-build-tmp-deploy-rpm'>
585 <title><filename>build/tmp/deploy/rpm/</filename></title>
586
587 <para>
588 This directory receives any <filename>.rpm</filename> packages produced by
589 the build process.
590 The packages are sorted into feeds for different architecture types.
591 </para>
592 </section>
593
594 <section id='structure-build-tmp-deploy-ipk'>
595 <title><filename>build/tmp/deploy/ipk/</filename></title>
596
597 <para>
598 This directory receives <filename>.ipk</filename> packages produced by
599 the build process.
600 </para>
601 </section>
602
603 <section id='structure-build-tmp-deploy-licenses'>
604 <title><filename>build/tmp/deploy/licenses/</filename></title>
605
606 <para>
607 This directory receives package licensing information.
608 For example, the directory contains sub-directories for <filename>bash</filename>,
609 <filename>busybox</filename>, and <filename>eglibc</filename> (among others) that in turn
610 contain appropriate <filename>COPYING</filename> license files with other licensing information.
611 For information on licensing, see the
612 "<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>"
613 section.
614 </para>
615 </section>
616
617 <section id='structure-build-tmp-deploy-images'>
618 <title><filename>build/tmp/deploy/images/</filename></title>
619
620 <para>
621 This directory receives complete filesystem images.
622 If you want to flash the resulting image from a build onto a device, look here for the image.
623 </para>
624
625 <para>
626 Be careful when deleting files in this directory.
627 You can safely delete old images from this directory (e.g.
628 <filename>core-image-*</filename>, <filename>hob-image-*</filename>,
629 etc.).
630 However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
631 bootloader and other supplementary files might be deployed here prior to building an
632 image.
633 Because these files are not directly produced from the image, if you
634 delete them they will not be automatically re-created when you build the image again.
635 </para>
636
637 <para>
638 If you do accidentally delete files here, you will need to force them to be
639 re-created.
640 In order to do that, you will need to know the target that produced them.
641 For example, these commands rebuild and re-create the kernel files:
642 <literallayout class='monospaced'>
643 $ bitbake -c clean virtual/kernel
644 $ bitbake virtual/kernel
645 </literallayout>
646 </para>
647 </section>
648
649 <section id='structure-build-tmp-deploy-sdk'>
650 <title><filename>build/tmp/deploy/sdk/</filename></title>
651
652 <para>
653 The OpenEmbedded build system creates this directory to hold
654 toolchain installer scripts, which when executed, install the
655 sysroot that matches your target hardware.
656 You can find out more about these installers in the
657 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
658 section in the Yocto Project Application Developer's Guide.
659 </para>
660 </section>
661
662 <section id='structure-build-tmp-sstate-control'>
663 <title><filename>build/tmp/sstate-control/</filename></title>
664
665 <para>
666 The OpenEmbedded build system uses this directory for the
667 shared state manifest files.
668 The shared state code uses these files to record the files
669 installed by each sstate task so that the files can be removed
670 when cleaning the recipe or when a newer version is about to
671 be installed.
672 The build system also uses the manifests to detect and produce
673 a warning when files from one task are overwriting those from
674 another.
675 </para>
676 </section>
677
678 <section id='structure-build-tmp-sysroots'>
679 <title><filename>build/tmp/sysroots/</filename></title>
680
681 <para>
682 This directory contains shared header files and libraries as well as other shared
683 data.
684 Packages that need to share output with other packages do so within this directory.
685 The directory is subdivided by architecture so multiple builds can run within
686 the one Build Directory.
687 </para>
688 </section>
689
690 <section id='structure-build-tmp-stamps'>
691 <title><filename>build/tmp/stamps/</filename></title>
692
693 <para>
694 This directory holds information that BitBake uses for accounting purposes
695 to track what tasks have run and when they have run.
696 The directory is sub-divided by architecture, package name, and
697 version.
698 Following is an example:
699 <literallayout class='monospaced'>
700 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
701 </literallayout>
702 Although the files in the directory are empty of data,
703 BitBake uses the filenames and timestamps for tracking purposes.
704 </para>
705 </section>
706
707 <section id='structure-build-tmp-log'>
708 <title><filename>build/tmp/log/</filename></title>
709
710 <para>
711 This directory contains general logs that are not otherwise placed using the
712 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
713 Examples of logs are the output from the <filename>check_pkg</filename> or
714 <filename>distro_check</filename> tasks.
715 Running a build does not necessarily mean this directory is created.
716 </para>
717 </section>
718
719 <section id='structure-build-tmp-work'>
720 <title><filename>build/tmp/work/</filename></title>
721
722 <para>
723 This directory contains architecture-specific work sub-directories
724 for packages built by BitBake.
725 All tasks execute from the appropriate work directory.
726 For example, the source for a particular package is unpacked,
727 patched, configured and compiled all within its own work directory.
728 Within the work directory, organization is based on the package group
729 and version for which the source is being compiled
730 as defined by the
731 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
732 </para>
733
734 <para>
735 It is worth considering the structure of a typical work directory.
736 As an example, consider <filename>linux-yocto-kernel-3.0</filename>
737 on the machine <filename>qemux86</filename>
738 built within the Yocto Project.
739 For this package, a work directory of
740 <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
741 referred to as the
742 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
743 Within this directory, the source is unpacked to
744 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt.
745 (See the
746 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using a Quilt Flow</ulink>"
747 section in the Yocto Project Development Manual for more information.)
748 Within the <filename>linux-qemux86-standard-build</filename> directory,
749 standard Quilt directories <filename>linux-3.0/patches</filename>
750 and <filename>linux-3.0/.pc</filename> are created,
751 and standard Quilt commands can be used.
752 </para>
753
754 <para>
755 There are other directories generated within <filename>WORKDIR</filename>.
756 The most important directory is <filename>WORKDIR/temp/</filename>,
757 which has log files for each task (<filename>log.do_*.pid</filename>)
758 and contains the scripts BitBake runs for each task
759 (<filename>run.do_*.pid</filename>).
760 The <filename>WORKDIR/image/</filename> directory is where "make
761 install" places its output that is then split into sub-packages
762 within <filename>WORKDIR/packages-split/</filename>.
763 </para>
764 </section>
765
766 <section id='structure-build-work-shared'>
767 <title><filename>build/tmp/work-shared/</filename></title>
768
769 <para>
770 For efficiency, the OpenEmbedded build system creates and uses
771 this directory to hold recipes that share a work directory with
772 other recipes.
773 In practice, this is only used for <filename>gcc</filename>
774 and its variants (e.g. <filename>gcc-cross</filename>,
775 <filename>libgcc</filename>, <filename>gcc-runtime</filename>,
776 and so forth).
777 </para>
778 </section>
779</section>
780
781<section id='structure-meta'>
782 <title>The Metadata - <filename>meta/</filename></title>
783
784 <para>
785 As mentioned previously,
786 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> is the core
787 of the Yocto Project.
788 Metadata has several important subdivisions:
789 </para>
790
791 <section id='structure-meta-classes'>
792 <title><filename>meta/classes/</filename></title>
793
794 <para>
795 This directory contains the <filename>*.bbclass</filename> files.
796 Class files are used to abstract common code so it can be reused by multiple
797 packages.
798 Every package inherits the <filename>base.bbclass</filename> file.
799 Examples of other important classes are <filename>autotools.bbclass</filename>, which
800 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
801 Another example is <filename>kernel.bbclass</filename> that contains common code and functions
802 for working with the Linux kernel.
803 Functions like image generation or packaging also have their specific class files
804 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
805 <filename>package*.bbclass</filename>.
806 </para>
807
808 <para>
809 For reference information on classes, see the
810 "<link linkend='ref-classes'>Classes</link>" chapter.
811 </para>
812 </section>
813
814 <section id='structure-meta-conf'>
815 <title><filename>meta/conf/</filename></title>
816
817 <para>
818 This directory contains the core set of configuration files that start from
819 <filename>bitbake.conf</filename> and from which all other configuration
820 files are included.
821 See the include statements at the end of the
822 <filename>bitbake.conf</filename> file and you will note that even
823 <filename>local.conf</filename> is loaded from there.
824 While <filename>bitbake.conf</filename> sets up the defaults, you can often override
825 these by using the (<filename>local.conf</filename>) file, machine file or
826 the distribution configuration file.
827 </para>
828 </section>
829
830 <section id='structure-meta-conf-machine'>
831 <title><filename>meta/conf/machine/</filename></title>
832
833 <para>
834 This directory contains all the machine configuration files.
835 If you set <filename>MACHINE = "qemux86"</filename>,
836 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
837 directory.
838 The <filename>include</filename> directory contains various data common to multiple machines.
839 If you want to add support for a new machine to the Yocto Project, look in this directory.
840 </para>
841 </section>
842
843 <section id='structure-meta-conf-distro'>
844 <title><filename>meta/conf/distro/</filename></title>
845
846 <para>
847 The contents of this directory controls any distribution-specific
848 configurations.
849 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
850 This directory includes the versions and the
851 <filename>SRCDATE</filename> definitions for applications that are configured here.
852 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
853 Although this file mainly inherits its configuration from Poky.
854 </para>
855 </section>
856
857 <section id='structure-meta-conf-machine-sdk'>
858 <title><filename>meta/conf/machine-sdk/</filename></title>
859
860 <para>
861 The OpenEmbedded build system searches this directory for
862 configuration files that correspond to the value of
863 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
864 By default, 32-bit and 64-bit x86 files ship with the Yocto
865 Project that support some SDK hosts.
866 However, it is possible to extend that support to other SDK hosts
867 by adding additional configuration files in this subdirectory
868 within another layer.
869 </para>
870 </section>
871
872 <section id='structure-meta-files'>
873 <title><filename>meta/files/</filename></title>
874
875 <para>
876 This directory contains common license files and several text files
877 used by the build system.
878 The text files contain minimal device information and
879 lists of files and directories with known permissions.
880 </para>
881 </section>
882
883 <section id='structure-meta-lib'>
884 <title><filename>meta/lib/</filename></title>
885
886 <para>
887 This directory contains OpenEmbedded Python library code
888 used during the build process.
889 </para>
890 </section>
891
892 <section id='structure-meta-recipes-bsp'>
893 <title><filename>meta/recipes-bsp/</filename></title>
894
895 <para>
896 This directory contains anything linking to specific hardware or hardware
897 configuration information such as "u-boot" and "grub".
898 </para>
899 </section>
900
901 <section id='structure-meta-recipes-connectivity'>
902 <title><filename>meta/recipes-connectivity/</filename></title>
903
904 <para>
905 This directory contains libraries and applications related to communication with other devices.
906 </para>
907 </section>
908
909 <section id='structure-meta-recipes-core'>
910 <title><filename>meta/recipes-core/</filename></title>
911
912 <para>
913 This directory contains what is needed to build a basic working Linux image
914 including commonly used dependencies.
915 </para>
916 </section>
917
918 <section id='structure-meta-recipes-devtools'>
919 <title><filename>meta/recipes-devtools/</filename></title>
920
921 <para>
922 This directory contains tools that are primarily used by the build system.
923 The tools, however, can also be used on targets.
924 </para>
925 </section>
926
927 <section id='structure-meta-recipes-extended'>
928 <title><filename>meta/recipes-extended/</filename></title>
929
930 <para>
931 This directory contains non-essential applications that add features compared to the
932 alternatives in core.
933 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
934 compliance.
935 </para>
936 </section>
937
938 <section id='structure-meta-recipes-gnome'>
939 <title><filename>meta/recipes-gnome/</filename></title>
940
941 <para>
942 This directory contains all things related to the GTK+ application framework.
943 </para>
944 </section>
945
946 <section id='structure-meta-recipes-graphics'>
947 <title><filename>meta/recipes-graphics/</filename></title>
948
949 <para>
950 This directory contains X and other graphically related system libraries
951 </para>
952 </section>
953
954 <section id='structure-meta-recipes-kernel'>
955 <title><filename>meta/recipes-kernel/</filename></title>
956
957 <para>
958 This directory contains the kernel and generic applications and libraries that
959 have strong kernel dependencies.
960 </para>
961 </section>
962
963 <section id='structure-meta-recipes-lsb4'>
964 <title><filename>meta/recipes-lsb4/</filename></title>
965
966 <para>
967 This directory contains recipes specifically added to support
968 the Linux Standard Base (LSB) version 4.x.
969 </para>
970 </section>
971
972 <section id='structure-meta-recipes-multimedia'>
973 <title><filename>meta/recipes-multimedia/</filename></title>
974
975 <para>
976 This directory contains codecs and support utilities for audio, images and video.
977 </para>
978 </section>
979
980 <section id='structure-meta-recipes-qt'>
981 <title><filename>meta/recipes-qt/</filename></title>
982
983 <para>
984 This directory contains all things related to the Qt application framework.
985 </para>
986 </section>
987
988 <section id='structure-meta-recipes-rt'>
989 <title><filename>meta/recipes-rt/</filename></title>
990
991 <para>
992 This directory contains package and image recipes for using and testing
993 the <filename>PREEMPT_RT</filename> kernel.
994 </para>
995 </section>
996
997 <section id='structure-meta-recipes-sato'>
998 <title><filename>meta/recipes-sato/</filename></title>
999
1000 <para>
1001 This directory contains the Sato demo/reference UI/UX and its associated applications
1002 and configuration data.
1003 </para>
1004 </section>
1005
1006 <section id='structure-meta-recipes-support'>
1007 <title><filename>meta/recipes-support/</filename></title>
1008
1009 <para>
1010 This directory contains recipes used by other recipes, but that are
1011 not directly included in images (i.e. dependencies of other
1012 recipes).
1013 </para>
1014 </section>
1015
1016 <section id='structure-meta-site'>
1017 <title><filename>meta/site/</filename></title>
1018
1019 <para>
1020 This directory contains a list of cached results for various architectures.
1021 Because certain "autoconf" test results cannot be determined when cross-compiling due to
1022 the tests not able to run on a live system, the information in this directory is
1023 passed to "autoconf" for the various architectures.
1024 </para>
1025 </section>
1026
1027 <section id='structure-meta-recipes-txt'>
1028 <title><filename>meta/recipes.txt</filename></title>
1029
1030 <para>
1031 This file is a description of the contents of <filename>recipes-*</filename>.
1032 </para>
1033 </section>
1034</section>
1035
1036</chapter>
1037<!--
1038vim: expandtab tw=80 ts=4
1039-->
diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css
new file mode 100644
index 0000000..e896a39
--- /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 0000000..4ff1a21
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,8419 @@
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-FEATURE_PACKAGES'>F</link>
25 <link linkend='var-GROUPADD_PARAM'>G</link>
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-ICECC_DISABLED'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LABELS'>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-QMAKE_PROFILES'>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_CONFIG'>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 hard runtime 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, as in:
62 <literallayout class='monospaced'>
63 ALLOW_EMPTY_${PN} = "1"
64 ALLOW_EMPTY_${PN}-dev = "1"
65 ALLOW_EMPTY_${PN}-staticdev = "1"
66 </literallayout>
67 </para>
68 </glossdef>
69 </glossentry>
70
71 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
72 <glossdef>
73 <para>
74 Lists commands in a package that need an alternative
75 binary naming scheme.
76 Sometimes the same command is provided in multiple packages.
77 When this occurs, the OpenEmbedded build system needs to
78 use the alternatives system to create a different binary
79 naming scheme so the commands can co-exist.
80 </para>
81
82 <para>
83 To use the variable, list out the package's commands
84 that also exist as part of another package.
85 For example, if the <filename>busybox</filename> package
86 has four commands that also exist as part of another
87 package, you identify them as follows:
88 <literallayout class='monospaced'>
89 ALTERNATIVE_busybox = "sh sed test bracket"
90 </literallayout>
91 For more information on the alternatives system, see the
92 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
93 section.
94 </para>
95 </glossdef>
96 </glossentry>
97
98 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
99 <glossdef>
100 <para>
101 Used by the alternatives system to map duplicated commands
102 to actual locations.
103 For example, if the <filename>bracket</filename> command
104 provided by the <filename>busybox</filename> package is
105 duplicated through another package, you must use the
106 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
107 specify the actual location:
108 <literallayout class='monospaced'>
109 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
110 </literallayout>
111 In this example, the binary for the
112 <filename>bracket</filename> command (i.e.
113 <filename>[</filename>) from the
114 <filename>busybox</filename> package resides in
115 <filename>/usr/bin/</filename>.
116 <note>
117 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
118 defined, it defaults to
119 <filename>${bindir}/&lt;name&gt;</filename>.
120 </note>
121 </para>
122
123 <para>
124 For more information on the alternatives system, see the
125 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
126 section.
127 </para>
128 </glossdef>
129 </glossentry>
130
131 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
132 <glossdef>
133 <para>
134 Used by the alternatives system to create default
135 priorities for duplicated commands.
136 You can use the variable to create a single default
137 regardless of the command name or package, a default for
138 specific duplicated commands regardless of the package, or
139 a default for specific commands tied to particular packages.
140 Here are the available syntax forms:
141 <literallayout class='monospaced'>
142 ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
143 ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
144 ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
145 </literallayout>
146 </para>
147
148 <para>
149 For more information on the alternatives system, see the
150 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
151 section.
152 </para>
153 </glossdef>
154 </glossentry>
155
156 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
157 <glossdef>
158 <para>
159 Used by the alternatives system to create default link
160 locations for duplicated commands.
161 You can use the variable to create a single default
162 location for all duplicated commands regardless of the
163 command name or package, a default for
164 specific duplicated commands regardless of the package, or
165 a default for specific commands tied to particular packages.
166 Here are the available syntax forms:
167 <literallayout class='monospaced'>
168 ALTERNATIVE_TARGET = "&lt;target&gt;"
169 ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
170 ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
171 </literallayout>
172 <note>
173 <para>
174 If <filename>ALTERNATIVE_TARGET</filename> is not
175 defined, it inherits the value from the
176 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
177 variable.
178 </para>
179
180 <para>
181 If <filename>ALTERNATIVE_LINK_NAME</filename> and
182 <filename>ALTERNATIVE_TARGET</filename> are the
183 same, the target for
184 <filename>ALTERNATIVE_TARGET</filename>
185 has "<filename>.{BPN}</filename>" appended to it.
186 </para>
187
188 <para>
189 Finally, if the file referenced has not been
190 renamed, the alternatives system will rename it to
191 avoid the need to rename alternative files in the
192 <filename>do_install</filename> task while
193 retaining support for the command if necessary.
194 </para>
195 </note>
196 </para>
197
198 <para>
199 For more information on the alternatives system, see the
200 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
201 section.
202 </para>
203 </glossdef>
204 </glossentry>
205
206 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
207 <glossdef>
208 <para>
209 An override list of append strings for each
210 <link linkend='var-LABELS'><filename>LABEL</filename></link>.
211 </para>
212
213 <para>
214 See the
215 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
216 class for more information on how this variable is used.
217 </para>
218 </glossdef>
219 </glossentry>
220
221 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
222 <glossdef>
223 <para>The email address used to contact the original author
224 or authors in order to send patches and forward bugs.</para>
225 </glossdef>
226 </glossentry>
227
228 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
229 <glossdef>
230 <para>
231 Enables creating an automatic menu.
232 You must set this in your recipe.
233 The
234 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
235 class checks this variable.
236 </para>
237 </glossdef>
238 </glossentry>
239
240 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
241 <glossdef>
242 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
243 is set to the value of this variable, it specifies to use the latest
244 source revision in the repository.
245 Here is an example:
246 <literallayout class='monospaced'>
247 SRCREV = "${AUTOREV}"
248 </literallayout>
249 </para>
250 </glossdef>
251 </glossentry>
252
253 </glossdiv>
254
255 <glossdiv id='var-glossary-b'><title>B</title>
256
257 <glossentry id='var-B'><glossterm>B</glossterm>
258 <glossdef>
259 <para>
260 The directory within the
261 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
262 in which the OpenEmbedded build system places generated
263 objects during a recipe's build process.
264 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
265 directory, which is defined as:
266 <literallayout class='monospaced'>
267 S = "${WORKDIR}/${BP}/"
268 </literallayout>
269 You can separate the (<filename>S</filename>) directory
270 and the directory pointed to by the <filename>B</filename>
271 variable.
272 Most Autotools-based recipes support separating these
273 directories.
274 The build system defaults to using separate directories for
275 <filename>gcc</filename> and some kernel recipes.
276 </para>
277 </glossdef>
278 </glossentry>
279
280 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
281 <glossdef>
282 <para>
283 Lists "recommended-only" packages to not install.
284 Recommended-only packages are packages installed only
285 through the
286 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
287 variable.
288 You can prevent any of these "recommended" packages from
289 being installed by listing them with the
290 <filename>BAD_RECOMMENDATIONS</filename> variable:
291 <literallayout class='monospaced'>
292 BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
293 </literallayout>
294 You can set this variable globally in your
295 <filename>local.conf</filename> file or you can attach it to
296 a specific image recipe by using the recipe name override:
297 <literallayout class='monospaced'>
298 BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
299 </literallayout>
300 </para>
301
302 <para>
303 It is important to realize that if you choose to not install
304 packages using this variable and some other packages are
305 dependent on them (i.e. listed in a recipe's
306 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
307 variable), the OpenEmbedded build system ignores your
308 request and will install the packages to avoid dependency
309 errors.
310 </para>
311
312 <para>
313 Support for this variable exists only when using the
314 IPK and RPM packaging backend.
315 Support does not exist for DEB.
316 </para>
317
318 <para>
319 See the
320 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
321 and the
322 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
323 variables for related information.
324 </para>
325 </glossdef>
326 </glossentry>
327
328 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
329 <glossdef>
330 <para>
331 Defines how BitBake handles situations where an append
332 file (<filename>.bbappend</filename>) has no
333 corresponding recipe file (<filename>.bb</filename>).
334 This condition often occurs when layers get out of sync
335 (e.g. <filename>oe-core</filename> bumps a
336 recipe version and the old recipe no longer exists and the
337 other layer has not been updated to the new version
338 of the recipe yet).
339 </para>
340
341 <para>
342 The default fatal behavior is safest because it is
343 the sane reaction given something is out of sync.
344 It is important to realize when your changes are no longer
345 being applied.
346 </para>
347
348 <para>
349 You can change the default behavior by setting this
350 variable to "1", "yes", or "true"
351 in your <filename>local.conf</filename> file, which is
352 located in the
353 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
354 Here is an example:
355 <literallayout class='monospaced'>
356 BB_DANGLINGAPPENDS_WARNONLY = "1"
357 </literallayout>
358 </para>
359 </glossdef>
360 </glossentry>
361
362 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
363 <glossdef>
364 <para>
365 Monitors disk space and available inodes during the build
366 and allows you to control the build based on these
367 parameters.
368 </para>
369
370 <para>
371 Disk space monitoring is disabled by default.
372 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
373 variable to your <filename>conf/local.conf</filename> file found in the
374 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
375 Use the following form:
376 <literallayout class='monospaced'>
377 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
378
379 where:
380
381 &lt;action&gt; is:
382 ABORT: Immediately abort the build when
383 a threshold is broken.
384 STOPTASKS: Stop the build after the currently
385 executing tasks have finished when
386 a threshold is broken.
387 WARN: Issue a warning but continue the
388 build when a threshold is broken.
389 Subsequent warnings are issued as
390 defined by the
391 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
392 which must be defined in the
393 conf/local.conf file.
394
395 &lt;dir&gt; is:
396 Any directory you choose. You can specify one or
397 more directories to monitor by separating the
398 groupings with a space. If two directories are
399 on the same device, only the first directory
400 is monitored.
401
402 &lt;threshold&gt; is:
403 Either the minimum available disk space,
404 the minimum number of free inodes, or
405 both. You must specify at least one. To
406 omit one or the other, simply omit the value.
407 Specify the threshold using G, M, K for Gbytes,
408 Mbytes, and Kbytes, respectively. If you do
409 not specify G, M, or K, Kbytes is assumed by
410 default. Do not use GB, MB, or KB.
411 </literallayout>
412 </para>
413
414 <para>
415 Here are some examples:
416 <literallayout class='monospaced'>
417 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
418 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
419 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
420 </literallayout>
421 The first example works only if you also provide
422 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
423 in the <filename>conf/local.conf</filename>.
424 This example causes the build system to immediately
425 abort when either the disk space in <filename>${TMPDIR}</filename> drops
426 below 1 Gbyte or the available free inodes drops below
427 100 Kbytes.
428 Because two directories are provided with the variable, the
429 build system also issue a
430 warning when the disk space in the
431 <filename>${SSTATE_DIR}</filename> directory drops
432 below 1 Gbyte or the number of free inodes drops
433 below 100 Kbytes.
434 Subsequent warnings are issued during intervals as
435 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
436 variable.
437 </para>
438
439 <para>
440 The second example stops the build after all currently
441 executing tasks complete when the minimum disk space
442 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
443 directory drops below 1 Gbyte.
444 No disk monitoring occurs for the free inodes in this case.
445 </para>
446
447 <para>
448 The final example immediately aborts the build when the
449 number of free inodes in the <filename>${TMPDIR}</filename> directory
450 drops below 100 Kbytes.
451 No disk space monitoring for the directory itself occurs
452 in this case.
453 </para>
454 </glossdef>
455 </glossentry>
456
457 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
458 <glossdef>
459 <para>
460 Defines the disk space and free inode warning intervals.
461 To set these intervals, define the variable in your
462 <filename>conf/local.conf</filename> file in the
463 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
464 </para>
465
466 <para>
467 If you are going to use the
468 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
469 also use the
470 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
471 and define its action as "WARN".
472 During the build, subsequent warnings are issued each time
473 disk space or number of free inodes further reduces by
474 the respective interval.
475 </para>
476
477 <para>
478 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
479 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
480 the "WARN" action, the disk monitoring interval defaults to
481 the following:
482 <literallayout class='monospaced'>
483 BB_DISKMON_WARNINTERVAL = "50M,5K"
484 </literallayout>
485 </para>
486
487 <para>
488 When specifying the variable in your configuration file,
489 use the following form:
490 <literallayout class='monospaced'>
491 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
492
493 where:
494
495 &lt;disk_space_interval&gt; is:
496 An interval of memory expressed in either
497 G, M, or K for Gbytes, Mbytes, or Kbytes,
498 respectively. You cannot use GB, MB, or KB.
499
500 &lt;disk_inode_interval&gt; is:
501 An interval of free inodes expressed in either
502 G, M, or K for Gbytes, Mbytes, or Kbytes,
503 respectively. You cannot use GB, MB, or KB.
504 </literallayout>
505 </para>
506
507 <para>
508 Here is an example:
509 <literallayout class='monospaced'>
510 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
511 BB_DISKMON_WARNINTERVAL = "50M,5K"
512 </literallayout>
513 These variables cause the OpenEmbedded build system to
514 issue subsequent warnings each time the available
515 disk space further reduces by 50 Mbytes or the number
516 of free inodes further reduces by 5 Kbytes in the
517 <filename>${SSTATE_DIR}</filename> directory.
518 Subsequent warnings based on the interval occur each time
519 a respective interval is reached beyond the initial warning
520 (i.e. 1 Gbytes and 100 Kbytes).
521 </para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
526 <glossdef>
527 <para>
528 Causes tarballs of the Git repositories, including the
529 Git metadata, to be placed in the
530 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
531 directory.
532 </para>
533
534 <para>
535 For performance reasons, creating and placing tarballs of
536 the Git repositories is not the default action by the
537 OpenEmbedded build system.
538 <literallayout class='monospaced'>
539 BB_GENERATE_MIRROR_TARBALLS = "1"
540 </literallayout>
541 Set this variable in your <filename>local.conf</filename>
542 file in the
543 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
544 </para>
545 </glossdef>
546 </glossentry>
547
548 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
549 <glossdef>
550 <para>
551 The maximum number of tasks BitBake should run in parallel
552 at any one time.
553 If your host development system supports multiple cores,
554 a good rule of thumb is to set this variable to twice the
555 number of cores.
556 </para>
557
558 <para>
559 The default value for <filename>BB_NUMBER_THREADS</filename>
560 is equal to the number of cores your build system has.
561 </para>
562 </glossdef>
563 </glossentry>
564
565 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
566 <glossdef>
567 <para>
568 Allows you to extend a recipe so that it builds variants of the software.
569 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
570 which is a copy of Quilt built to run on the build system;
571 "crosses" such as <filename>gcc-cross</filename>,
572 which is a compiler built to run on the build machine but produces binaries
573 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
574 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
575 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
576 </para>
577
578 <para>
579 To build a different variant of the recipe with a minimal amount of code, it usually
580 is as simple as adding the following to your recipe:
581 <literallayout class='monospaced'>
582 BBCLASSEXTEND =+ "native nativesdk"
583 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
584 </literallayout>
585 </para>
586 </glossdef>
587 </glossentry>
588
589 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
590 <glossdef>
591 <para>Lists the names of configured layers.
592 These names are used to find the other <filename>BBFILE_*</filename>
593 variables.
594 Typically, each layer will append its name to this variable in its
595 <filename>conf/layer.conf</filename> file.
596 </para>
597 </glossdef>
598 </glossentry>
599
600 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
601 <glossdef>
602 <para>Variable that expands to match files from
603 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
604 in a particular layer.
605 This variable is used in the <filename>conf/layer.conf</filename> file and must
606 be suffixed with the name of the specific layer (e.g.
607 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
608 </glossdef>
609 </glossentry>
610
611 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
612 <glossdef>
613 <para>Assigns the priority for recipe files in each layer.</para>
614 <para>This variable is useful in situations where the same recipe appears in
615 more than one layer.
616 Setting this variable allows you to prioritize a
617 layer against other layers that contain the same recipe - effectively
618 letting you control the precedence for the multiple layers.
619 The precedence established through this variable stands regardless of a
620 recipe's version
621 (<link linkend='var-PV'><filename>PV</filename></link> variable).
622 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
623 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
624 lower precedence.</para>
625 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
626 precedence.
627 For example, the value 6 has a higher precedence than the value 5.
628 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
629 dependencies (see the
630 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
631 more information.
632 The default priority, if unspecified
633 for a layer with no dependencies, is the lowest defined priority + 1
634 (or 1 if no priorities are defined).</para>
635 <tip>
636 You can use the command <filename>bitbake-layers show-layers</filename> to list
637 all configured layers along with their priorities.
638 </tip>
639 </glossdef>
640 </glossentry>
641
642 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
643 <glossdef>
644 <para>List of recipe files used by BitBake to build software.</para>
645 </glossdef>
646 </glossentry>
647
648 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
649 <glossdef>
650 <para>Variable that controls how BitBake displays logs on build failure.</para>
651 </glossdef>
652 </glossentry>
653
654 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
655 <glossdef>
656 <para>Lists the layers to enable during the build.
657 This variable is defined in the <filename>bblayers.conf</filename> configuration
658 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
659 Here is an example:
660 <literallayout class='monospaced'>
661 BBLAYERS = " \
662 /home/scottrif/poky/meta \
663 /home/scottrif/poky/meta-yocto \
664 /home/scottrif/poky/meta-yocto-bsp \
665 /home/scottrif/poky/meta-mykernel \
666 "
667
668 BBLAYERS_NON_REMOVABLE ?= " \
669 /home/scottrif/poky/meta \
670 /home/scottrif/poky/meta-yocto \
671 "
672 </literallayout>
673 This example enables four layers, one of which is a custom, user-defined layer
674 named <filename>meta-mykernel</filename>.
675 </para>
676 </glossdef>
677 </glossentry>
678
679 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
680 <glossdef>
681 <para>Lists core layers that cannot be removed from the
682 <filename>bblayers.conf</filename> file during a build
683 using the
684 <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>.
685 <note>
686 When building an image outside of Hob, this variable
687 is ignored.
688 </note>
689 In order for BitBake to build your image using Hob, your
690 <filename>bblayers.conf</filename> file must include the
691 <filename>meta</filename> and <filename>meta-yocto</filename>
692 core layers.
693 Here is an example that shows these two layers listed in
694 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
695 <literallayout class='monospaced'>
696 BBLAYERS = " \
697 /home/scottrif/poky/meta \
698 /home/scottrif/poky/meta-yocto \
699 /home/scottrif/poky/meta-yocto-bsp \
700 /home/scottrif/poky/meta-mykernel \
701 "
702
703 BBLAYERS_NON_REMOVABLE ?= " \
704 /home/scottrif/poky/meta \
705 /home/scottrif/poky/meta-yocto \
706 "
707 </literallayout>
708 </para>
709 </glossdef>
710 </glossentry>
711
712 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
713 <glossdef>
714 <para>
715 Prevents BitBake from processing recipes and recipe
716 append files.
717 Use the <filename>BBMASK</filename> variable from within the
718 <filename>conf/local.conf</filename> file found
719 in the
720 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
721 </para>
722
723 <para>
724 You can use the <filename>BBMASK</filename> variable
725 to "hide" these <filename>.bb</filename> and
726 <filename>.bbappend</filename> files.
727 BitBake ignores any recipe or recipe append files that
728 match the expression.
729 It is as if BitBake does not see them at all.
730 Consequently, matching files are not parsed or otherwise
731 used by BitBake.</para>
732 <para>
733 The value you provide is passed to Python's regular
734 expression compiler.
735 The expression is compared against the full paths to
736 the files.
737 For complete syntax information, see Python's
738 documentation at
739 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
740 </para>
741
742 <para>
743 The following example uses a complete regular expression
744 to tell BitBake to ignore all recipe and recipe append
745 files in the <filename>meta-ti/recipes-misc/</filename>
746 directory:
747 <literallayout class='monospaced'>
748 BBMASK = "meta-ti/recipes-misc/"
749 </literallayout>
750 If you want to mask out multiple directories or recipes,
751 use the vertical bar to separate the regular expression
752 fragments.
753 This next example masks out multiple directories and
754 individual recipes:
755 <literallayout class='monospaced'>
756 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
757 BBMASK .= "|.*meta-oe/recipes-support/"
758 BBMASK .= "|.*openldap"
759 BBMASK .= "|.*opencv"
760 BBMASK .= "|.*lzma"
761 </literallayout>
762 Notice how the vertical bar is used to append the fragments.
763 <note>
764 When specifying a directory name, use the trailing
765 slash character to ensure you match just that directory
766 name.
767 </note>
768 </para>
769 </glossdef>
770 </glossentry>
771
772 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
773 <glossdef>
774 <para>
775 Used by BitBake to locate
776 <filename>.bbclass</filename> and configuration files.
777 This variable is analogous to the
778 <filename>PATH</filename> variable.
779 <note>
780 If you run BitBake from a directory outside of the
781 <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
782 you must be sure to set
783 <filename>BBPATH</filename> to point to the
784 Build Directory.
785 Set the variable as you would any environment variable
786 and then run BitBake:
787 <literallayout class='monospaced'>
788 $ BBPATH = "&lt;build_directory&gt;"
789 $ export BBPATH
790 $ bitbake &lt;target&gt;
791 </literallayout>
792 </note>
793 </para>
794 </glossdef>
795 </glossentry>
796
797 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
798 <glossdef>
799 <para>
800 Points to the server that runs memory-resident BitBake.
801 This variable is set by the
802 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
803 setup script and should not be hand-edited.
804 The variable is only used when you employ memory-resident
805 BitBake.
806 The setup script exports the value as follows:
807 <literallayout class='monospaced'>
808 export BBSERVER=localhost:$port
809 </literallayout>
810 For more information on how the
811 <filename>BBSERVER</filename> is used, see the
812 <filename>oe-init-build-env-memres</filename> script, which
813 is located in the
814 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
815 </para>
816 </glossdef>
817 </glossentry>
818
819 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
820 <glossdef>
821 <para>
822 When inheriting <filename>binconfig.bbclass</filename>
823 from a recipe, this variable specifies a wildcard for
824 configuration scripts that need editing.
825 The scripts are edited to correct any paths that have been
826 set up during compilation so that they are correct for
827 use when installed into the sysroot and called by the
828 build processes of other recipes.
829 </para>
830
831 <para>
832 For more information on how this variable works, see
833 <filename>meta/classes/binconfig.bbclass</filename> in the
834 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
835 You can also find general information on the class in the
836 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
837 section.
838 </para>
839 </glossdef>
840 </glossentry>
841
842 <glossentry id='var-BP'><glossterm>BP</glossterm>
843 <glossdef>
844 <para>The base recipe name and version but without any special
845 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
846 and so forth).
847 <filename>BP</filename> is comprised of the following:
848 <literallayout class="monospaced">
849 ${BPN}-${PV}
850 </literallayout></para>
851 </glossdef>
852 </glossentry>
853
854 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
855 <glossdef>
856 <para>The bare name of the recipe.
857 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
858 but removes common suffixes such as "-native" and "-cross" as well
859 as removes common prefixes such as multilib's "lib64-" and "lib32-".
860 The exact list of suffixes removed is specified by the
861 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
862 The exact list of prefixes removed is specified by the
863 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
864 Prefixes are removed for <filename>multilib</filename>
865 and <filename>nativesdk</filename> cases.</para>
866 </glossdef>
867 </glossentry>
868
869 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
870 <glossdef>
871 <para>
872 Specifies a URL for an upstream bug tracking website for
873 a recipe.
874 The OpenEmbedded build system does not use this variable.
875 Rather, the variable is a useful pointer in case a bug
876 in the software being built needs to be manually reported.
877 </para>
878 </glossdef>
879 </glossentry>
880
881 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
882 <glossdef>
883 <para>
884 Points to the location of the
885 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
886 You can define this directory indirectly through the
887 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
888 and
889 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
890 scripts by passing in a Build Directory path when you run
891 the scripts.
892 If you run the scripts and do not provide a Build Directory
893 path, the <filename>BUILDDIR</filename> defaults to
894 <filename>build</filename> in the current directory.
895 </para>
896 </glossdef>
897 </glossentry>
898
899 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
900 <glossdef>
901 <para>
902 When inheriting the
903 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
904 class, specifies whether or not to commit the build
905 history output in a local Git repository.
906 If set to "1", this local repository will be maintained
907 automatically by the
908 <filename>buildhistory</filename>
909 class and a commit will be created on every
910 build for changes to each top-level subdirectory of the
911 build history output (images, packages, and sdk).
912 If you want to track changes to build history over
913 time, you should set this value to "1".
914 </para>
915
916 <para>
917 By default, the <filename>buildhistory</filename> class
918 does not commit the build history output in a local
919 Git repository:
920 <literallayout class='monospaced'>
921 BUILDHISTORY_COMMIT ?= "0"
922 </literallayout>
923 </para>
924 </glossdef>
925 </glossentry>
926
927 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
928 <glossdef>
929 <para>
930 When inheriting the
931 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
932 class, specifies the author to use for each Git commit.
933 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
934 variable to work, the
935 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
936 variable must be set to "1".
937 </para>
938
939 <para>
940 Git requires that the value you provide for the
941 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
942 takes the form of "name &lt;email@host&gt;".
943 Providing an email address or host that is not valid does
944 not produce an error.
945 </para>
946
947 <para>
948 By default, the <filename>buildhistory</filename> class
949 sets the variable as follows:
950 <literallayout class='monospaced'>
951 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
952 </literallayout>
953 </para>
954 </glossdef>
955 </glossentry>
956
957 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
958 <glossdef>
959 <para>
960 When inheriting the
961 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
962 class, specifies the directory in which build history
963 information is kept.
964 For more information on how the variable works, see the
965 <filename>buildhistory.class</filename>.
966 </para>
967
968 <para>
969 By default, the <filename>buildhistory</filename> class
970 sets the directory as follows:
971 <literallayout class='monospaced'>
972 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
973 </literallayout>
974 </para>
975 </glossdef>
976 </glossentry>
977
978 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
979 <glossdef>
980 <para>
981 When inheriting the
982 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
983 class, specifies the build history features to be enabled.
984 For more information on how build history works, see the
985 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
986 section.
987 </para>
988
989 <para>
990 You can specify three features in the form of a
991 space-separated list:
992 <itemizedlist>
993 <listitem><para><emphasis>image:</emphasis>
994 Analysis of the contents of images, which
995 includes the list of installed packages among other
996 things.
997 </para></listitem>
998 <listitem><para><emphasis>package:</emphasis>
999 Analysis of the contents of individual packages.
1000 </para></listitem>
1001 <listitem><para><emphasis>sdk:</emphasis>
1002 Analysis of the contents of the software
1003 development kit (SDK).
1004 </para></listitem>
1005 </itemizedlist>
1006 </para>
1007
1008 <para>
1009 By default, the <filename>buildhistory</filename> class
1010 enables all three features:
1011 <literallayout class='monospaced'>
1012 BUILDHISTORY_FEATURES ?= "image package sdk"
1013 </literallayout>
1014 </para>
1015 </glossdef>
1016 </glossentry>
1017
1018 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
1019 <glossdef>
1020 <para>
1021 When inheriting the
1022 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1023 class, specifies a list of paths to files copied from the
1024 image contents into the build history directory under
1025 an "image-files" directory in the directory for
1026 the image, so that you can track the contents of each file.
1027 The default is to copy <filename>/etc/passwd</filename>
1028 and <filename>/etc/group</filename>, which allows you to
1029 monitor for changes in user and group entries.
1030 You can modify the list to include any file.
1031 Specifying an invalid path does not produce an error.
1032 Consequently, you can include files that might
1033 not always be present.
1034 </para>
1035
1036 <para>
1037 By default, the <filename>buildhistory</filename> class
1038 provides paths to the following files:
1039 <literallayout class='monospaced'>
1040 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1041 </literallayout>
1042 </para>
1043 </glossdef>
1044 </glossentry>
1045
1046 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
1047 <glossdef>
1048 <para>
1049 When inheriting the
1050 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1051 class, optionally specifies a remote repository
1052 to which build history pushes Git changes.
1053 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
1054 to work,
1055 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1056 must be set to "1".
1057 </para>
1058
1059 <para>
1060 The repository should correspond to a remote
1061 address that specifies a repository as understood by
1062 Git, or alternatively to a remote name that you have
1063 set up manually using <filename>git remote</filename>
1064 within the local repository.
1065 </para>
1066
1067 <para>
1068 By default, the <filename>buildhistory</filename> class
1069 sets the variable as follows:
1070 <literallayout class='monospaced'>
1071 BUILDHISTORY_PUSH_REPO ?= ""
1072 </literallayout>
1073 </para>
1074 </glossdef>
1075 </glossentry>
1076
1077 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
1078 <glossdef>
1079 <para>
1080 Points to the location of the directory that holds build
1081 statistics when you use and enable the
1082 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
1083 class.
1084 The <filename>BUILDSTATS_BASE</filename> directory defaults
1085 to
1086 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
1087 </para>
1088 </glossdef>
1089 </glossentry>
1090
1091 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
1092 <glossdef>
1093 <para>
1094 For the BusyBox recipe, specifies whether to split the
1095 output executable file into two parts: one for features
1096 that require <filename>setuid root</filename>, and one for
1097 the remaining features (i.e. those that do not require
1098 <filename>setuid root</filename>).
1099 </para>
1100
1101 <para>
1102 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
1103 defaults to "1", which results in a single output
1104 executable file.
1105 Set the variable to "0" to split the output file.
1106 </para>
1107 </glossdef>
1108 </glossentry>
1109
1110 </glossdiv>
1111
1112 <glossdiv id='var-glossary-c'><title>C</title>
1113
1114 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
1115 <glossdef>
1116 <para>
1117 Flags passed to the C compiler for the target system.
1118 This variable evaluates to the same as
1119 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
1120 </para>
1121
1122 <para>
1123 For information on flags that help with creating more
1124 secure code, see the
1125 "<ulink url='&YOCTO_DOCS_DEV_URL;#making-images-more-secure'>Making Images More Secure</ulink>"
1126 section in the Yocto Project Development Manual.
1127 </para>
1128 </glossdef>
1129 </glossentry>
1130
1131 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
1132 <glossdef>
1133 <para>
1134 An internal variable specifying the special class override
1135 that should currently apply (e.g. "class-target",
1136 "class-native", and so forth).
1137 The classes that use this variable set it to
1138 appropriate values.
1139 </para>
1140
1141 <para>
1142 You do not normally directly interact with this variable.
1143 The value for the <filename>CLASSOVERRIDE</filename>
1144 variable goes into
1145 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1146 and then can be used as an override.
1147 Here is an example where "python-native" is added to
1148 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1149 only when building for the native case:
1150 <literallayout class='monospaced'>
1151 DEPENDS_append_class-native = " python-native"
1152 </literallayout>
1153 </para>
1154 </glossdef>
1155 </glossentry>
1156
1157 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
1158 <glossdef>
1159 <para>
1160 Provides a list of hardware features that are enabled in
1161 both
1162 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1163 and
1164 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1165 This select list of features contains features that make
1166 sense to be controlled both at the machine and distribution
1167 configuration level.
1168 For example, the "bluetooth" feature requires hardware
1169 support but should also be optional at the distribution
1170 level, in case the hardware supports Bluetooth but you
1171 do not ever intend to use it.
1172 </para>
1173
1174 <para>
1175 For more information, see the
1176 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1177 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
1178 variables.
1179 </para>
1180 </glossdef>
1181 </glossentry>
1182
1183 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
1184 <glossdef>
1185 <para>
1186 Points to <filename>meta/files/common-licenses</filename>
1187 in the
1188 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1189 which is where generic license files reside.
1190 </para>
1191 </glossdef>
1192 </glossentry>
1193
1194 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
1195 <glossdef>
1196 <para>A regular expression that resolves to one or more hosts
1197 (when the recipe is native) or one or more targets (when
1198 the recipe is non-native) with which a recipe is compatible.
1199 The regular expression is matched against
1200 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
1201 You can use the variable to stop recipes from being built
1202 for classes of systems with which the recipes are not
1203 compatible.
1204 Stopping these builds is particularly useful with kernels.
1205 The variable also helps to increase parsing speed
1206 since the build system skips parsing recipes not
1207 compatible with the current system.</para>
1208 </glossdef>
1209 </glossentry>
1210
1211 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
1212 <glossdef>
1213 <para>A regular expression that resolves to one or more
1214 target machines with which a recipe is compatible.
1215 The regular expression is matched against
1216 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
1217 You can use the variable to stop recipes from being built
1218 for machines with which the recipes are not compatible.
1219 Stopping these builds is particularly useful with kernels.
1220 The variable also helps to increase parsing speed
1221 since the build system skips parsing recipes not
1222 compatible with the current machine.</para>
1223 </glossdef>
1224 </glossentry>
1225
1226 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
1227 <glossdef>
1228 <para>
1229 Defines wildcards to match when installing a list of
1230 complementary packages for all the packages explicitly
1231 (or implicitly) installed in an image.
1232 The resulting list of complementary packages is associated
1233 with an item that can be added to
1234 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
1235 An example usage of this is the "dev-pkgs" item that when
1236 added to <filename>IMAGE_FEATURES</filename> will
1237 install -dev packages (containing headers and other
1238 development files) for every package in the image.
1239 </para>
1240
1241 <para>
1242 To add a new feature item pointing to a wildcard, use a
1243 variable flag to specify the feature item name and
1244 use the value to specify the wildcard.
1245 Here is an example:
1246 <literallayout class='monospaced'>
1247 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1248 </literallayout>
1249 </para>
1250 </glossdef>
1251 </glossentry>
1252
1253 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
1254 <glossdef>
1255 <para>
1256 Identifies editable or configurable files that are part of a package.
1257 If the Package Management System (PMS) is being used to update
1258 packages on the target system, it is possible that
1259 configuration files you have changed after the original installation
1260 and that you now want to remain unchanged are overwritten.
1261 In other words, editable files might exist in the package that you do not
1262 want reset as part of the package update process.
1263 You can use the <filename>CONFFILES</filename> variable to list the files in the
1264 package that you wish to prevent the PMS from overwriting during this update process.
1265 </para>
1266
1267 <para>
1268 To use the <filename>CONFFILES</filename> variable, provide a package name
1269 override that identifies the resulting package.
1270 Then, provide a space-separated list of files.
1271 Here is an example:
1272 <literallayout class='monospaced'>
1273 CONFFILES_${PN} += "${sysconfdir}/file1 \
1274 ${sysconfdir}/file2 ${sysconfdir}/file3"
1275 </literallayout>
1276 </para>
1277
1278 <para>
1279 A relationship exists between the <filename>CONFFILES</filename> and
1280 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
1281 The files listed within <filename>CONFFILES</filename> must be a subset of
1282 the files listed within <filename>FILES</filename>.
1283 Because the configuration files you provide with <filename>CONFFILES</filename>
1284 are simply being identified so that the PMS will not overwrite them,
1285 it makes sense that
1286 the files must already be included as part of the package through the
1287 <filename>FILES</filename> variable.
1288 </para>
1289
1290 <note>
1291 When specifying paths as part of the <filename>CONFFILES</filename> variable,
1292 it is good practice to use appropriate path variables.
1293 For example, <filename>${sysconfdir}</filename> rather than
1294 <filename>/etc</filename> or <filename>${bindir}</filename> rather
1295 than <filename>/usr/bin</filename>.
1296 You can find a list of these variables at the top of the
1297 <filename>meta/conf/bitbake.conf</filename> file in the
1298 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1299 </note>
1300 </glossdef>
1301 </glossentry>
1302
1303 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
1304 <glossdef>
1305 <para>
1306 Identifies the initial RAM disk (initramfs) source files.
1307 The OpenEmbedded build system receives and uses
1308 this kernel Kconfig variable as an environment variable.
1309 By default, the variable is set to null ("").
1310 </para>
1311
1312 <para>
1313 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
1314 either a single cpio archive with a
1315 <filename>.cpio</filename> suffix or a
1316 space-separated list of directories and files for building
1317 the initramfs image.
1318 A cpio archive should contain a filesystem archive
1319 to be used as an initramfs image.
1320 Directories should contain a filesystem layout to be
1321 included in the initramfs image.
1322 Files should contain entries according to the format
1323 described by the
1324 <filename>usr/gen_init_cpio</filename> program in the
1325 kernel tree.
1326 </para>
1327
1328 <para>
1329 If you specify multiple directories and files, the
1330 initramfs image will be the aggregate of all of them.
1331 </para>
1332 </glossdef>
1333 </glossentry>
1334
1335 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
1336 <glossdef>
1337 <para>
1338 A list of files that contains <filename>autoconf</filename> test results relevant
1339 to the current build.
1340 This variable is used by the Autotools utilities when running
1341 <filename>configure</filename>.
1342 </para>
1343 </glossdef>
1344 </glossentry>
1345
1346 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
1347 <glossdef>
1348 <para>
1349 When a recipe inherits the
1350 <filename>distro_features_check</filename> class, this
1351 variable identifies distribution features that would
1352 be in conflict should the recipe
1353 be built.
1354 In other words, if the
1355 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
1356 lists a feature that also appears in
1357 <filename>DISTRO_FEATURES</filename> within the
1358 current configuration, an error occurs and the
1359 build stops.
1360 </para>
1361 </glossdef>
1362 </glossentry>
1363
1364 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
1365 <glossdef>
1366 <para>
1367 If set to "1" along with the
1368 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1369 variable, the OpenEmbedded build system copies
1370 into the image the license files, which are located in
1371 <filename>/usr/share/common-licenses</filename>,
1372 for each package.
1373 The license files are placed
1374 in directories within the image itself.
1375 </para>
1376 </glossdef>
1377 </glossentry>
1378
1379 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
1380 <glossdef>
1381 <para>
1382 If set to "1", the OpenEmbedded build system copies
1383 the license manifest for the image to
1384 <filename>/usr/share/common-licenses/license.manifest</filename>
1385 within the image itself.
1386 </para>
1387 </glossdef>
1388 </glossentry>
1389
1390 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
1391 <glossdef>
1392 <para>
1393 Specifies the list of packages to be added to the image.
1394 You should only set this variable in the
1395 <filename>local.conf</filename> configuration file found
1396 in the
1397 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1398 </para>
1399
1400 <para>
1401 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
1402 </para>
1403 </glossdef>
1404 </glossentry>
1405
1406 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
1407 <glossdef>
1408 <para>
1409 Specifies the parent directory of the OpenEmbedded
1410 Core Metadata layer (i.e. <filename>meta</filename>).
1411 </para>
1412
1413 <para>
1414 It is an important distinction that
1415 <filename>COREBASE</filename> points to the parent of this
1416 layer and not the layer itself.
1417 Consider an example where you have cloned the Poky Git
1418 repository and retained the <filename>poky</filename>
1419 name for your local copy of the repository.
1420 In this case, <filename>COREBASE</filename> points to
1421 the <filename>poky</filename> folder because it is the
1422 parent directory of the <filename>poky/meta</filename>
1423 layer.
1424 </para>
1425 </glossdef>
1426 </glossentry>
1427
1428 </glossdiv>
1429
1430 <glossdiv id='var-glossary-d'><title>D</title>
1431
1432 <glossentry id='var-D'><glossterm>D</glossterm>
1433 <glossdef>
1434 <para>
1435 The destination directory.
1436 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1437 where components are installed by the <filename>do_install</filename> task.
1438 This location defaults to:
1439 <literallayout class='monospaced'>
1440 ${WORKDIR}/image
1441 </literallayout>
1442 </para>
1443 </glossdef>
1444 </glossentry>
1445
1446 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
1447 <glossdef>
1448 <para>
1449 The date and time on which the current build started.
1450 The format is suitable for timestamps.
1451 </para>
1452 </glossdef>
1453 </glossentry>
1454
1455 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
1456 <glossdef>
1457 <para>
1458 Specifies to build packages with debugging information.
1459 This influences the value of the
1460 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
1461 variable.
1462 </para>
1463 </glossdef>
1464 </glossentry>
1465
1466 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
1467 <glossdef>
1468 <para>
1469 The options to pass in
1470 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1471 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
1472 a system for debugging.
1473 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1474 </para>
1475 </glossdef>
1476 </glossentry>
1477
1478 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1479 <glossdef>
1480 <para>
1481 Specifies a weak bias for recipe selection priority.
1482 </para>
1483 <para>
1484 The most common usage of this is variable is to set
1485 it to "-1" within a recipe for a development version of a
1486 piece of software.
1487 Using the variable in this way causes the stable version
1488 of the recipe to build by default in the absence of
1489 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1490 being used to build the development version.
1491 </para>
1492 <note>
1493 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1494 is weak and is overridden by
1495 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1496 if that variable is different between two layers
1497 that contain different versions of the same recipe.
1498 </note>
1499 </glossdef>
1500 </glossentry>
1501
1502 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1503 <glossdef>
1504 <para>
1505 Lists a recipe's build-time dependencies
1506 (i.e. other recipe files).
1507 The system ensures that all the dependencies listed
1508 have been built and have their contents in the appropriate
1509 sysroots before the recipe's configure task is executed.
1510 </para>
1511
1512 <para>
1513 Consider this simple example for two recipes named "a" and
1514 "b" that produce similarly named packages.
1515 In this example, the <filename>DEPENDS</filename>
1516 statement appears in the "a" recipe:
1517 <literallayout class='monospaced'>
1518 DEPENDS = "b"
1519 </literallayout>
1520 Here, the dependency is such that the
1521 <filename>do_configure</filename> task for recipe "a"
1522 depends on the <filename>do_populate_sysroot</filename>
1523 task of recipe "b".
1524 This means anything that recipe "b" puts into sysroot
1525 is available when recipe "a" is configuring itself.
1526 </para>
1527
1528 <para>
1529 For information on runtime dependencies, see the
1530 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1531 variable.
1532 </para>
1533 </glossdef>
1534 </glossentry>
1535
1536 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
1537 <glossdef>
1538 <para>
1539 Points to the general area that the OpenEmbedded build
1540 system uses to place images, packages, SDKs and other output
1541 files that are ready to be used outside of the build system.
1542 By default, this directory resides within the
1543 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1544 as <filename>${TMPDIR}/deploy</filename>.
1545 </para>
1546
1547 <para>
1548 For more information on the structure of the Build
1549 Directory, see
1550 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1551 section.
1552 For more detail on the contents of the
1553 <filename>deploy</filename> directory, see the
1554 "<link linkend='images-dev-environment'>Images</link>" and
1555 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1556 sections.
1557 </para>
1558 </glossdef>
1559 </glossentry>
1560
1561 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
1562 <glossdef>
1563 <para>
1564 Points to the area that the OpenEmbedded build system uses
1565 to place images and other associated output files that are
1566 ready to be deployed onto the target machine.
1567 The directory is machine-specific as it contains the
1568 <filename>${MACHINE}</filename> name.
1569 By default, this directory resides within the
1570 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1571 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
1572 </para>
1573
1574 <para>
1575 For more information on the structure of the Build
1576 Directory, see
1577 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1578 section.
1579 For more detail on the contents of the
1580 <filename>deploy</filename> directory, see the
1581 "<link linkend='images-dev-environment'>Images</link>" and
1582 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1583 sections.
1584 </para>
1585 </glossdef>
1586 </glossentry>
1587
1588 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
1589 <glossdef>
1590 <para>
1591 For recipes that inherit the
1592 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
1593 class, the <filename>DEPLOYDIR</filename> points to a
1594 temporary work area for deployed files that is set in the
1595 <filename>deploy</filename> class as follows:
1596 <literallayout class='monospaced'>
1597 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
1598 </literallayout>
1599 Recipes inheriting the <filename>deploy</filename> class
1600 should copy files to be deployed into
1601 <filename>DEPLOYDIR</filename>, and the class will take
1602 care of copying them into
1603 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
1604 afterwards.
1605 </para>
1606 </glossdef>
1607 </glossentry>
1608
1609 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1610 <glossdef>
1611 <para>The package description used by package managers.
1612 If not set, <filename>DESCRIPTION</filename> takes
1613 the value of the
1614 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
1615 variable.
1616 </para>
1617 </glossdef>
1618 </glossentry>
1619
1620 <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm>
1621 <glossdef>
1622 <para>
1623 A 32-bit MBR disk signature used by
1624 <filename>directdisk</filename> images.
1625 </para>
1626
1627 <para>
1628 By default, the signature is set to an automatically
1629 generated random value that allows the OpenEmbedded
1630 build system to create a boot loader.
1631 You can override the signature in the image recipe
1632 by setting <filename>DISK_SIGNATURE</filename> to an
1633 8-digit hex string.
1634 You might want to override
1635 <filename>DISK_SIGNATURE</filename> if you want the disk
1636 signature to remain constant between image builds.
1637 </para>
1638
1639 <para>
1640 When using Linux 3.8 or later, you can use
1641 <filename>DISK_SIGNATURE</filename> to specify the root
1642 by UUID to allow the kernel to locate the root device
1643 even if the device name changes due to differences in
1644 hardware configuration.
1645 By default, <filename>SYSLINUX_ROOT</filename> is set
1646 as follows:
1647 <literallayout class='monospaced'>
1648 SYSLINUX_ROOT = "root=/dev/sda2"
1649 </literallayout>
1650 However, you can change this to locate the root device
1651 using the disk signature instead:
1652 <literallayout class='monospaced'>
1653 SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02"
1654 </literallayout>
1655 </para>
1656
1657 <para>
1658 As previously mentioned, it is possible to set the
1659 <filename>DISK_SIGNATURE</filename> variable in your
1660 <filename>local.conf</filename> file to a fixed
1661 value if you do not want <filename>syslinux.cfg</filename>
1662 changing for each build.
1663 You might find this useful when you want to upgrade the
1664 root filesystem on a device without having to recreate or
1665 modify the master boot record.
1666 </para>
1667 </glossdef>
1668 </glossentry>
1669
1670 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
1671 <glossdef>
1672 <para>
1673 The short name of the distribution.
1674 This variable corresponds to a distribution
1675 configuration file whose root name is the same as the
1676 variable's argument and whose filename extension is
1677 <filename>.conf</filename>.
1678 For example, the distribution configuration file for the
1679 Poky distribution is named <filename>poky.conf</filename>
1680 and resides in the
1681 <filename>meta-yocto/conf/distro</filename> directory of
1682 the
1683 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1684 </para>
1685
1686 <para>
1687 Within that <filename>poky.conf</filename> file, the
1688 <filename>DISTRO</filename> variable is set as follows:
1689 <literallayout class='monospaced'>
1690 DISTRO = "poky"
1691 </literallayout>
1692 </para>
1693
1694 <para>
1695 Distribution configuration files are located in a
1696 <filename>conf/distro</filename> directory within the
1697 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
1698 that contains the distribution configuration.
1699 The value for <filename>DISTRO</filename> must not contain
1700 spaces, and is typically all lower-case.
1701 <note>
1702 If the <filename>DISTRO</filename> variable is blank, a set
1703 of default configurations are used, which are specified
1704 within
1705 <filename>meta/conf/distro/defaultsetup.conf</filename>
1706 also in the Source Directory.
1707 </note>
1708 </para>
1709 </glossdef>
1710 </glossentry>
1711
1712 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
1713 <glossdef>
1714 <para>
1715 Specifies a list of distro-specific packages to add to all images.
1716 This variable takes affect through
1717 <filename>packagegroup-base</filename> so the
1718 variable only really applies to the more full-featured
1719 images that include <filename>packagegroup-base</filename>.
1720 You can use this variable to keep distro policy out of
1721 generic images.
1722 As with all other distro variables, you set this variable
1723 in the distro <filename>.conf</filename> file.
1724 </para>
1725 </glossdef>
1726 </glossentry>
1727
1728 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
1729 <glossdef>
1730 <para>
1731 Specifies a list of distro-specific packages to add to all images
1732 if the packages exist.
1733 The packages might not exist or be empty (e.g. kernel modules).
1734 The list of packages are automatically installed but you can
1735 remove them.
1736 </para>
1737 </glossdef>
1738 </glossentry>
1739
1740 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
1741 <glossdef>
1742 <para>
1743 The software support you want in your distribution for
1744 various features.
1745 You define your distribution features in the distribution
1746 configuration file.
1747 </para>
1748
1749 <para>
1750 In most cases, the presence or absence of a feature in
1751 <filename>DISTRO_FEATURES</filename> is translated to the
1752 appropriate option supplied to the configure script
1753 during <filename>do_configure</filename> for recipes that
1754 optionally support the feature.
1755 For example, specifying "x11" in
1756 <filename>DISTRO_FEATURES</filename>, causes
1757 every piece of software built for the target that can
1758 optionally support X11 to have its X11 support enabled.
1759 </para>
1760
1761 <para>
1762 Two more examples are Bluetooth and NFS support.
1763 For a more complete list of features that ships with the
1764 Yocto Project and that you can provide with this variable,
1765 see the
1766 "<link linkend='ref-features-distro'>Distro Features</link>"
1767 section.
1768 </para>
1769 </glossdef>
1770 </glossentry>
1771
1772 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
1773 <glossdef>
1774 <para>Features to be added to
1775 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
1776 if not also present in
1777 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1778 </para>
1779
1780 <para>
1781 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1782 It is not intended to be user-configurable.
1783 It is best to just reference the variable to see which distro features are
1784 being backfilled for all distro configurations.
1785 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1786 more information.
1787 </para>
1788 </glossdef>
1789 </glossentry>
1790
1791 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
1792 <glossdef>
1793 <para>Features from
1794 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
1795 that should not be backfilled (i.e. added to
1796 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
1797 during the build.
1798 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
1799 more information.
1800 </para>
1801 </glossdef>
1802 </glossentry>
1803
1804 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
1805 <glossdef>
1806 <para>The long name of the distribution.</para>
1807 </glossdef>
1808 </glossentry>
1809
1810 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
1811 <glossdef>
1812 <para>Alias names used for the recipe in various Linux distributions.</para>
1813 <para>See the
1814 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
1815 a Package Name Alias</ulink>" section in the Yocto Project Development
1816 Manual for more information.</para>
1817 </glossdef>
1818 </glossentry>
1819
1820 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
1821 <glossdef>
1822 <para>The version of the distribution.</para>
1823 </glossdef>
1824 </glossentry>
1825
1826 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
1827 <glossdef>
1828 <para>
1829 This variable lists overrides specific to the current
1830 distribution.
1831 By default, the variable list includes the value of the
1832 <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
1833 variable.
1834 You can extend the variable to apply any variable overrides
1835 you want as part of the distribution and are not
1836 already in <filename>OVERRIDES</filename> through
1837 some other means.
1838 </para>
1839 </glossdef>
1840 </glossentry>
1841
1842 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1843 <glossdef>
1844 <para>
1845 The central download directory used by the build process to
1846 store downloads.
1847 By default, <filename>DL_DIR</filename> gets files
1848 suitable for mirroring for everything except Git
1849 repositories.
1850 If you want tarballs of Git repositories, use the
1851 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1852 variable.
1853 </para>
1854
1855 <para>
1856 You can set this directory by defining the
1857 <filename>DL_DIR</filename> variable in the
1858 <filename>conf/local.conf</filename> file.
1859 This directory is self-maintaining and you should not have
1860 to touch it.
1861 By default, the directory is <filename>downloads</filename>
1862 in the
1863 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1864 <literallayout class='monospaced'>
1865 #DL_DIR ?= "${TOPDIR}/downloads"
1866 </literallayout>
1867 To specify a different download directory, simply remove
1868 the comment from the line and provide your directory.
1869 </para>
1870
1871 <para>
1872 During a first build, the system downloads many different
1873 source code tarballs from various upstream projects.
1874 Downloading can take a while, particularly if your network
1875 connection is slow.
1876 Tarballs are all stored in the directory defined by
1877 <filename>DL_DIR</filename> and the build system looks there
1878 first to find source tarballs.
1879 <note>
1880 When wiping and rebuilding, you can preserve this
1881 directory to speed up this part of subsequent
1882 builds.
1883 </note>
1884 </para>
1885
1886 <para>
1887 You can safely share this directory between multiple builds
1888 on the same development machine.
1889 For additional information on how the build process gets
1890 source files when working behind a firewall or proxy server,
1891 see this specific question in the
1892 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
1893 chapter.
1894 </para>
1895 </glossdef>
1896
1897 </glossentry>
1898 </glossdiv>
1899
1900 <glossdiv id='var-glossary-e'><title>E</title>
1901
1902 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
1903 <glossdef>
1904 <para></para>
1905 <para>Variable that controls which locales for
1906 <filename>eglibc</filename> are generated during the
1907 build (useful if the target device has 64Mbytes
1908 of RAM or less).</para>
1909 </glossdef>
1910 </glossentry>
1911
1912 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
1913 <glossdef>
1914 <para>
1915 Specifies the quality assurance checks whose failures are
1916 reported as errors by the OpenEmbedded build system.
1917 You set this variable in your distribution configuration
1918 file.
1919 For a list of the checks you can control with this variable,
1920 see the
1921 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1922 section.
1923 </para>
1924 </glossdef>
1925 </glossentry>
1926
1927 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
1928 <glossdef>
1929 <para>
1930 When used with the
1931 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
1932 class, specifies the path used for storing the debug files
1933 created by the
1934 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
1935 which allows you to submit build errors you encounter to a
1936 central database.
1937 By default, the value of this variable is
1938 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
1939 </para>
1940
1941 <para>
1942 You can set <filename>ERR_REPORT_DIR</filename> to the path
1943 you want the error reporting tool to store the debug files
1944 as follows in your <filename>local.conf</filename> file:
1945 <literallayout class='monospaced'>
1946 ERR_REPORT_DIR = "path"
1947 </literallayout>
1948 </para>
1949 </glossdef>
1950 </glossentry>
1951
1952 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1953 <glossdef>
1954 <para>
1955 Directs BitBake to exclude a recipe from world builds (i.e.
1956 <filename>bitbake world</filename>).
1957 During world builds, BitBake locates, parses and builds all
1958 recipes found in every layer exposed in the
1959 <filename>bblayers.conf</filename> configuration file.
1960 </para>
1961
1962 <para>
1963 To exclude a recipe from a world build using this variable,
1964 set the variable to "1" in the recipe.
1965 </para>
1966
1967 <note>
1968 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1969 may still be built during a world build in order to satisfy
1970 dependencies of other recipes.
1971 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1972 only ensures that the recipe is not explicitly added
1973 to the list of build targets in a world build.
1974 </note>
1975 </glossdef>
1976 </glossentry>
1977
1978 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
1979 <glossdef>
1980 <para>
1981 Used with file and pathnames to create a prefix for a recipe's
1982 version based on the recipe's
1983 <link linkend='var-PE'><filename>PE</filename></link> value.
1984 If <filename>PE</filename> is set and greater than zero for a recipe,
1985 <filename>EXTENDPE</filename> becomes that value (e.g if
1986 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
1987 becomes "1_").
1988 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
1989 zero, <filename>EXTENDPE</filename> becomes "".</para>
1990 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
1991 variable for an example.
1992 </para>
1993 </glossdef>
1994 </glossentry>
1995
1996 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
1997 <glossdef>
1998 <para>
1999 The full package version specification as it appears on the
2000 final packages produced by a recipe.
2001 The variable's value is normally used to fix a runtime
2002 dependency to the exact same version of another package
2003 in the same recipe:
2004 <literallayout class='monospaced'>
2005 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
2006 </literallayout>
2007 </para>
2008
2009 <para>
2010 The dependency relationships are intended to force the
2011 package manager to upgrade these types of packages in
2012 lock-step.
2013 </para>
2014 </glossdef>
2015 </glossentry>
2016
2017 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
2018 <glossdef>
2019 <para>
2020 If <filename>externalsrc.bbclass</filename> is inherited,
2021 this variable points to the source tree, which is
2022 outside of the OpenEmbedded build system.
2023 When set, this variable sets the
2024 <link linkend='var-S'><filename>S</filename></link>
2025 variable, which is what the OpenEmbedded build system uses
2026 to locate unpacked recipe source code.
2027 </para>
2028
2029 <para>
2030 For more information on
2031 <filename>externalsrc.bbclass</filename>, see the
2032 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2033 section.
2034 You can also find information on how to use this variable
2035 in the
2036 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2037 section in the Yocto Project Development Manual.
2038 </para>
2039 </glossdef>
2040 </glossentry>
2041
2042 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
2043 <glossdef>
2044 <para>
2045 If <filename>externalsrc.bbclass</filename> is inherited,
2046 this variable points to the directory in which the recipe's
2047 source code is built,
2048 which is outside of the OpenEmbedded build system.
2049 When set, this variable sets the
2050 <link linkend='var-B'><filename>B</filename></link>
2051 variable, which is what the OpenEmbedded build system uses
2052 to locate the Build Directory.
2053 </para>
2054
2055 <para>
2056 For more information on
2057 <filename>externalsrc.bbclass</filename>, see the
2058 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2059 section.
2060 You can also find information on how to use this variable
2061 in the
2062 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2063 section in the Yocto Project Development Manual.
2064 </para>
2065 </glossdef>
2066 </glossentry>
2067
2068 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
2069 <glossdef>
2070 <para>
2071 The list of additional features to include in an image.
2072 Typically, you configure this variable in your
2073 <filename>local.conf</filename> file, which is found in the
2074 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2075 Although you can use this variable from within a recipe,
2076 best practices dictate that you do not.
2077 <note>
2078 To enable primary features from within the image
2079 recipe, use the
2080 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2081 variable.
2082 </note>
2083 </para>
2084
2085 <para>
2086 Here are some examples of features you can add:
2087 <literallayout class='monospaced'>
2088"dbg-pkgs" - Adds -dbg packages for all installed packages
2089 including symbol information for debugging and
2090 profiling.
2091
2092"debug-tweaks" - Makes an image suitable for development.
2093 For example, ssh root access has a blank
2094 password. You should remove this feature
2095 before you produce a production image.
2096
2097"dev-pkgs" - Adds -dev packages for all installed packages.
2098 This is useful if you want to develop against
2099 the libraries in the image.
2100
2101"read-only-rootfs" - Creates an image whose root
2102 filesystem is read-only. See the
2103 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
2104 section in the Yocto Project
2105 Development Manual for more
2106 information
2107
2108"tools-debug" - Adds debugging tools such as gdb and
2109 strace.
2110
2111"tools-profile" - Adds profiling tools such as oprofile,
2112 exmap, lttng and valgrind (x86 only).
2113
2114"tools-sdk" - Adds development tools such as gcc, make,
2115 pkgconfig and so forth.
2116
2117"tools-testapps" - Adds useful testing tools such as
2118 ts_print, aplay, arecord and so
2119 forth.
2120
2121 </literallayout>
2122 </para>
2123
2124 <para>
2125 For a complete list of image features that ships with the
2126 Yocto Project, see the
2127 "<link linkend="ref-features-image">Image Features</link>"
2128 section.
2129 </para>
2130
2131 <para>
2132 For an example that shows how to customize your image by
2133 using this variable, see the
2134 "<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>"
2135 section in the Yocto Project Development Manual.
2136 </para>
2137 </glossdef>
2138 </glossentry>
2139
2140 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
2141 <glossdef>
2142 <para>A list of recipes to build that do not provide packages
2143 for installing into the root filesystem.
2144 </para>
2145 <para>Sometimes a recipe is required to build the final image but is not
2146 needed in the root filesystem.
2147 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
2148 list these recipes and thus specify the dependencies.
2149 A typical example is a required bootloader in a machine configuration.
2150 </para>
2151 <note>
2152 To add packages to the root filesystem, see the various
2153 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
2154 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
2155 variables.
2156 </note>
2157 </glossdef>
2158 </glossentry>
2159
2160 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
2161 <glossdef>
2162 <para>Additional <filename>cmake</filename> options.</para>
2163 </glossdef>
2164 </glossentry>
2165
2166 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
2167 <glossdef>
2168 <para>Additional <filename>configure</filename> script options.</para>
2169 </glossdef>
2170 </glossentry>
2171
2172 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
2173 <glossdef>
2174 <para>Additional GNU <filename>make</filename> options.</para>
2175 </glossdef>
2176 </glossentry>
2177
2178 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
2179 <glossdef>
2180 <para>
2181 When a recipe inherits the
2182 <link linkend='ref-classes-scons'><filename>scons</filename></link>
2183 class, this variable specifies additional configuration
2184 options you want to pass to the
2185 <filename>scons</filename> command line.
2186 </para>
2187 </glossdef>
2188 </glossentry>
2189
2190 <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>EXTRA_QMAKEVARS_POST</glossterm>
2191 <glossdef>
2192 <para>
2193 Configuration variables or options you want to pass to
2194 <filename>qmake</filename>.
2195 Use this variable when the arguments need to be after the
2196 <filename>.pro</filename> file list on the command line.
2197 </para>
2198
2199 <para>
2200 This variable is used with recipes that inherit the
2201 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2202 class or other classes that inherit
2203 <filename>qmake_base</filename>.
2204 </para>
2205 </glossdef>
2206 </glossentry>
2207
2208 <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>EXTRA_QMAKEVARS_PRE</glossterm>
2209 <glossdef>
2210 <para>
2211 Configuration variables or options you want to pass to
2212 <filename>qmake</filename>.
2213 Use this variable when the arguments need to be before the
2214 <filename>.pro</filename> file list on the command line.
2215 </para>
2216
2217 <para>
2218 This variable is used with recipes that inherit the
2219 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2220 class or other classes that inherit
2221 <filename>qmake_base</filename>.
2222 </para>
2223 </glossdef>
2224 </glossentry>
2225
2226 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
2227 <glossdef>
2228 <para>
2229 When a recipe inherits the
2230 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
2231 class, this variable provides image level user and group
2232 operations.
2233 This is a more global method of providing user and group
2234 configuration as compared to using the
2235 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
2236 class, which ties user and group configurations to a
2237 specific recipe.
2238 </para>
2239
2240 <para>
2241 The set list of commands you can configure using the
2242 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
2243 <filename>extrausers</filename> class.
2244 These commands map to the normal Unix commands of the same
2245 names:
2246 <literallayout class='monospaced'>
2247 # EXTRA_USERS_PARAMS = "\
2248 # useradd -p '' tester; \
2249 # groupadd developers; \
2250 # userdel nobody; \
2251 # groupdel -g video; \
2252 # groupmod -g 1020 developers; \
2253 # usermod -s /bin/sh tester; \
2254 # "
2255 </literallayout>
2256 </para>
2257 </glossdef>
2258 </glossentry>
2259
2260 </glossdiv>
2261
2262 <glossdiv id='var-glossary-f'><title>F</title>
2263
2264 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
2265 <glossdef>
2266 <para>
2267 Defines one or more packages to include in an image when
2268 a specific item is included in
2269 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2270 When setting the value, <filename>FEATURE_PACKAGES</filename>
2271 should have the name of the feature item as an override.
2272 Here is an example:
2273 <literallayout class='monospaced'>
2274 FEATURE_PACKAGES_widget = "package1 package2"
2275 </literallayout>
2276 In this example, if "widget" were added to
2277 <filename>IMAGE_FEATURES</filename>, "package1" and
2278 "package2" would be included in the image.
2279 <note>
2280 Packages installed by features defined through
2281 <filename>FEATURE_PACKAGES</filename> are often package
2282 groups.
2283 While similarly named, you should not confuse the
2284 <filename>FEATURE_PACKAGES</filename> variable with
2285 package groups, which are discussed elsewhere in the
2286 documentation.
2287 </note>
2288 </para>
2289 </glossdef>
2290 </glossentry>
2291
2292 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
2293 <glossdef>
2294 <para>
2295 Points to the base URL of the server and location within
2296 the document-root that provides the metadata and
2297 packages required by OPKG to support runtime package
2298 management of IPK packages.
2299 You set this variable in your
2300 <filename>local.conf</filename> file.
2301 </para>
2302
2303 <para>
2304 Consider the following example:
2305 <literallayout class='monospaced'>
2306 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2307 </literallayout>
2308 This example assumes you are serving your packages over
2309 HTTP and your databases are located in a directory
2310 named <filename>BOARD-dir</filename>, which is underneath
2311 your HTTP server's document-root.
2312 In this case, the OpenEmbedded build system generates a set
2313 of configuration files for you in your target that work
2314 with the feed.
2315 </para>
2316 </glossdef>
2317 </glossentry>
2318
2319 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
2320 <glossdef>
2321 <para>
2322 The list of directories or files that are placed in packages.
2323 </para>
2324
2325 <para>
2326 To use the <filename>FILES</filename> variable, provide a package name
2327 override that identifies the resulting package.
2328 Then, provide a space-separated list of files or paths that identifies the
2329 files you want included as part of the resulting package.
2330 Here is an example:
2331 <literallayout class='monospaced'>
2332 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
2333 </literallayout>
2334 </para>
2335
2336 <note>
2337 When specifying paths as part of the <filename>FILES</filename> variable,
2338 it is good practice to use appropriate path variables.
2339 For example, use <filename>${sysconfdir}</filename> rather than
2340 <filename>/etc</filename>, or <filename>${bindir}</filename> rather
2341 than <filename>/usr/bin</filename>.
2342 You can find a list of these variables at the top of the
2343 <filename>meta/conf/bitbake.conf</filename> file in the
2344 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2345 </note>
2346
2347 <para>
2348 If some of the files you provide with the <filename>FILES</filename> variable
2349 are editable and you know they should not be
2350 overwritten during the package update process by the Package Management
2351 System (PMS), you can identify these files so that the PMS will not
2352 overwrite them.
2353 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
2354 variable for information on how to identify these files to the PMS.
2355 </para>
2356
2357 </glossdef>
2358 </glossentry>
2359
2360 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
2361 <glossdef>
2362 <para>
2363 Extends the search path the OpenEmbedded build system uses
2364 when looking for files and patches as it processes recipes
2365 and append files.
2366 The default directories BitBake uses when it processes
2367 recipes are initially defined by the
2368 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2369 variable.
2370 You can extend <filename>FILESPATH</filename> variable
2371 by using <filename>FILESEXTRAPATHS</filename>.
2372 </para>
2373
2374 <para>
2375 Best practices dictate that you accomplish this by using
2376 <filename>FILESEXTRAPATHS</filename> from within a
2377 <filename>.bbappend</filename> file and that you prepend
2378 paths as follows:
2379 <literallayout class='monospaced'>
2380 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2381 </literallayout>
2382 In the above example, the build system first looks for files
2383 in a directory that has the same name as the corresponding
2384 append file.
2385 <note>
2386 <para>When extending <filename>FILESEXTRAPATHS</filename>,
2387 be sure to use the immediate expansion
2388 (<filename>:=</filename>) operator.
2389 Immediate expansion makes sure that BitBake evaluates
2390 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
2391 at the time the directive is encountered rather than at
2392 some later time when expansion might result in a
2393 directory that does not contain the files you need.
2394 </para>
2395 <para>Also, include the trailing separating colon
2396 character if you are prepending.
2397 The trailing colon character is necessary because you
2398 are directing BitBake to extend the path by prepending
2399 directories to the search path.</para>
2400 </note>
2401 Here is another common use:
2402 <literallayout class='monospaced'>
2403 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
2404 </literallayout>
2405 In this example, the build system extends the
2406 <filename>FILESPATH</filename> variable to include a
2407 directory named <filename>files</filename> that is in the
2408 same directory as the corresponding append file.
2409 </para>
2410
2411 <para>
2412 Here is a final example that specifically adds three paths:
2413 <literallayout class='monospaced'>
2414 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
2415 </literallayout>
2416 </para>
2417
2418 <para>
2419 By prepending paths in <filename>.bbappend</filename>
2420 files, you allow multiple append files that reside in
2421 different layers but are used for the same recipe to
2422 correctly extend the path.
2423 </para>
2424 </glossdef>
2425 </glossentry>
2426
2427 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
2428 <glossdef>
2429 <para>
2430 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2431 used by the OpenEmbedded build system for creating
2432 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
2433 You can find more information on how overrides are handled
2434 in the BitBake Manual that is located at
2435 <filename>bitbake/doc/manual</filename> in the
2436 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2437 </para>
2438
2439 <para>
2440 By default, the <filename>FILESOVERRIDES</filename>
2441 variable is defined as:
2442 <literallayout class='monospaced'>
2443 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2444 </literallayout>
2445
2446 <note>
2447 Do not hand-edit the <filename>FILESOVERRIDES</filename>
2448 variable.
2449 The values match up with expected overrides and are
2450 used in an expected manner by the build system.
2451 </note>
2452 </para>
2453 </glossdef>
2454 </glossentry>
2455
2456 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
2457 <glossdef>
2458 <para>
2459 The default set of directories the OpenEmbedded build system
2460 uses when searching for patches and files.
2461 During the build process, BitBake searches each directory in
2462 <filename>FILESPATH</filename> in the specified order when
2463 looking for files and patches specified by each
2464 <filename>file://</filename> URI in a recipe.
2465 </para>
2466
2467 <para>
2468 The default value for the <filename>FILESPATH</filename>
2469 variable is defined in the <filename>base.bbclass</filename>
2470 class found in <filename>meta/classes</filename> in the
2471 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2472 <literallayout class='monospaced'>
2473 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2474 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2475 </literallayout>
2476 <note>
2477 Do not hand-edit the <filename>FILESPATH</filename>
2478 variable.
2479 If you want the build system to look in directories
2480 other than the defaults, extend the
2481 <filename>FILESPATH</filename> variable by using the
2482 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2483 variable.
2484 </note>
2485 Be aware that the default <filename>FILESPATH</filename>
2486 directories do not map to directories in custom layers
2487 where append files (<filename>.bbappend</filename>)
2488 are used.
2489 If you want the build system to find patches or files
2490 that reside with your append files, you need to extend
2491 the <filename>FILESPATH</filename> variable by using
2492 the
2493 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2494 variable.
2495 </para>
2496 </glossdef>
2497 </glossentry>
2498
2499 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
2500 <glossdef>
2501 <para>Allows you to define your own file permissions settings table as part of
2502 your configuration for the packaging process.
2503 For example, suppose you need a consistent set of custom permissions for
2504 a set of groups and users across an entire work project.
2505 It is best to do this in the packages themselves but this is not always
2506 possible.
2507 </para>
2508 <para>
2509 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
2510 is located in the <filename>meta/files</filename> folder in the
2511 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2512 If you create your own file permissions setting table, you should place it in your
2513 layer or the distro's layer.
2514 </para>
2515 <para>
2516 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
2517 <filename>conf/local.conf</filename> file, which is found in the
2518 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
2519 point to your custom <filename>fs-perms.txt</filename>.
2520 You can specify more than a single file permissions setting table.
2521 The paths you specify to these files must be defined within the
2522 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
2523 </para>
2524 <para>
2525 For guidance on how to create your own file permissions settings table file,
2526 examine the existing <filename>fs-perms.txt</filename>.
2527 </para>
2528 </glossdef>
2529 </glossentry>
2530
2531 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
2532 <glossdef>
2533 <para>
2534 When a recipe inherits the
2535 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
2536 class, this variable identifies packages containing font
2537 files that need to be cached by Fontconfig.
2538 By default, the <filename>fontcache</filename> class assumes
2539 that fonts are in the recipe's main package
2540 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2541 Use this variable if fonts you need are in a package
2542 other than that main package.
2543 </para>
2544 </glossdef>
2545 </glossentry>
2546
2547 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
2548 <glossdef>
2549 <para>
2550 The options to pass in
2551 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
2552 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
2553 when compiling an optimized system.
2554 This variable defaults to
2555 "-O2 -pipe ${DEBUG_FLAGS}".
2556 </para>
2557 </glossdef>
2558 </glossentry>
2559 </glossdiv>
2560
2561 <glossdiv id='var-glossary-g'><title>G</title>
2562
2563 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
2564 <glossdef>
2565 <para>
2566 When a recipe inherits the
2567 <filename>useradd</filename> class, this variable
2568 specifies for a package what parameters should be passed
2569 to the <filename>groupadd</filename> command
2570 if you wish to add a group to the system when the package
2571 is installed.
2572 </para>
2573
2574 <para>
2575 Here is an example from the <filename>dbus</filename>
2576 recipe:
2577 <literallayout class='monospaced'>
2578 GROUPADD_PARAM_${PN} = "-r netdev"
2579 </literallayout>
2580 For information on the standard Linux shell command
2581 <filename>groupadd</filename>, see
2582 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
2583 </para>
2584 </glossdef>
2585 </glossentry>
2586
2587 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
2588 <glossdef>
2589 <para>
2590 When a recipe inherits the
2591 <filename>useradd</filename> class, this variable
2592 specifies for a package what parameters should be passed
2593 to the <filename>groupmems</filename> command
2594 if you wish to modify the members of a group when the
2595 package is installed.
2596 </para>
2597
2598 <para>
2599 For information on the standard Linux shell command
2600 <filename>groupmems</filename>, see
2601 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
2602 </para>
2603 </glossdef>
2604 </glossentry>
2605
2606 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
2607 <glossdef>
2608 <para>
2609 Configures the GNU GRand Unified Bootloader (GRUB) to have
2610 graphics and serial in the boot menu.
2611 Set this variable to "1" in your
2612 <filename>local.conf</filename> or distribution
2613 configuration file to enable graphics and serial
2614 in the menu.
2615 </para>
2616
2617 <para>
2618 See the
2619 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2620 class for more information on how this variable is used.
2621 </para>
2622 </glossdef>
2623 </glossentry>
2624
2625 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
2626 <glossdef>
2627 <para>
2628 Additional options to add to the GNU GRand Unified
2629 Bootloader (GRUB) configuration.
2630 Use a semi-colon character (<filename>;</filename>) to
2631 separate multiple options.
2632 </para>
2633
2634 <para>
2635 The <filename>GRUB_OPTS</filename> variable is optional.
2636 See the
2637 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2638 class for more information on how this variable is used.
2639 </para>
2640 </glossdef>
2641 </glossentry>
2642
2643 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
2644 <glossdef>
2645 <para>
2646 Specifies the timeout before executing the default
2647 <filename>LABEL</filename> in the GNU GRand Unified
2648 Bootloader (GRUB).
2649 </para>
2650
2651 <para>
2652 The <filename>GRUB_TIMEOUT</filename> variable is optional.
2653 See the
2654 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2655 class for more information on how this variable is used.
2656 </para>
2657 </glossdef>
2658 </glossentry>
2659
2660 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
2661 <glossdef>
2662 <para>
2663 For recipes that inherit the
2664 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
2665 class, this variable specifies the packages that contain the
2666 GTK+ input method modules being installed when the modules
2667 are in packages other than the main package.
2668 </para>
2669 </glossdef>
2670 </glossentry>
2671
2672 </glossdiv>
2673
2674 <glossdiv id='var-glossary-h'><title>H</title>
2675
2676 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
2677 <glossdef>
2678 <para>Website where more information about the software the recipe is building
2679 can be found.</para>
2680 </glossdef>
2681 </glossentry>
2682
2683 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
2684 <glossdef>
2685 <para>
2686 Specifies the system, including the architecture and the
2687 operating system, for with the build is occurring
2688 in the context of the current
2689 recipe.
2690 The OpenEmbedded build system automatically sets this
2691 variable.
2692 You do not need to set the variable yourself.
2693 </para>
2694
2695 <para>
2696 Here are two examples:
2697 <itemizedlist>
2698 <listitem><para>Given a native recipe on a 32-bit
2699 x86 machine running Linux, the value is
2700 "i686-linux".
2701 </para></listitem>
2702 <listitem><para>Given a recipe being built for a
2703 little-endian MIPS target running Linux,
2704 the value might be "mipsel-linux".
2705 </para></listitem>
2706 </itemizedlist>
2707 </para>
2708 </glossdef>
2709 </glossentry>
2710
2711 </glossdiv>
2712
2713 <glossdiv id='var-glossary-i'><title>I</title>
2714
2715 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
2716 <glossdef>
2717 <para>
2718 Disables or enables the <filename>icecc</filename>
2719 (Icecream) function.
2720 For more information on this function and best practices
2721 for using this variable, see the
2722 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
2723 section.
2724 </para>
2725
2726 <para>
2727 Setting this variable to "1" in your
2728 <filename>local.conf</filename> disables the function:
2729 <literallayout class='monospaced'>
2730 ICECC_DISABLED ??= "1"
2731 </literallayout>
2732 To enable the function, set the variable as follows:
2733 <literallayout class='monospaced'>
2734 ICECC_DISABLED = ""
2735 </literallayout>
2736 </para>
2737 </glossdef>
2738 </glossentry>
2739
2740 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
2741 <glossdef>
2742 <para>
2743 Points to the <filename>icecc-create-env</filename> script
2744 that you provide.
2745 This variable is used by the
2746 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2747 class.
2748 You set this variable in your
2749 <filename>local.conf</filename> file.
2750 </para>
2751
2752 <para>
2753 If you do not point to a script that you provide, the
2754 OpenEmbedded build system uses the default script provided
2755 by the <filename>icecc-create-env.bb</filename> recipe,
2756 which is a modified version and not the one that comes with
2757 <filename>icecc</filename>.
2758 </para>
2759 </glossdef>
2760 </glossentry>
2761
2762 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
2763 <glossdef>
2764 <para>
2765 Extra options passed to the <filename>make</filename>
2766 command during the <filename>do_compile</filename> task
2767 that specify parallel compilation.
2768 This variable usually takes the form of
2769 <filename>-j 4</filename>, where the number
2770 represents the maximum number of parallel threads
2771 <filename>make</filename> can run.
2772 <note>
2773 The options passed affect builds on all enabled
2774 machines on the network, which are machines running the
2775 <filename>iceccd</filename> daemon.
2776 </note>
2777 </para>
2778
2779 <para>
2780 If your enabled machines support multiple cores,
2781 coming up with the maximum number of parallel threads
2782 that gives you the best performance could take some
2783 experimentation since machine speed, network lag,
2784 available memory, and existing machine loads can all
2785 affect build time.
2786 Consequently, unlike the
2787 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
2788 variable, there is no rule-of-thumb for setting
2789 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
2790 optimal performance.
2791 </para>
2792
2793 <para>
2794 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
2795 the build system does not use it (i.e. the system does
2796 not detect and assign the number of cores as is done with
2797 <filename>PARALLEL_MAKE</filename>).
2798 </para>
2799 </glossdef>
2800 </glossentry>
2801
2802 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
2803 <glossdef>
2804 <para>
2805 The location of the <filename>icecc</filename> binary.
2806 You can set this variable in your
2807 <filename>local.conf</filename> file.
2808 If your <filename>local.conf</filename> file does not define
2809 this variable, the
2810 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2811 class attempts to define it by locating
2812 <filename>icecc</filename> using <filename>which</filename>.
2813 </para>
2814 </glossdef>
2815 </glossentry>
2816
2817 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
2818 <glossdef>
2819 <para>
2820 Identifies user classes that you do not want the
2821 Icecream distributed compile support to consider.
2822 This variable is used by the
2823 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2824 class.
2825 You set this variable in your
2826 <filename>local.conf</filename> file.
2827 </para>
2828
2829 <para>
2830 When you list classes using this variable, you are
2831 "blacklisting" them from distributed compilation across
2832 remote hosts.
2833 Any classes you list will be distributed and compiled
2834 locally.
2835 </para>
2836 </glossdef>
2837 </glossentry>
2838
2839 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
2840 <glossdef>
2841 <para>
2842 Identifies user recipes that you do not want the
2843 Icecream distributed compile support to consider.
2844 This variable is used by the
2845 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2846 class.
2847 You set this variable in your
2848 <filename>local.conf</filename> file.
2849 </para>
2850
2851 <para>
2852 When you list packages using this variable, you are
2853 "blacklisting" them from distributed compilation across
2854 remote hosts.
2855 Any packages you list will be distributed and compiled
2856 locally.
2857 </para>
2858 </glossdef>
2859 </glossentry>
2860
2861 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
2862 <glossdef>
2863 <para>
2864 Identifies user recipes that use an empty
2865 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
2866 variable that you want to force remote distributed
2867 compilation on using the Icecream distributed compile
2868 support.
2869 This variable is used by the
2870 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2871 class.
2872 You set this variable in your
2873 <filename>local.conf</filename> file.
2874 </para>
2875 </glossdef>
2876 </glossentry>
2877
2878 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
2879 <glossdef>
2880 <para>
2881 The base name of image output files.
2882 This variable defaults to the recipe name
2883 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2884 </para>
2885 </glossdef>
2886 </glossentry>
2887
2888 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
2889 <glossdef>
2890 <para>
2891 A list of classes that all images should inherit.
2892 You typically use this variable to specify the list of
2893 classes that register the different types of images
2894 the OpenEmbedded build system creates.
2895 </para>
2896
2897 <para>
2898 The default value for <filename>IMAGE_CLASSES</filename> is
2899 <filename>image_types</filename>.
2900 You can set this variable in your
2901 <filename>local.conf</filename> or in a distribution
2902 configuration file.
2903 </para>
2904
2905 <para>
2906 For more information, see
2907 <filename>meta/classes/image_types.bbclass</filename> in the
2908 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2909 </para>
2910 </glossdef>
2911 </glossentry>
2912
2913 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
2914 <glossdef>
2915 <para>
2916 The primary list of features to include in an image.
2917 Typically, you configure this variable in an image recipe.
2918 Although you can use this variable from your
2919 <filename>local.conf</filename> file, which is found in the
2920 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
2921 best practices dictate that you do not.
2922 <note>
2923 To enable extra features from outside the image recipe,
2924 use the
2925 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
2926 </note>
2927 For a list of image features that ships with the Yocto
2928 Project, see the
2929 "<link linkend="ref-features-image">Image Features</link>"
2930 section.
2931 </para>
2932
2933 <para>
2934 For an example that shows how to customize your image by
2935 using this variable, see the
2936 "<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>"
2937 section in the Yocto Project Development Manual.
2938 </para>
2939 </glossdef>
2940 </glossentry>
2941
2942 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
2943 <glossdef>
2944 <para>
2945 Specifies the formats the OpenEmbedded build system uses
2946 during the build when creating the root filesystem.
2947 For example, setting <filename>IMAGE_FSTYPES</filename>
2948 as follows causes the build system to create root
2949 filesystems using two formats: <filename>.ext3</filename>
2950 and <filename>.tar.bz2</filename>:
2951 <literallayout class='monospaced'>
2952 IMAGE_FSTYPES = "ext3 tar.bz2"
2953 </literallayout>
2954 For the complete list of supported image formats from which
2955 you can choose, see
2956 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
2957 </para>
2958
2959 <note>
2960 If you add "live" to <filename>IMAGE_FSTYPES</filename>
2961 inside an image recipe, be sure that you do so prior to the
2962 "inherit image" line of the recipe or the live image will
2963 not build.
2964 </note>
2965
2966 <note>
2967 Due to the way this variable is processed, it is not
2968 possible to update its contents using
2969 <filename>_append</filename> or
2970 <filename>_prepend</filename>. To add one or more
2971 additional options to this variable the
2972 <filename>+=</filename> operator must be used.
2973 </note>
2974 </glossdef>
2975 </glossentry>
2976
2977 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
2978 <glossdef>
2979 <para>
2980 Specifies the packages to install into an image.
2981 The <filename>IMAGE_INSTALL</filename> variable is a
2982 mechanism for an image recipe and you should use it
2983 with care to avoid ordering issues.
2984 <note>
2985 When working with an
2986 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
2987 image, do not use the <filename>IMAGE_INSTALL</filename>
2988 variable to specify packages for installation.
2989 Instead, use the
2990 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
2991 variable, which allows the initial RAM disk (initramfs)
2992 recipe to use a fixed set of packages and not be
2993 affected by <filename>IMAGE_INSTALL</filename>.
2994 </note>
2995 </para>
2996
2997 <para>
2998 Image recipes set <filename>IMAGE_INSTALL</filename>
2999 to specify the packages to install into an image through
3000 <filename>image.bbclass</filename>.
3001 Additionally, "helper" classes exist, such as
3002 <filename>core-image.bbclass</filename>, that can take
3003 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
3004 lists and turn these into auto-generated entries in
3005 <filename>IMAGE_INSTALL</filename> in addition to its
3006 default contents.
3007 </para>
3008
3009 <para>
3010 Using <filename>IMAGE_INSTALL</filename> with the
3011 <filename>+=</filename> operator from the
3012 <filename>/conf/local.conf</filename> file or from within
3013 an image recipe is not recommended as it can cause ordering
3014 issues.
3015 Since <filename>core-image.bbclass</filename> sets
3016 <filename>IMAGE_INSTALL</filename> to a default value using
3017 the <filename>?=</filename> operator, using a
3018 <filename>+=</filename> operation against
3019 <filename>IMAGE_INSTALL</filename> will result in
3020 unexpected behavior when used in
3021 <filename>conf/local.conf</filename>.
3022 Furthermore, the same operation from within an image
3023 recipe may or may not succeed depending on the specific
3024 situation.
3025 In both these cases, the behavior is contrary to how most
3026 users expect the <filename>+=</filename> operator to work.
3027 </para>
3028
3029 <para>
3030 When you use this variable, it is best to use it as follows:
3031 <literallayout class='monospaced'>
3032 IMAGE_INSTALL_append = " package-name"
3033 </literallayout>
3034 Be sure to include the space between the quotation character
3035 and the start of the package name or names.
3036 </para>
3037 </glossdef>
3038 </glossentry>
3039
3040 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
3041 <glossdef>
3042 <para>
3043 Specifies the list of locales to install into the image
3044 during the root filesystem construction process.
3045 The OpenEmbedded build system automatically splits locale
3046 files, which are used for localization, into separate
3047 packages.
3048 Setting the <filename>IMAGE_LINGUAS</filename> variable
3049 ensures that any locale packages that correspond to packages
3050 already selected for installation into the image are also
3051 installed.
3052 Here is an example:
3053 <literallayout class='monospaced'>
3054 IMAGE_LINGUAS = "pt-br de-de"
3055 </literallayout>
3056 In this example, the build system ensures any Brazilian
3057 Portuguese and German locale files that correspond to
3058 packages in the image are installed (i.e.
3059 <filename>*-locale-pt-br</filename>
3060 and <filename>*-locale-de-de</filename> as well as
3061 <filename>*-locale-pt</filename>
3062 and <filename>*-locale-de</filename>, since some software
3063 packages only provide locale files by language and not by
3064 country-specific language).
3065 </para>
3066 </glossdef>
3067 </glossentry>
3068
3069 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
3070 <glossdef>
3071 <para>
3072 The manifest file for the image.
3073 This file lists all the installed packages that make up
3074 the image.
3075 The file contains package information on a line-per-package
3076 basis as follows:
3077 <literallayout class='monospaced'>
3078 &lt;packagename&gt; &lt;packagearch&gt; &lt;version&gt;
3079 </literallayout>
3080 </para>
3081
3082 <para>
3083 The
3084 <link linkend='ref-classes-image'><filename>image</filename></link>
3085 class defines the manifest file as follows:
3086 <literallayout class='monospaced'>
3087 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
3088 </literallayout>
3089 The location is derived using the
3090 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3091 and
3092 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
3093 variables.
3094 You can find information on how the image
3095 is created in the
3096 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
3097 section.
3098 </para>
3099 </glossdef>
3100 </glossentry>
3101
3102 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
3103 <glossdef>
3104 <para>
3105 The name of the output image files minus the extension.
3106 This variable is derived using the
3107 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
3108 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3109 and
3110 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3111 variables:
3112 <literallayout class='monospaced'>
3113 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
3114 </literallayout>
3115 </para>
3116 </glossdef>
3117 </glossentry>
3118
3119 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
3120 <glossdef>
3121 <para>
3122 Defines a multiplier that the build system applies to the initial image
3123 size for cases when the multiplier times the returned disk usage value
3124 for the image is greater than the sum of
3125 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3126 and
3127 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
3128 The result of the multiplier applied to the initial image size creates
3129 free disk space in the image as overhead.
3130 By default, the build process uses a multiplier of 1.3 for this variable.
3131 This default value results in 30% free disk space added to the image when this
3132 method is used to determine the final generated image size.
3133 You should be aware that post install scripts and the package management
3134 system uses disk space inside this overhead area.
3135 Consequently, the multiplier does not produce an image with
3136 all the theoretical free disk space.
3137 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3138 for information on how the build system determines the overall image size.
3139 </para>
3140
3141 <para>
3142 The default 30% free disk space typically gives the image enough room to boot
3143 and allows for basic post installs while still leaving a small amount of
3144 free disk space.
3145 If 30% free space is inadequate, you can increase the default value.
3146 For example, the following setting gives you 50% free space added to the image:
3147 <literallayout class='monospaced'>
3148 IMAGE_OVERHEAD_FACTOR = "1.5"
3149 </literallayout>
3150 </para>
3151
3152 <para>
3153 Alternatively, you can ensure a specific amount of free disk space is added
3154 to the image by using the
3155 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3156 variable.
3157 </para>
3158 </glossdef>
3159 </glossentry>
3160
3161 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
3162 <glossdef>
3163 <para>
3164 Defines the package type (DEB, RPM, IPK, or TAR) used
3165 by the OpenEmbedded build system.
3166 The variable is defined appropriately by the
3167 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
3168 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
3169 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
3170 or
3171 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3172 class.
3173 </para>
3174
3175 <para>
3176 The
3177 <link linkend='ref-classes-populate-sdk-*'><filename>package_sdk_base</filename></link>
3178 and
3179 <link linkend='ref-classes-image'><filename>image</filename></link>
3180 classes use the <filename>IMAGE_PKGTYPE</filename> for
3181 packaging up images and SDKs.
3182 </para>
3183
3184 <para>
3185 You should not set the <filename>IMAGE_PKGTYPE</filename>
3186 manually.
3187 Rather, the variable is set indirectly through the
3188 appropriate
3189 <link linkend='ref-classes-package'><filename>package_*</filename></link>
3190 class using the
3191 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3192 variable.
3193 The OpenEmbedded build system uses the first package type
3194 (e.g. DEB, RPM, or IPK) that appears with the variable
3195 <note>
3196 Files using the <filename>.tar</filename> format are
3197 never used as a substitute packaging format for DEB,
3198 RPM, and IPK formatted files for your image or SDK.
3199 </note>
3200 </para>
3201 </glossdef>
3202 </glossentry>
3203
3204 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
3205 <glossdef>
3206 <para>
3207 Added by classes to run post processing commands once the
3208 OpenEmbedded build system has created the image.
3209 You can specify shell commands separated by semicolons:
3210 <literallayout class='monospaced'>
3211 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
3212 </literallayout>
3213 If you need to pass the path to the root filesystem within
3214 the command, you can use
3215 <filename>${IMAGE_ROOTFS}</filename>, which points to
3216 the root filesystem image.
3217 </para>
3218 </glossdef>
3219 </glossentry>
3220
3221 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
3222 <glossdef>
3223 <para>
3224 The location of the root filesystem while it is under
3225 construction (i.e. during <filename>do_rootfs</filename>).
3226 This variable is not configurable.
3227 Do not change it.
3228 </para>
3229 </glossdef>
3230 </glossentry>
3231
3232 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
3233 <glossdef>
3234 <para>
3235 Defines additional free disk space created in the image in Kbytes.
3236 By default, this variable is set to "0".
3237 This free disk space is added to the image after the build system determines
3238 the image size as described in
3239 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
3240 </para>
3241
3242 <para>
3243 This variable is particularly useful when you want to ensure that a
3244 specific amount of free disk space is available on a device after an image
3245 is installed and running.
3246 For example, to be sure 5 Gbytes of free disk space is available, set the
3247 variable as follows:
3248 <literallayout class='monospaced'>
3249 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3250 </literallayout>
3251 </para>
3252
3253 <para>
3254 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
3255 of extra space with the line:
3256 <literallayout class='monospaced'>
3257 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3258 </literallayout>
3259 </para>
3260 </glossdef>
3261 </glossentry>
3262
3263 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
3264 <glossdef>
3265 <para>
3266 Defines the size in Kbytes for the generated image.
3267 The OpenEmbedded build system determines the final size for the generated
3268 image using an algorithm that takes into account the initial disk space used
3269 for the generated image, a requested size for the image, and requested
3270 additional free disk space to be added to the image.
3271 Programatically, the build system determines the final size of the
3272 generated image as follows:
3273 <literallayout class='monospaced'>
3274 if (image-du * overhead) &lt; rootfs-size:
3275 internal-rootfs-size = rootfs-size + xspace
3276 else:
3277 internal-rootfs-size = (image-du * overhead) + xspace
3278
3279 where:
3280
3281 image-du = Returned value of the du command on
3282 the image.
3283
3284 overhead = IMAGE_OVERHEAD_FACTOR
3285
3286 rootfs-size = IMAGE_ROOTFS_SIZE
3287
3288 internal-rootfs-size = Initial root filesystem
3289 size before any modifications.
3290
3291 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3292 </literallayout>
3293 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
3294 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
3295 variables for related information.
3296<!-- In the above example, <filename>overhead</filename> is defined by the
3297 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
3298 variable, <filename>xspace</filename> is defined by the
3299 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3300 variable, and <filename>du</filename> is the results of the disk usage command
3301 on the initially generated image. -->
3302 </para>
3303 </glossdef>
3304 </glossentry>
3305
3306 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
3307 <glossdef>
3308 <para>
3309 Specifies a dependency from one image type on another.
3310 Here is an example from the
3311 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
3312 class:
3313 <literallayout class='monospaced'>
3314 IMAGE_TYPEDEP_live = "ext3"
3315 </literallayout>
3316 In the previous example, the variable ensures that when
3317 "live" is listed with the
3318 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3319 variable, the OpenEmbedded build system produces an
3320 <filename>ext3</filename> image first since one of the
3321 components of the live
3322 image is an <filename>ext3</filename>
3323 formatted partition containing the root
3324 filesystem.
3325 </para>
3326 </glossdef>
3327 </glossentry>
3328
3329 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
3330 <glossdef>
3331 <para>
3332 Specifies the complete list of supported image types
3333 by default:
3334 <literallayout class='monospaced'>
3335 jffs2
3336 jffs2.sum
3337 cramfs
3338 ext2
3339 ext2.gz
3340 ext2.bz2
3341 ext3
3342 ext3.gz
3343 ext2.lzma
3344 btrfs
3345 live
3346 squashfs
3347 squashfs-xz
3348 ubi
3349 ubifs
3350 tar
3351 tar.gz
3352 tar.bz2
3353 tar.xz
3354 cpio
3355 cpio.gz
3356 cpio.xz
3357 cpio.lzma
3358 vmdk
3359 elf
3360 </literallayout>
3361 For more information on how these types of images, see
3362 <filename>meta/classes/image_types*.bbclass</filename>
3363 in the
3364 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3365 </para>
3366 </glossdef>
3367 </glossentry>
3368
3369 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
3370 <glossdef>
3371 <para>Helps define the recipe revision for recipes that share
3372 a common <filename>include</filename> file.
3373 You can think of this variable as part of the recipe revision
3374 as set from within an include file.</para>
3375 <para>Suppose, for example, you have a set of recipes that
3376 are used across several projects.
3377 And, within each of those recipes the revision
3378 (its <link linkend='var-PR'><filename>PR</filename></link>
3379 value) is set accordingly.
3380 In this case, when the revision of those recipes changes,
3381 the burden is on you to find all those recipes and
3382 be sure that they get changed to reflect the updated
3383 version of the recipe.
3384 In this scenario, it can get complicated when recipes
3385 that are used in many places and provide common functionality
3386 are upgraded to a new revision.</para>
3387 <para>A more efficient way of dealing with this situation is
3388 to set the <filename>INC_PR</filename> variable inside
3389 the <filename>include</filename> files that the recipes
3390 share and then expand the <filename>INC_PR</filename>
3391 variable within the recipes to help
3392 define the recipe revision.
3393 </para>
3394 <para>
3395 The following provides an example that shows how to use
3396 the <filename>INC_PR</filename> variable
3397 given a common <filename>include</filename> file that
3398 defines the variable.
3399 Once the variable is defined in the
3400 <filename>include</filename> file, you can use the
3401 variable to set the <filename>PR</filename> values in
3402 each recipe.
3403 You will notice that when you set a recipe's
3404 <filename>PR</filename> you can provide more granular
3405 revisioning by appending values to the
3406 <filename>INC_PR</filename> variable:
3407 <literallayout class='monospaced'>
3408recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3409recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3410recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3411recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3412 </literallayout>
3413 The first line of the example establishes the baseline
3414 revision to be used for all recipes that use the
3415 <filename>include</filename> file.
3416 The remaining lines in the example are from individual
3417 recipes and show how the <filename>PR</filename> value
3418 is set.</para>
3419 </glossdef>
3420 </glossentry>
3421
3422 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
3423 <glossdef>
3424 <para>
3425 Specifies a space-separated list of license names
3426 (as they would appear in
3427 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
3428 that should be excluded from the build.
3429 Recipes that provide no alternatives to listed incompatible
3430 licenses are not built.
3431 Packages that are individually licensed with the specified
3432 incompatible licenses will be deleted.
3433 </para>
3434
3435 <note>
3436 This functionality is only regularly tested using
3437 the following setting:
3438 <literallayout class='monospaced'>
3439 INCOMPATIBLE_LICENSE = "GPLv3"
3440 </literallayout>
3441 Although you can use other settings, you might be required
3442 to remove dependencies on or provide alternatives to
3443 components that are required to produce a functional system
3444 image.
3445 </note>
3446 </glossdef>
3447 </glossentry>
3448
3449 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
3450 <glossdef>
3451 <para>
3452 Prevents the default dependencies, namely the C compiler
3453 and standard C library (libc), from being added to
3454 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
3455 This variable is usually used within recipes that do not
3456 require any compilation using the C compiler.
3457 </para>
3458
3459 <para>
3460 Set the variable to "1" to prevent the default dependencies
3461 from being added.
3462 </para>
3463 </glossdef>
3464 </glossentry>
3465
3466 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
3467 <glossdef>
3468 <para>
3469 If set to "1", causes the build to not strip binaries in resulting packages.
3470 </para>
3471 </glossdef>
3472 </glossentry>
3473
3474 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
3475 <glossdef>
3476 <para>
3477 Causes the named class to be inherited at
3478 this point during parsing.
3479 The variable is only valid in configuration files.
3480 </para>
3481 </glossdef>
3482 </glossentry>
3483
3484 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
3485 <glossdef>
3486 <para>
3487 Lists classes that will be inherited at the
3488 distribution level.
3489 It is unlikely that you want to edit this variable.
3490 </para>
3491
3492 <para>
3493 The default value of the variable is set as follows in the
3494 <filename>meta/conf/distro/defaultsetup.conf</filename>
3495 file:
3496 <literallayout class='monospaced'>
3497 INHERIT_DISTRO ?= "debian devshell sstate license"
3498 </literallayout>
3499 </para>
3500 </glossdef>
3501 </glossentry>
3502
3503 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
3504 <glossdef>
3505 <para>
3506 Defines the format for the output image of an initial
3507 RAM disk (initramfs), which is used during boot.
3508 Supported formats are the same as those supported by the
3509 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3510 variable.
3511 </para>
3512 </glossdef>
3513 </glossentry>
3514
3515 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
3516 <glossdef>
3517 <para>
3518 Causes the OpenEmbedded build system to build an additional
3519 recipe as a dependency to your root filesystem recipe
3520 (e.g. <filename>core-image-sato</filename>).
3521 The additional recipe is used to create an initial RAM disk
3522 (initramfs) that might be needed during the initial boot of
3523 the target system to accomplish such things as loading
3524 kernel modules prior to mounting the root file system.
3525 </para>
3526
3527 <para>
3528 When you set the variable, specify the name of the
3529 initramfs you want created.
3530 The following example, which is set in the
3531 <filename>local.conf</filename> configuration file, causes
3532 a separate recipe to be created that results in an
3533 initramfs image named
3534 <filename>core-image-sato-initramfs.bb</filename> to be
3535 created:
3536 <literallayout class='monospaced'>
3537 INITRAMFS_IMAGE = "core-image-minimal-initramfs"
3538 </literallayout>
3539 By default, the
3540 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3541 class sets this variable to a null string as follows:
3542 <literallayout class='monospaced'>
3543 INITRAMFS_IMAGE = ""
3544 </literallayout>
3545 </para>
3546
3547 <para>
3548 See the
3549 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
3550 file for additional information.
3551 You can also reference the
3552 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/kernel.bbclass'><filename>kernel.bbclass</filename></ulink>
3553 file to see how the variable is used.
3554 </para>
3555 </glossdef>
3556 </glossentry>
3557
3558 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
3559 <glossdef>
3560 <para>
3561 Controls whether or not the image recipe specified by
3562 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
3563 is run through an extra pass during kernel compilation
3564 in order to build a single binary that contains both the
3565 kernel image and the initial RAM disk (initramfs).
3566 Using an extra compilation pass ensures that when a kernel
3567 attempts to use an initramfs, it does not encounter
3568 circular dependencies should the initramfs include kernel
3569 modules.
3570 </para>
3571
3572 <para>
3573 The combined binary is deposited into the
3574 <filename>tmp/deploy</filename> directory, which is part
3575 of the
3576 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
3577 </para>
3578
3579 <para>
3580 Setting the variable to "1" in a configuration file causes
3581 the OpenEmbedded build system to make the extra pass during
3582 kernel compilation:
3583 <literallayout class='monospaced'>
3584 INITRAMFS_IMAGE_BUNDLE = "1"
3585 </literallayout>
3586 By default, the
3587 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3588 class sets this variable to a null string as follows:
3589 <literallayout class='monospaced'>
3590 INITRAMFS_IMAGE_BUNDLE = ""
3591 </literallayout>
3592 <note>
3593 You must set the
3594 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
3595 a configuration file.
3596 You cannot set the variable in a recipe file.
3597 </note>
3598 See the
3599 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
3600 file for additional information.
3601 </para>
3602 </glossdef>
3603 </glossentry>
3604
3605 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
3606 <glossdef>
3607 <para>
3608 Indicates a filesystem image to use as an initial RAM
3609 disk (<filename>initrd</filename>).
3610 </para>
3611
3612 <para>
3613 The <filename>INITRD</filename> variable is an optional
3614 variable used with the
3615 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
3616 class.
3617 </para>
3618 </glossdef>
3619 </glossentry>
3620
3621 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
3622 <glossdef>
3623 <para>
3624 The filename of the initialization script as installed to
3625 <filename>${sysconfdir}/init.d</filename>.
3626 </para>
3627 <para>
3628 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
3629 The variable is mandatory.
3630 </para>
3631 </glossdef>
3632 </glossentry>
3633
3634 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
3635 <glossdef>
3636 <para>
3637 A list of the packages that contain initscripts.
3638 If multiple packages are specified, you need to append the package name
3639 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
3640 <para>
3641 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
3642 The variable is optional and defaults to the
3643 <link linkend='var-PN'><filename>PN</filename></link> variable.
3644 </para>
3645 </glossdef>
3646 </glossentry>
3647
3648 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
3649 <glossdef>
3650 <para>
3651 Specifies the options to pass to <filename>update-rc.d</filename>.
3652 Here is an example:
3653 <literallayout class='monospaced'>
3654 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3655 </literallayout>
3656 In this example, the script has a runlevel of 99,
3657 starts the script in initlevels 2 and 5, and
3658 stops the script in levels 0, 1 and 6.
3659 </para>
3660 <para>
3661 The variable is mandatory and is used in recipes when using
3662 <filename>update-rc.d.bbclass</filename>.
3663 </para>
3664 </glossdef>
3665 </glossentry>
3666
3667 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
3668 <glossdef>
3669 <para>
3670 Specifies the QA checks to skip for a specific package
3671 within a recipe.
3672 For example, to skip the check for symbolic link
3673 <filename>.so</filename> files in the main package of a
3674 recipe, add the following to the recipe.
3675 The package name override must be used, which in this
3676 example is <filename>${PN}</filename>:
3677 <literallayout class='monospaced'>
3678 INSANE_SKIP_${PN} += "dev-so"
3679 </literallayout>
3680 </para>
3681 <para>
3682 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
3683 section for a list of the valid QA checks you can
3684 specify using this variable.
3685 </para>
3686 </glossdef>
3687 </glossentry>
3688
3689 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
3690 <glossdef>
3691 <para>
3692 When the IPK backend is in use and package management
3693 is enabled on the target, you can use this variable to
3694 set up <filename>opkg</filename> in the target image
3695 to point to package feeds on a nominated server.
3696 Once the feed is established, you can perform
3697 installations or upgrades using the package manager
3698 at runtime.
3699 </para>
3700 </glossdef>
3701 </glossentry>
3702
3703<!--
3704 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
3705 <glossdef>
3706 <para>
3707 An environment variable that defines the directory where
3708 post installation hooks are installed for the
3709 post install environment.
3710 This variable is fixed as follows:
3711 <literallayout class='monospaced'>
3712 ${WORKDIR}/intercept_scripts
3713 </literallayout>
3714 </para>
3715
3716 <para>
3717 After installation of a target's root filesystem,
3718 post installation scripts, which are essentially bash scripts,
3719 are all executed just a single time.
3720 Limiting execution of these scripts minimizes installation
3721 time that would be lengthened due to certain packages
3722 triggering redundant operations.
3723 For example, consider the installation of font packages
3724 as a common example.
3725 Without limiting the execution of post installation scripts,
3726 all font directories would be rescanned to create the
3727 cache after each individual font package was installed.
3728 </para>
3729
3730 <para>
3731 Do not edit the <filename>INTERCEPT_DIR</filename>
3732 variable.
3733 </para>
3734 </glossdef>
3735 </glossentry>
3736-->
3737
3738 </glossdiv>
3739
3740<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
3741<!-- </glossdiv>-->
3742
3743 <glossdiv id='var-glossary-k'><title>K</title>
3744
3745 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
3746 <glossdef>
3747 <para>
3748 Defines the kernel architecture used when assembling
3749 the configuration.
3750 Architectures supported for this release are:
3751 <literallayout class='monospaced'>
3752 powerpc
3753 i386
3754 x86_64
3755 arm
3756 qemu
3757 mips
3758 </literallayout>
3759 </para>
3760
3761 <para>
3762 You define the <filename>KARCH</filename> variable in the
3763 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
3764 </para>
3765 </glossdef>
3766 </glossentry>
3767
3768 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
3769 <glossdef>
3770 <para>
3771 A regular expression used by the build process to explicitly
3772 identify the kernel branch that is validated, patched
3773 and configured during a build.
3774 The <filename>KBRANCH</filename> variable is optional.
3775 You can use it to trigger checks to ensure the exact kernel
3776 branch you want is being used by the build process.
3777 </para>
3778
3779 <para>
3780 Values for this variable are set in the kernel's recipe
3781 file and the kernel's append file.
3782 For example, if you are using the Yocto Project kernel that
3783 is based on the Linux 3.10 kernel, the kernel recipe file
3784 is the
3785 <filename>meta/recipes-kernel/linux/linux-yocto_3.10.bb</filename>
3786 file.
3787 Following is the default value for <filename>KBRANCH</filename>
3788 and the default override for the architectures the Yocto
3789 Project supports:
3790 <literallayout class='monospaced'>
3791 KBRANCH_DEFAULT = "standard/base"
3792 KBRANCH = "${KBRANCH_DEFAULT}"
3793 </literallayout>
3794 This branch exists in the <filename>linux-yocto-3.10</filename>
3795 kernel Git repository
3796 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.10/refs/heads'></ulink>.
3797 </para>
3798
3799 <para>
3800 This variable is also used from the kernel's append file
3801 to identify the kernel branch specific to a particular
3802 machine or target hardware.
3803 The kernel's append file is located in the BSP layer for
3804 a given machine.
3805 For example, the kernel append file for the Crown Bay BSP is in the
3806 <filename>meta-intel</filename> Git repository and is named
3807 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend</filename>.
3808 Here are the related statements from the append file:
3809 <literallayout class='monospaced'>
3810 COMPATIBLE_MACHINE_crownbay = "crownbay"
3811 KMACHINE_crownbay = "crownbay"
3812 KBRANCH_crownbay = "standard/crownbay"
3813 KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb"
3814
3815 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
3816 KMACHINE_crownbay-noemgd = "crownbay"
3817 KBRANCH_crownbay-noemgd = "standard/crownbay"
3818 KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb"
3819 </literallayout>
3820 The <filename>KBRANCH_*</filename> statements identify
3821 the kernel branch to use when building for the Crown
3822 Bay BSP.
3823 In this case there are two identical statements: one
3824 for each type of Crown Bay machine.
3825 </para>
3826 </glossdef>
3827 </glossentry>
3828
3829 <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
3830 <glossdef>
3831 <para>
3832 Defines the Linux kernel source repository's default
3833 branch used to build the Linux kernel.
3834 The <filename>KBRANCH_DEFAULT</filename> value is
3835 the default value for
3836 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
3837 Unless you specify otherwise,
3838 <filename>KBRANCH_DEFAULT</filename> initializes to
3839 "master".
3840 </para>
3841 </glossdef>
3842 </glossentry>
3843
3844 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
3845 <glossdef>
3846 <para>
3847 Specifies additional <filename>make</filename>
3848 command-line arguments the OpenEmbedded build system
3849 passes on when compiling the kernel.
3850 </para>
3851 </glossdef>
3852 </glossentry>
3853
3854 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
3855 <glossdef>
3856 <para>Includes additional metadata from the Yocto Project kernel Git repository.
3857 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
3858 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
3859 is provided through
3860 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
3861 and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
3862 You can use the <filename>KERNEL_FEATURES</filename> variable to further
3863 add metadata for all BSPs.</para>
3864 <para>The metadata you add through this variable includes config fragments and
3865 features descriptions,
3866 which usually includes patches as well as config fragments.
3867 You typically override the <filename>KERNEL_FEATURES</filename> variable
3868 for a specific machine.
3869 In this way, you can provide validated, but optional, sets of kernel
3870 configurations and features.</para>
3871 <para>For example, the following adds <filename>netfilter</filename> to all
3872 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
3873 machine:
3874 <literallayout class='monospaced'>
3875 # Add netfilter to all linux-yocto kernels
3876 KERNEL_FEATURES="features/netfilter"
3877
3878 # Add sound support to the qemux86 machine
3879 KERNEL_FEATURES_append_qemux86=" cfg/sound"
3880 </literallayout></para>
3881 </glossdef>
3882 </glossentry>
3883
3884 <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm>
3885 <glossdef>
3886 <para>
3887 The base name of the kernel image.
3888 This variable is set in the
3889 <link linkend='ref-classes-kernel'>kernel</link> class
3890 as follows:
3891 <literallayout class='monospaced'>
3892 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
3893 </literallayout>
3894 See the
3895 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>,
3896 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
3897 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
3898 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
3899 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3900 and
3901 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3902 variables for additional information.
3903 </para>
3904 </glossdef>
3905 </glossentry>
3906
3907 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
3908 <glossdef>
3909 <para>The type of kernel to build for a device, usually set by the
3910 machine configuration files and defaults to "zImage".
3911 This variable is used
3912 when building the kernel and is passed to <filename>make</filename> as the target to
3913 build.</para>
3914 </glossdef>
3915 </glossentry>
3916
3917 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
3918 <glossdef>
3919 <para>
3920 The location of the kernel sources.
3921 This variable is set to the value of the
3922 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
3923 within the <filename>module.bbclass</filename> class.
3924 For information on how this variable is used, see the
3925 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
3926 section.
3927 </para>
3928
3929 <para>
3930 To help maximize compatibility with out-of-tree drivers
3931 used to build modules, the OpenEmbedded build system also
3932 recognizes and uses the
3933 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
3934 variable, which is identical to the
3935 <filename>KERNEL_PATH</filename> variable.
3936 Both variables are common variables used by external
3937 Makefiles to point to the kernel source directory.
3938 </para>
3939 </glossdef>
3940 </glossentry>
3941
3942 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
3943 <glossdef>
3944 <para>
3945 The location of the kernel sources.
3946 This variable is set to the value of the
3947 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
3948 within the <filename>module.bbclass</filename> class.
3949 For information on how this variable is used, see the
3950 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
3951 section.
3952 </para>
3953
3954 <para>
3955 To help maximize compatibility with out-of-tree drivers
3956 used to build modules, the OpenEmbedded build system also
3957 recognizes and uses the
3958 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
3959 variable, which is identical to the
3960 <filename>KERNEL_SRC</filename> variable.
3961 Both variables are common variables used by external
3962 Makefiles to point to the kernel source directory.
3963 </para>
3964 </glossdef>
3965 </glossentry>
3966
3967 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
3968 <glossdef>
3969 <para>
3970 Provides a short description of a configuration fragment.
3971 You use this variable in the <filename>.scc</filename>
3972 file that describes a configuration fragment file.
3973 Here is the variable used in a file named
3974 <filename>smp.scc</filename> to describe SMP being
3975 enabled:
3976 <literallayout class='monospaced'>
3977 define KFEATURE_DESCRIPTION "Enable SMP"
3978 </literallayout>
3979 </para>
3980 </glossdef>
3981 </glossentry>
3982
3983 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
3984 <glossdef>
3985 <para>
3986 The machine as known by the kernel.
3987 Sometimes the machine name used by the kernel does not match the machine name
3988 used by the OpenEmbedded build system.
3989 For example, the machine name that the OpenEmbedded build system understands as
3990 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
3991 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
3992 For cases like these, the <filename>KMACHINE</filename> variable maps the
3993 kernel machine name to the OpenEmbedded build system machine name.
3994 </para>
3995
3996 <para>
3997 Kernel machine names are initially defined in the
3998 Yocto Linux Kernel's <filename>meta</filename> branch.
3999 From the <filename>meta</filename> branch, look in
4000 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
4001 For example, from the <filename>meta</filename> branch in the
4002 <filename>linux-yocto-3.0</filename> kernel, the
4003 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
4004 has the following:
4005 <literallayout class='monospaced'>
4006 define KMACHINE cedartrail
4007 define KTYPE standard
4008 define KARCH i386
4009
4010 include ktypes/standard
4011 branch cedartrail
4012
4013 include cedartrail.scc
4014 </literallayout>
4015 You can see that the kernel understands the machine name for
4016 the Cedar Trail Board Support Package (BSP) as
4017 <filename>cedartrail</filename>.
4018 </para>
4019
4020 <para>
4021 If you look in the Cedar Trail BSP layer in the
4022 <filename>meta-intel</filename>
4023 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
4024 at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
4025 you will find the following statements among others:
4026 <literallayout class='monospaced'>
4027 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
4028 KMACHINE_cedartrail = "cedartrail"
4029 KBRANCH_cedartrail = "yocto/standard/cedartrail"
4030 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
4031 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
4032
4033 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
4034 KMACHINE_cedartrail-nopvr = "cedartrail"
4035 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
4036 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
4037 </literallayout>
4038 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
4039 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
4040 names.
4041 </para>
4042
4043 <para>
4044 This append file uses two <filename>KMACHINE</filename> statements.
4045 The first is not really necessary but does ensure that the machine known to the
4046 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
4047 in the kernel also known as <filename>cedartrail</filename>:
4048 <literallayout class='monospaced'>
4049 KMACHINE_cedartrail = "cedartrail"
4050 </literallayout>
4051 </para>
4052
4053 <para>
4054 The second statement is a good example of why the <filename>KMACHINE</filename> variable
4055 is needed.
4056 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
4057 machine name to refer to the Cedar Trail BSP that does not support the proprietary
4058 PowerVR driver.
4059 The kernel, however, uses the machine name <filename>cedartrail</filename>.
4060 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
4061 the kernel's <filename>cedartrail</filename> name:
4062 <literallayout class='monospaced'>
4063 KMACHINE_cedartrail-nopvr = "cedartrail"
4064 </literallayout>
4065 </para>
4066
4067 <para>
4068 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
4069 Project kernel machine names and the OpenEmbedded machine names.
4070 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
4071 name you use is different than that used in the kernel.
4072 </para>
4073 </glossdef>
4074 </glossentry>
4075
4076 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
4077 <glossdef>
4078 <para>
4079 Defines the kernel type to be used in assembling the
4080 configuration.
4081 The linux-yocto recipes define "standard", "tiny",
4082 and "preempt-rt" kernel types.
4083 See the
4084 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4085 section in the Yocto Project Linux Kernel Development
4086 Manual for more information on kernel types.
4087 </para>
4088
4089 <para>
4090 You define the <filename>KTYPE</filename> variable in the
4091 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
4092 The value you use must match the value used for the
4093 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
4094 value used by the kernel recipe.
4095 </para>
4096 </glossdef>
4097 </glossentry>
4098 </glossdiv>
4099
4100 <glossdiv id='var-glossary-l'><title>L</title>
4101
4102 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
4103 <glossdef>
4104 <para>
4105 Provides a list of targets for automatic configuration.
4106 </para>
4107
4108 <para>
4109 See the
4110 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
4111 class for more information on how this variable is used.
4112 </para>
4113 </glossdef>
4114 </glossentry>
4115
4116 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
4117 <glossdef>
4118 <para>Lists the layers that this recipe depends upon, separated by spaces.
4119 Optionally, you can specify a specific layer version for a dependency
4120 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
4121 to be compared against
4122 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
4123 in this case).
4124 An error will be produced if any dependency is missing or
4125 the version numbers do not match exactly (if specified).
4126 This variable is used in the <filename>conf/layer.conf</filename> file
4127 and must be suffixed with the name of the specific layer (e.g.
4128 <filename>LAYERDEPENDS_mylayer</filename>).</para>
4129 </glossdef>
4130 </glossentry>
4131
4132 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
4133 <glossdef>
4134 <para>When used inside the <filename>layer.conf</filename> configuration
4135 file, this variable provides the path of the current layer.
4136 This variable is not available outside of <filename>layer.conf</filename>
4137 and references are expanded immediately when parsing of the file completes.</para>
4138 </glossdef>
4139 </glossentry>
4140
4141 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
4142 <glossdef>
4143 <para>Optionally specifies the version of a layer as a single number.
4144 You can use this within
4145 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
4146 for another layer in order to depend on a specific version
4147 of the layer.
4148 This variable is used in the <filename>conf/layer.conf</filename> file
4149 and must be suffixed with the name of the specific layer (e.g.
4150 <filename>LAYERVERSION_mylayer</filename>).</para>
4151 </glossdef>
4152 </glossentry>
4153
4154 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
4155 <glossdef>
4156 <para>
4157 Specifies the lead (or primary) compiled library file
4158 (<filename>.so</filename>) that the
4159 <link linkend='ref-classes-debian'><filename>debian</filename></link>
4160 class applies its naming policy to given a recipe that
4161 packages multiple libraries.
4162 </para>
4163
4164 <para>
4165 This variable works in conjunction with the
4166 <filename>debian</filename> class.
4167 </para>
4168 </glossdef>
4169 </glossentry>
4170
4171 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
4172 <glossdef>
4173 <para>Checksums of the license text in the recipe source code.</para>
4174 <para>This variable tracks changes in license text of the source
4175 code files.
4176 If the license text is changed, it will trigger a build
4177 failure, which gives the developer an opportunity to review any
4178 license change.</para>
4179 <para>
4180 This variable must be defined for all recipes (unless
4181 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
4182 is set to "CLOSED")</para>
4183 <para>For more information, see the
4184 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
4185 Tracking License Changes</link> section</para>
4186 </glossdef>
4187 </glossentry>
4188
4189 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
4190 <glossdef>
4191 <para>
4192 The list of source licenses for the recipe.
4193 Follow these rules:
4194 <itemizedlist>
4195 <listitem><para>Do not use spaces within individual
4196 license names.</para></listitem>
4197 <listitem><para>Separate license names using
4198 | (pipe) when there is a choice between licenses.
4199 </para></listitem>
4200 <listitem><para>Separate license names using
4201 &amp; (ampersand) when multiple licenses exist
4202 that cover different parts of the source.
4203 </para></listitem>
4204 <listitem><para>You can use spaces between license
4205 names.</para></listitem>
4206 <listitem><para>For standard licenses, use the names
4207 of the files in
4208 <filename>meta/files/common-licenses/</filename>
4209 or the
4210 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
4211 flag names defined in
4212 <filename>meta/conf/licenses.conf</filename>.
4213 </para></listitem>
4214 </itemizedlist>
4215 </para>
4216
4217 <para>
4218 Here are some examples:
4219 <literallayout class='monospaced'>
4220 LICENSE = "LGPLv2.1 | GPLv3"
4221 LICENSE = "MPL-1 &amp; LGPLv2.1"
4222 LICENSE = "GPLv2+"
4223 </literallayout>
4224 The first example is from the recipes for Qt, which the user
4225 may choose to distribute under either the LGPL version
4226 2.1 or GPL version 3.
4227 The second example is from Cairo where two licenses cover
4228 different parts of the source code.
4229 The final example is from <filename>sysstat</filename>,
4230 which presents a single license.
4231 </para>
4232
4233 <para>
4234 You can also specify licenses on a per-package basis to
4235 handle situations where components of the output have
4236 different licenses.
4237 For example, a piece of software whose code is
4238 licensed under GPLv2 but has accompanying documentation
4239 licensed under the GNU Free Documentation License 1.2 could
4240 be specified as follows:
4241 <literallayout class='monospaced'>
4242 LICENSE = "GFDL-1.2 &amp; GPLv2"
4243 LICENSE_${PN} = "GPLv2"
4244 LICENSE_${PN}-doc = "GFDL-1.2"
4245 </literallayout>
4246 </para>
4247 </glossdef>
4248 </glossentry>
4249
4250 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
4251 <glossdef>
4252 <para>Path to additional licenses used during the build.
4253 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
4254 to define the directory that holds common license text used during the build.
4255 The <filename>LICENSE_PATH</filename> variable allows you to extend that
4256 location to other areas that have additional licenses:
4257 <literallayout class='monospaced'>
4258 LICENSE_PATH += "/path/to/additional/common/licenses"
4259 </literallayout></para>
4260 </glossdef>
4261 </glossentry>
4262
4263 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
4264 <glossdef>
4265 <para>
4266 Defines the kernel type to be used in assembling the
4267 configuration.
4268 The linux-yocto recipes define "standard", "tiny", and
4269 "preempt-rt" kernel types.
4270 See the
4271 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4272 section in the Yocto Project Linux Kernel Development
4273 Manual for more information on kernel types.
4274 </para>
4275
4276 <para>
4277 If you do not specify a
4278 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
4279 "standard".
4280 Together with
4281 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
4282 the <filename>LINUX_KERNEL_TYPE</filename> variable
4283 defines the search
4284 arguments used by the kernel tools to find the appropriate
4285 description within the kernel
4286 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4287 with which to build out the sources and configuration.
4288 </para>
4289 </glossdef>
4290 </glossentry>
4291
4292 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
4293 <glossdef>
4294 <para>The Linux version from <filename>kernel.org</filename>
4295 on which the Linux kernel image being built using the
4296 OpenEmbedded build system is based.
4297 You define this variable in the kernel recipe.
4298 For example, the <filename>linux-yocto-3.4.bb</filename>
4299 kernel recipe found in
4300 <filename>meta/recipes-kernel/linux</filename>
4301 defines the variables as follows:
4302 <literallayout class='monospaced'>
4303 LINUX_VERSION ?= "3.4.24"
4304 </literallayout>
4305 The <filename>LINUX_VERSION</filename> variable is used to
4306 define <link linkend='var-PV'><filename>PV</filename></link>
4307 for the recipe:
4308 <literallayout class='monospaced'>
4309 PV = "${LINUX_VERSION}+git${SRCPV}"
4310 </literallayout></para>
4311 </glossdef>
4312 </glossentry>
4313
4314 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
4315 <glossdef>
4316 <para>A string extension compiled into the version
4317 string of the Linux kernel built with the OpenEmbedded
4318 build system.
4319 You define this variable in the kernel recipe.
4320 For example, the linux-yocto kernel recipes all define
4321 the variable as follows:
4322 <literallayout class='monospaced'>
4323 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
4324 </literallayout>
4325 Defining this variable essentially sets the
4326 Linux kernel configuration item
4327 <filename>CONFIG_LOCALVERSION</filename>, which is visible
4328 through the <filename>uname</filename> command.
4329 Here is an example that shows the extension assuming it
4330 was set as previously shown:
4331 <literallayout class='monospaced'>
4332 $ uname -r
4333 3.7.0-rc8-custom
4334 </literallayout>
4335 </para>
4336 </glossdef>
4337 </glossentry>
4338
4339 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
4340 <glossdef>
4341 <para>
4342 Specifies the directory to which the OpenEmbedded build
4343 system writes overall log files.
4344 The default directory is <filename>${TMPDIR}/log</filename>.
4345 </para>
4346 <para>
4347 For the directory containing logs specific to each task,
4348 see the <link linkend='var-T'><filename>T</filename></link>
4349 variable.
4350 </para>
4351 </glossdef>
4352 </glossentry>
4353
4354 </glossdiv>
4355
4356 <glossdiv id='var-glossary-m'><title>M</title>
4357
4358 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
4359 <glossdef>
4360 <para>
4361 Specifies the target device for which the image is built.
4362 You define <filename>MACHINE</filename> in the
4363 <filename>local.conf</filename> file found in the
4364 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
4365 By default, <filename>MACHINE</filename> is set to
4366 "qemux86", which is an x86-based architecture machine to
4367 be emulated using QEMU:
4368 <literallayout class='monospaced'>
4369 MACHINE ?= "qemux86"
4370 </literallayout>
4371 The variable corresponds to a machine configuration file of the
4372 same name, through which machine-specific configurations are set.
4373 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
4374 exists the corresponding <filename>qemux86.conf</filename> machine
4375 configuration file, which can be found in the
4376 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4377 in <filename>meta/conf/machine</filename>.
4378 </para>
4379
4380 <para>
4381 The list of machines supported by the Yocto Project as
4382 shipped include the following:
4383 <literallayout class='monospaced'>
4384 MACHINE ?= "qemuarm"
4385 MACHINE ?= "qemumips"
4386 MACHINE ?= "qemuppc"
4387 MACHINE ?= "qemux86"
4388 MACHINE ?= "qemux86-64"
4389 MACHINE ?= "genericx86"
4390 MACHINE ?= "genericx86-64"
4391 MACHINE ?= "beaglebone"
4392 MACHINE ?= "mpc8315e-rdb"
4393 MACHINE ?= "edgerouter"
4394 </literallayout>
4395 The last five are Yocto Project reference hardware boards, which
4396 are provided in the <filename>meta-yocto-bsp</filename> layer.
4397 <note>Adding additional Board Support Package (BSP) layers
4398 to your configuration adds new possible settings for
4399 <filename>MACHINE</filename>.
4400 </note>
4401 </para>
4402 </glossdef>
4403 </glossentry>
4404
4405 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
4406 <glossdef>
4407 <para></para>
4408 <para>
4409 A list of required machine-specific packages to install as part of
4410 the image being built.
4411 The build process depends on these packages being present.
4412 Furthermore, because this is a "machine essential" variable, the list of
4413 packages are essential for the machine to boot.
4414 The impact of this variable affects images based on
4415 <filename>packagegroup-core-boot</filename>,
4416 including the <filename>core-image-minimal</filename> image.
4417 </para>
4418 <para>
4419 This variable is similar to the
4420 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
4421 variable with the exception that the image being built has a build
4422 dependency on the variable's list of packages.
4423 In other words, the image will not build if a file in this list is not found.
4424 </para>
4425 <para>
4426 As an example, suppose the machine for which you are building requires
4427 <filename>example-init</filename> to be run during boot to initialize the hardware.
4428 In this case, you would use the following in the machine's
4429 <filename>.conf</filename> configuration file:
4430 <literallayout class='monospaced'>
4431 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4432 </literallayout>
4433 </para>
4434 </glossdef>
4435 </glossentry>
4436
4437 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
4438 <glossdef>
4439 <para></para>
4440 <para>
4441 A list of recommended machine-specific packages to install as part of
4442 the image being built.
4443 The build process does not depend on these packages being present.
4444 However, because this is a "machine essential" variable, the list of
4445 packages are essential for the machine to boot.
4446 The impact of this variable affects images based on
4447 <filename>packagegroup-core-boot</filename>,
4448 including the <filename>core-image-minimal</filename> image.
4449 </para>
4450 <para>
4451 This variable is similar to the
4452 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
4453 variable with the exception that the image being built does not have a build
4454 dependency on the variable's list of packages.
4455 In other words, the image will still build if a package in this list is not found.
4456 Typically, this variable is used to handle essential kernel modules, whose
4457 functionality may be selected to be built into the kernel rather than as a module,
4458 in which case a package will not be produced.
4459 </para>
4460 <para>
4461 Consider an example where you have a custom kernel where a specific touchscreen
4462 driver is required for the machine to be usable.
4463 However, the driver can be built as a module or
4464 into the kernel depending on the kernel configuration.
4465 If the driver is built as a module, you want it to be installed.
4466 But, when the driver is built into the kernel, you still want the
4467 build to succeed.
4468 This variable sets up a "recommends" relationship so that in the latter case,
4469 the build will not fail due to the missing package.
4470 To accomplish this, assuming the package for the module was called
4471 <filename>kernel-module-ab123</filename>, you would use the
4472 following in the machine's <filename>.conf</filename> configuration
4473 file:
4474 <literallayout class='monospaced'>
4475 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4476 </literallayout>
4477 </para>
4478 <para>
4479 Some examples of these machine essentials are flash, screen, keyboard, mouse,
4480 or touchscreen drivers (depending on the machine).
4481 </para>
4482 </glossdef>
4483 </glossentry>
4484
4485 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
4486 <glossdef>
4487 <para>
4488 A list of machine-specific packages to install as part of the
4489 image being built that are not essential for the machine to boot.
4490 However, the build process for more fully-featured images
4491 depends on the packages being present.
4492 </para>
4493 <para>
4494 This variable affects all images based on
4495 <filename>packagegroup-base</filename>, which does not include the
4496 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4497 images.
4498 </para>
4499 <para>
4500 The variable is similar to the
4501 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
4502 variable with the exception that the image being built has a build
4503 dependency on the variable's list of packages.
4504 In other words, the image will not build if a file in this list is not found.
4505 </para>
4506 <para>
4507 An example is a machine that has WiFi capability but is not
4508 essential for the machine to boot the image.
4509 However, if you are building a more fully-featured image, you want to enable
4510 the WiFi.
4511 The package containing the firmware for the WiFi hardware is always
4512 expected to exist, so it is acceptable for the build process to depend upon
4513 finding the package.
4514 In this case, assuming the package for the firmware was called
4515 <filename>wifidriver-firmware</filename>, you would use the following in the
4516 <filename>.conf</filename> file for the machine:
4517 <literallayout class='monospaced'>
4518 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4519 </literallayout>
4520 </para>
4521 </glossdef>
4522 </glossentry>
4523
4524 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
4525 <glossdef>
4526 <para></para>
4527 <para>
4528 A list of machine-specific packages to install as part of the
4529 image being built that are not essential for booting the machine.
4530 The image being built has no build dependency on this list of packages.
4531 </para>
4532 <para>
4533 This variable affects only images based on
4534 <filename>packagegroup-base</filename>, which does not include the
4535 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4536 images.
4537 </para>
4538 <para>
4539 This variable is similar to the
4540 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
4541 variable with the exception that the image being built does not have a build
4542 dependency on the variable's list of packages.
4543 In other words, the image will build if a file in this list is not found.
4544 </para>
4545 <para>
4546 An example is a machine that has WiFi capability but is not essential
4547 For the machine to boot the image.
4548 However, if you are building a more fully-featured image, you want to enable
4549 WiFi.
4550 In this case, the package containing the WiFi kernel module will not be produced
4551 if the WiFi driver is built into the kernel, in which case you still want the
4552 build to succeed instead of failing as a result of the package not being found.
4553 To accomplish this, assuming the package for the module was called
4554 <filename>kernel-module-examplewifi</filename>, you would use the
4555 following in the <filename>.conf</filename> file for the machine:
4556 <literallayout class='monospaced'>
4557 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4558 </literallayout>
4559 </para>
4560 </glossdef>
4561 </glossentry>
4562
4563 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
4564 <glossdef>
4565 <para>
4566 Specifies the list of hardware features the
4567 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
4568 of supporting.
4569 For related information on enabling features, see the
4570 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
4571 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
4572 and
4573 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
4574 variables.
4575 </para>
4576
4577 <para>
4578 For a list of hardware features supported by the Yocto
4579 Project as shipped, see the
4580 "<link linkend='ref-features-machine'>Machine Features</link>"
4581 section.
4582 </para>
4583 </glossdef>
4584 </glossentry>
4585
4586 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
4587 <glossdef>
4588 <para>Features to be added to
4589 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
4590 if not also present in
4591 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
4592 </para>
4593
4594 <para>
4595 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
4596 It is not intended to be user-configurable.
4597 It is best to just reference the variable to see which machine features are
4598 being backfilled for all machine configurations.
4599 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
4600 more information.
4601 </para>
4602 </glossdef>
4603 </glossentry>
4604
4605 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
4606 <glossdef>
4607 <para>Features from
4608 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
4609 that should not be backfilled (i.e. added to
4610 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
4611 during the build.
4612 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
4613 more information.
4614 </para>
4615 </glossdef>
4616 </glossentry>
4617
4618 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
4619 <glossdef>
4620 <para>
4621 Lists overrides specific to the current machine.
4622 By default, this list includes the value
4623 of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
4624 You can extend the list to apply variable overrides for
4625 classes of machines.
4626 For example, all QEMU emulated machines (e.g. qemuarm,
4627 qemux86, and so forth) include a common file named
4628 <filename>meta/conf/machine/include/qemu.inc</filename>
4629 that prepends <filename>MACHINEOVERRIDES</filename> with
4630 the following variable override:
4631 <literallayout class='monospaced'>
4632 MACHINEOVERRIDES =. "qemuall:"
4633 </literallayout>
4634 Applying an override like <filename>qemuall</filename>
4635 affects all QEMU emulated machines elsewhere.
4636 Here is an example from the
4637 <filename>connman-conf</filename> recipe:
4638 <literallayout class='monospaced'>
4639 SRC_URI_append_qemuall = "file://wired.config \
4640 file://wired-setup \
4641 "
4642 </literallayout>
4643 </para>
4644 </glossdef>
4645 </glossentry>
4646
4647 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
4648 <glossdef>
4649 <para>The email address of the distribution maintainer.</para>
4650 </glossdef>
4651 </glossentry>
4652
4653 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
4654 <glossdef>
4655 <para>
4656 Specifies additional paths from which the OpenEmbedded
4657 build system gets source code.
4658 When the build system searches for source code, it first
4659 tries the local download directory.
4660 If that location fails, the build system tries locations
4661 defined by
4662 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
4663 the upstream source, and then locations specified by
4664 <filename>MIRRORS</filename> in that order.
4665 </para>
4666
4667 <para>
4668 Assuming your distribution
4669 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
4670 is "poky", the default value for
4671 <filename>MIRRORS</filename> is defined in the
4672 <filename>conf/distro/poky.conf</filename> file in the
4673 <filename>meta-yocto</filename> Git repository.
4674 </para>
4675 </glossdef>
4676 </glossentry>
4677
4678 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
4679 <glossdef>
4680 <para>
4681 Specifies a prefix has been added to
4682 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
4683 of a recipe or package, such as a Multilib version.
4684 The variable is used in places where the prefix needs to be
4685 added to or removed from a the name (e.g. the
4686 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
4687 <filename>MLPREFIX</filename> gets set when a prefix has been
4688 added to <filename>PN</filename>.
4689 </para>
4690 </glossdef>
4691 </glossentry>
4692
4693 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
4694 <glossdef>
4695 <para>
4696 Lists kernel modules that need to be auto-loaded during
4697 boot.
4698 </para>
4699
4700 <para>
4701 You can use this variable anywhere that it can be
4702 recognized by the kernel recipe or out-of-tree kernel
4703 module recipe (e.g. a machine configuration file, a
4704 distribution configuration file, an append file for the
4705 recipe, or the recipe itself).
4706 </para>
4707
4708 <para>
4709 Specify it as follows:
4710 <literallayout class='monospaced'>
4711 module_autoload_&lt;modname&gt; = "modname1 modname2 modname3"
4712 </literallayout>
4713 You must use the kernel module name override.
4714 </para>
4715
4716 <para>
4717 Including <filename>module_autoload</filename> causes the
4718 OpenEmbedded build system to populate the
4719 <filename>/etc/modules-load.d/modname.conf</filename>
4720 file with the list of modules to be auto-loaded on boot.
4721 The modules appear one-per-line in the file.
4722 Here is an example of the most common use case:
4723 <literallayout class='monospaced'>
4724 module_autoload_modname = "modname"
4725 </literallayout>
4726 </para>
4727
4728 <para>
4729 For information on how to populate the
4730 <filename>modname.conf</filename> file with
4731 <filename>modprobe.d</filename> syntax lines, see the
4732 <link linkend='var-module_conf'><filename>module_conf</filename></link>
4733 variable.
4734 </para>
4735 </glossdef>
4736 </glossentry>
4737
4738 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
4739 <glossdef>
4740 <para>
4741 Specifies <filename>modprobe.d</filename> syntax lines
4742 for inclusion in the
4743 <filename>/etc/modprobe.d/modname.conf</filename> file.
4744 </para>
4745
4746 <para>
4747 You can use this variable anywhere that it can be
4748 recognized by the kernel recipe or out-of-tree kernel
4749 module recipe (e.g. a machine configuration file, a
4750 distribution configuration file, an append file for the
4751 recipe, or the recipe itself).
4752 </para>
4753
4754 <para>
4755 Here is the general syntax:
4756 <literallayout class='monospaced'>
4757 module_conf_&lt;modname&gt; = "modprobe.d-syntax"
4758 </literallayout>
4759 You must use the kernel module name override.
4760 </para>
4761
4762 <para>
4763 Run <filename>man modprobe.d</filename> in the shell to
4764 find out more information on the exact syntax for lines
4765 you want to provide with <filename>module_conf</filename>.
4766 </para>
4767
4768 <para>
4769 Including <filename>module_conf</filename> causes the
4770 OpenEmbedded build system to populate the
4771 <filename>/etc/modprobe.d/modname.conf</filename>
4772 file with <filename>modprobe.d</filename> syntax lines.
4773 Here is an example:
4774 <literallayout class='monospaced'>
4775 module_conf_&lt;modname&gt; = "options modname arg1=val1 arg2=val2"
4776 </literallayout>
4777 </para>
4778
4779 <para>
4780 For information on how to specify kernel modules to
4781 auto-load on boot, see the
4782 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
4783 variable.
4784 </para>
4785 </glossdef>
4786 </glossentry>
4787
4788 <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm>
4789 <glossdef>
4790 <para>
4791 The base name of the kernel modules tarball.
4792 This variable is set in the
4793 <link linkend='ref-classes-kernel'>kernel</link> class
4794 as follows:
4795 <literallayout class='monospaced'>
4796 MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
4797 </literallayout>
4798 See the
4799 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
4800 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
4801 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
4802 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
4803 and
4804 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
4805 variables for additional information.
4806 </para>
4807 </glossdef>
4808 </glossentry>
4809
4810 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
4811 <glossdef>
4812 <para>
4813 Controls creation of the <filename>modules-*.tgz</filename>
4814 file.
4815 Set this variable to "0" to disable creation of this
4816 file, which contains all of the kernel modules resulting
4817 from a kernel build.
4818 </para>
4819 </glossdef>
4820 </glossentry>
4821
4822 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
4823 <glossdef>
4824 <para>
4825 Separates files for different machines such that you can build
4826 for multiple target machines using the same output directories.
4827 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
4828 for an example.
4829 </para>
4830 </glossdef>
4831 </glossentry>
4832
4833 </glossdiv>
4834
4835 <glossdiv id='var-glossary-n'><title>N</title>
4836
4837 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
4838 <glossdef>
4839 <para>
4840 A string identifying the host distribution.
4841 Strings consist of the host distributor ID
4842 followed by the release, as reported by the
4843 <filename>lsb_release</filename> tool
4844 or as read from <filename>/etc/lsb-release</filename>.
4845 For example, when running a build on Ubuntu 12.10, the value
4846 is "Ubuntu-12.10".
4847 If this information is unable to be determined, the value
4848 resolves to "Unknown".
4849 </para>
4850 <para>
4851 This variable is used by default to isolate native shared
4852 state packages for different distributions (e.g. to avoid
4853 problems with <filename>glibc</filename> version
4854 incompatibilities).
4855 Additionally, the variable is checked against
4856 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
4857 if that variable is set.
4858 </para>
4859 </glossdef>
4860 </glossentry>
4861
4862 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
4863 <glossdef>
4864 <para>
4865 Prevents installation of all "recommended-only" packages.
4866 Recommended-only packages are packages installed only
4867 through the
4868 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
4869 variable).
4870 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
4871 to "1" turns this feature on:
4872 <literallayout class='monospaced'>
4873 NO_RECOMMENDATIONS = "1"
4874 </literallayout>
4875 You can set this variable globally in your
4876 <filename>local.conf</filename> file or you can attach it to
4877 a specific image recipe by using the recipe name override:
4878 <literallayout class='monospaced'>
4879 NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
4880 </literallayout>
4881 </para>
4882
4883 <para>
4884 It is important to realize that if you choose to not install
4885 packages using this variable and some other packages are
4886 dependent on them (i.e. listed in a recipe's
4887 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
4888 variable), the OpenEmbedded build system ignores your
4889 request and will install the packages to avoid dependency
4890 errors.
4891 <note>
4892 Some recommended packages might be required for certain
4893 system functionality, such as kernel modules.
4894 It is up to you to add packages with the
4895 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
4896 variable.
4897 </note>
4898 </para>
4899
4900 <para>
4901 Support for this variable exists only when using the
4902 IPK and RPM packaging backend.
4903 Support does not exist for DEB.
4904 </para>
4905
4906 <para>
4907 See the
4908 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
4909 and the
4910 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
4911 variables for related information.
4912 </para>
4913 </glossdef>
4914 </glossentry>
4915
4916 <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm>
4917 <glossdef>
4918 <para>
4919 Causes the OpenEmbedded build system to skip building the
4920 <filename>.hddimg</filename> image.
4921 The <filename>NOHDD</filename> variable is used with the
4922 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
4923 class.
4924 Set the variable to "1" to prevent the
4925 <filename>.hddimg</filename> image from being built.
4926 </para>
4927 </glossdef>
4928 </glossentry>
4929
4930 <glossentry id='var-NOISO'><glossterm>NOISO</glossterm>
4931 <glossdef>
4932 <para>
4933 Causes the OpenEmbedded build system to skip building the
4934 ISO image.
4935 The <filename>NOISO</filename> variable is used with the
4936 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
4937 class.
4938 Set the variable to "1" to prevent the ISO image from
4939 being built.
4940 To enable building an ISO image, set the variable to "0".
4941 </para>
4942 </glossdef>
4943 </glossentry>
4944
4945 </glossdiv>
4946
4947 <glossdiv id='var-glossary-o'><title>O</title>
4948
4949 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
4950 <glossdef>
4951 <para>
4952 When a recipe inherits the
4953 <filename>binconfig.bbclass</filename> class, this variable
4954 specifies additional arguments passed to the "sed" command.
4955 The sed command alters any paths in configuration scripts
4956 that have been set up during compilation.
4957 Inheriting this class results in all paths in these scripts
4958 being changed to point into the
4959 <filename>sysroots/</filename> directory so that all builds
4960 that use the script will use the correct directories
4961 for the cross compiling layout.
4962 </para>
4963
4964 <para>
4965 See the <filename>meta/classes/binconfig.bbclass</filename>
4966 in the
4967 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4968 for details on how this class applies these additional
4969 sed command arguments.
4970 For general information on the
4971 <filename>binconfig.bbclass</filename> class, see the
4972 "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
4973 section.
4974 </para>
4975 </glossdef>
4976 </glossentry>
4977
4978 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
4979 <glossdef>
4980 <para>
4981 An internal variable used to tell the OpenEmbedded build
4982 system what Python modules to import for every Python
4983 function run by the system.
4984 </para>
4985
4986 <note>
4987 Do not set this variable.
4988 It is for internal use only.
4989 </note>
4990 </glossdef>
4991 </glossentry>
4992
4993 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
4994 <glossdef>
4995 <para>
4996 Controls how the OpenEmbedded build system spawns
4997 interactive terminals on the host development system
4998 (e.g. using the BitBake command with the
4999 <filename>-c devshell</filename> command-line option).
5000 For more information, see the
5001 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
5002 in the Yocto Project Development Manual.
5003 </para>
5004
5005 <para>
5006 You can use the following values for the
5007 <filename>OE_TERMINAL</filename> variable:
5008 <literallayout class='monospaced'>
5009 auto
5010 gnome
5011 xfce
5012 rxvt
5013 screen
5014 konsole
5015 none
5016 </literallayout>
5017 <note>Konsole support only works for KDE 3.x.
5018 Also, "auto" is the default behavior for
5019 <filename>OE_TERMINAL</filename></note>
5020 </para>
5021 </glossdef>
5022 </glossentry>
5023
5024 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
5025 <glossdef>
5026 <para>
5027 The directory from which the top-level build environment
5028 setup script is sourced.
5029 The Yocto Project makes two top-level build environment
5030 setup scripts available:
5031 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
5032 and
5033 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
5034 When you run one of these scripts, the
5035 <filename>OEROOT</filename> variable resolves to the
5036 directory that contains the script.
5037 </para>
5038
5039 <para>
5040 For additional information on how this variable is used,
5041 see the initialization scripts.
5042 </para>
5043 </glossdef>
5044 </glossentry>
5045
5046 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
5047 <glossdef>
5048 <para>
5049 Declares the oldest version of the Linux kernel that the
5050 produced binaries must support.
5051 This variable is passed into the build of the Embedded
5052 GNU C Library (<filename>eglibc</filename>).
5053 </para>
5054
5055 <para>
5056 The default for this variable comes from the
5057 <filename>meta/conf/bitbake.conf</filename> configuration
5058 file.
5059 You can override this default by setting the variable
5060 in a custom distribution configuration file.
5061 </para>
5062 </glossdef>
5063 </glossentry>
5064
5065 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
5066 <glossdef>
5067 <para>
5068 BitBake uses <filename>OVERRIDES</filename> to control
5069 what variables are overridden after BitBake parses
5070 recipes and configuration files.
5071 You can find more information on how overrides are handled
5072 in the BitBake Manual that is located at
5073 <filename>bitbake/doc/manual</filename> in the
5074 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5075 </para>
5076 </glossdef>
5077 </glossentry>
5078 </glossdiv>
5079
5080 <glossdiv id='var-glossary-p'><title>P</title>
5081
5082 <glossentry id='var-P'><glossterm>P</glossterm>
5083 <glossdef>
5084 <para>The recipe name and version.
5085 <filename>P</filename> is comprised of the following:
5086 <literallayout class='monospaced'>
5087 ${PN}-${PV}
5088 </literallayout></para>
5089 </glossdef>
5090 </glossentry>
5091
5092 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
5093 <glossdef>
5094 <para>The architecture of the resulting package or packages.</para>
5095 </glossdef>
5096 </glossentry>
5097
5098 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
5099 <glossdef>
5100 <para>Enables easily adding packages to
5101 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
5102 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
5103 so that those added packages can pick up files that would normally be
5104 included in the default package.</para>
5105 </glossdef>
5106 </glossentry>
5107
5108 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
5109 <glossdef>
5110 <para>
5111 This variable, which is set in the
5112 <filename>local.conf</filename> configuration file found in
5113 the <filename>conf</filename> folder of the
5114 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
5115 specifies the package manager the OpenEmbedded build system
5116 uses when packaging data.
5117 </para>
5118
5119 <para>
5120 You can provide one or more of the following arguments for
5121 the variable:
5122 <literallayout class='monospaced'>
5123 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
5124 </literallayout>
5125 The build system uses only the first argument in the list
5126 as the package manager when creating your image or SDK.
5127 However, packages will be created using any additional
5128 packaging classes you specify.
5129 For example, if you use the following in your
5130 <filename>local.conf</filename> file:
5131 <literallayout class='monospaced'>
5132 PACKAGE_CLASSES ?= "package_ipk package_tar"
5133 </literallayout>
5134 The OpenEmbedded build system uses the IPK package manager
5135 to create your image or SDK as well as generating
5136 TAR packages.
5137 </para>
5138
5139 <para>
5140 You cannot specify the
5141 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
5142 class first in the list.
5143 Files using the <filename>.tar</filename> format cannot
5144 be used as a substitute packaging format
5145 for DEB, RPM, and IPK formatted files for your image or SDK.
5146 </para>
5147
5148 <para>
5149 For information on packaging and build performance effects
5150 as a result of the package manager in use, see the
5151 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
5152 section.
5153 </para>
5154 </glossdef>
5155 </glossentry>
5156
5157 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
5158 <glossdef>
5159 <para>
5160 Lists packages that should not be installed into an image.
5161 For example:
5162 <literallayout class='monospaced'>
5163 PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
5164 </literallayout>
5165 You can set this variable globally in your
5166 <filename>local.conf</filename> file or you can attach it to
5167 a specific image recipe by using the recipe name override:
5168 <literallayout class='monospaced'>
5169 PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
5170 </literallayout>
5171 </para>
5172
5173 <para>
5174 If you choose to not install
5175 a package using this variable and some other package is
5176 dependent on it (i.e. listed in a recipe's
5177 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5178 variable), the OpenEmbedded build system generates a fatal
5179 installation error.
5180 Because the build system halts the process with a fatal
5181 error, you can use the variable with an iterative
5182 development process to remove specific components from a
5183 system.
5184 </para>
5185
5186 <para>
5187 Support for this variable exists only when using the
5188 IPK and RPM packaging backend.
5189 Support does not exist for DEB.
5190 </para>
5191
5192 <para>
5193 See the
5194 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
5195 and the
5196 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
5197 variables for related information.
5198 </para>
5199 </glossdef>
5200 </glossentry>
5201
5202 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
5203 <glossdef>
5204 <para>Specifies the list of architectures compatible with the device CPU.
5205 This variable is useful when you build for several different devices that use
5206 miscellaneous processors such as XScale and ARM926-EJS).</para>
5207 </glossdef>
5208 </glossentry>
5209
5210 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
5211 <glossdef>
5212
5213 <para>
5214 The <filename>PACKAGE_GROUP</filename> variable has been
5215 renamed to
5216 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
5217 See the variable description for
5218 <filename>FEATURE_PACKAGES</filename> for information.
5219 </para>
5220
5221 <para>
5222 If if you use the <filename>PACKAGE_GROUP</filename>
5223 variable, the OpenEmbedded build system issues a warning
5224 message.
5225 </para>
5226 </glossdef>
5227 </glossentry>
5228
5229 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
5230 <glossdef>
5231 <para>
5232 The final list of packages passed to the package manager
5233 for installation into the image.
5234 </para>
5235
5236 <para>
5237 Because the package manager controls actual installation
5238 of all packages, the list of packages passed using
5239 <filename>PACKAGE_INSTALL</filename> is not the final list
5240 of packages that are actually installed.
5241 This variable is internal to the image construction
5242 code.
5243 Consequently, in general, you should use the
5244 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
5245 variable to specify packages for installation.
5246 The exception to this is when working with
5247 the
5248 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5249 image.
5250 When working with an initial RAM disk (initramfs)
5251 image, use the <filename>PACKAGE_INSTALL</filename>
5252 variable.
5253 </para>
5254 </glossdef>
5255 </glossentry>
5256
5257 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
5258 <glossdef>
5259 <para>
5260 This variable provides a means of enabling or disabling
5261 features of a recipe on a per-recipe basis.
5262 <filename>PACKAGECONFIG</filename> blocks are defined
5263 in recipes when you specify features and then arguments
5264 that define feature behaviors.
5265 Here is the basic block structure:
5266 <literallayout class='monospaced'>
5267 PACKAGECONFIG ??= "f1 f2 f3 ..."
5268 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
5269 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
5270 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
5271 </literallayout>
5272 The <filename>PACKAGECONFIG</filename>
5273 variable itself specifies a space-separated list of the
5274 features to enable.
5275 Following the features, you can determine the behavior of
5276 each feature by providing up to four order-dependent
5277 arguments, which are separated by commas.
5278 You can omit any argument you like but must retain the
5279 separating commas.
5280 The order is important and specifies the following:
5281 <orderedlist>
5282 <listitem><para>Extra arguments
5283 that should be added to the configure script
5284 argument list
5285 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
5286 if the feature is enabled.</para></listitem>
5287 <listitem><para>Extra arguments
5288 that should be added to <filename>EXTRA_OECONF</filename>
5289 if the feature is disabled.
5290 </para></listitem>
5291 <listitem><para>Additional build dependencies
5292 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
5293 that should be added if the feature is enabled.
5294 </para></listitem>
5295 <listitem><para>Additional runtime dependencies
5296 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5297 that should be added if the feature is enabled.
5298 </para></listitem>
5299 </orderedlist>
5300 </para>
5301
5302 <para>
5303 Consider the following
5304 <filename>PACKAGECONFIG</filename> block taken from the
5305 <filename>librsvg</filename> recipe.
5306 In this example the feature is <filename>croco</filename>,
5307 which has three arguments that determine the feature's
5308 behavior.
5309 <literallayout class='monospaced'>
5310 PACKAGECONFIG ??= "croco"
5311 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
5312 </literallayout>
5313 The <filename>--with-croco</filename> and
5314 <filename>libcroco</filename> arguments apply only if
5315 the feature is enabled.
5316 In this case, <filename>--with-croco</filename> is
5317 added to the configure script argument list and
5318 <filename>libcroco</filename> is added to
5319 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
5320 On the other hand, if the feature is disabled say through
5321 a <filename>.bbappend</filename> file in another layer, then
5322 the second argument <filename>--without-croco</filename> is
5323 added to the configure script rather than
5324 <filename>--with-croco</filename>.
5325 </para>
5326
5327 <para>
5328 The basic <filename>PACKAGECONFIG</filename> structure
5329 previously described holds true regardless of whether you
5330 are creating a block or changing a block.
5331 When creating a block, use the structure inside your
5332 recipe.
5333 </para>
5334
5335 <para>
5336 If you want to change an existing
5337 <filename>PACKAGECONFIG</filename> block, you can do so
5338 one of two ways:
5339 <itemizedlist>
5340 <listitem><para><emphasis>Append file:</emphasis>
5341 Create an append file named
5342 <filename>&lt;recipename&gt;.bbappend</filename> in your
5343 layer and override the value of
5344 <filename>PACKAGECONFIG</filename>.
5345 You can either completely override the variable:
5346 <literallayout class='monospaced'>
5347 PACKAGECONFIG="f4 f5"
5348 </literallayout>
5349 Or, you can just append the variable:
5350 <literallayout class='monospaced'>
5351 PACKAGECONFIG_append = " f4"
5352 </literallayout></para></listitem>
5353 <listitem><para><emphasis>Configuration file:</emphasis>
5354 This method is identical to changing the block
5355 through an append file except you edit your
5356 <filename>local.conf</filename> or
5357 <filename>&lt;mydistro&gt;.conf</filename> file.
5358 As with append files previously described,
5359 you can either completely override the variable:
5360 <literallayout class='monospaced'>
5361 PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
5362 </literallayout>
5363 Or, you can just amend the variable:
5364 <literallayout class='monospaced'>
5365 PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
5366 </literallayout></para></listitem>
5367 </itemizedlist>
5368 </para>
5369 </glossdef>
5370 </glossentry>
5371
5372 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
5373 <glossdef>
5374 <para>The list of packages to be created from the recipe.
5375 The default value is the following:
5376 <literallayout class='monospaced'>
5377 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
5378 </literallayout></para>
5379 </glossdef>
5380 </glossentry>
5381
5382 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
5383 <glossdef>
5384 <para>
5385 A promise that your recipe satisfies runtime dependencies
5386 for optional modules that are found in other recipes.
5387 <filename>PACKAGES_DYNAMIC</filename>
5388 does not actually satisfy the dependencies, it only states that
5389 they should be satisfied.
5390 For example, if a hard, runtime dependency
5391 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5392 of another package is satisfied
5393 at build time through the <filename>PACKAGES_DYNAMIC</filename>
5394 variable, but a package with the module name is never actually
5395 produced, then the other package will be broken.
5396 Thus, if you attempt to include that package in an image,
5397 you will get a dependency failure from the packaging system
5398 during <filename>do_rootfs</filename>.
5399 </para>
5400 <para>
5401 Typically, if there is a chance that such a situation can
5402 occur and the package that is not created is valid
5403 without the dependency being satisfied, then you should use
5404 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
5405 (a soft runtime dependency) instead of
5406 <filename>RDEPENDS</filename>.
5407 </para>
5408
5409 <para>
5410 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
5411 variable when you are splitting packages, see the
5412 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
5413 in the Yocto Project Development Manual.
5414 </para>
5415 </glossdef>
5416 </glossentry>
5417
5418 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
5419 <glossdef>
5420 <para>
5421 Extra options passed to the <filename>make</filename>
5422 command during the <filename>do_compile</filename> task
5423 in order to specify parallel compilation on the local
5424 build host.
5425 This variable is usually in the form "-j &lt;x&gt;",
5426 where x represents the maximum number of parallel threads
5427 <filename>make</filename> can run.
5428 </para>
5429
5430 <para>
5431 If your development host supports multiple cores, a good
5432 rule of thumb is to set this variable to twice the number
5433 of cores on the host.
5434 If you do not set <filename>PARALLEL_MAKE</filename>, it
5435 defaults to the number of cores your build system has.
5436 <note>
5437 Individual recipes might clear out this variable if
5438 the software being built has problems running its
5439 <filename>make</filename> process in parallel.
5440 </note>
5441 </para>
5442 </glossdef>
5443 </glossentry>
5444
5445 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
5446 <glossdef>
5447 <para>
5448 Extra options passed to the
5449 <filename>make install</filename> command during the
5450 <filename>do_install</filename> task in order to specify
5451 parallel installation.
5452 This variable defaults to the value of
5453 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
5454 <note>
5455 Individual recipes might clear out this variable if
5456 the software being built has problems running its
5457 <filename>make install</filename> process in parallel.
5458 </note>
5459 </para>
5460 </glossdef>
5461 </glossentry>
5462
5463 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
5464 <glossdef>
5465 <para>
5466 Determines the action to take when a patch fails.
5467 You can set this variable to one of two values: "noop" and
5468 "user".
5469 </para>
5470
5471 <para>
5472 The default value of "noop" causes the build to simply fail
5473 when the OpenEmbedded build system cannot successfully
5474 apply a patch.
5475 Setting the value to "user" causes the build system to
5476 launch a shell and places you in the right location so that
5477 you can manually resolve the conflicts.
5478 </para>
5479
5480 <para>
5481 Set this variable in your
5482 <filename>local.conf</filename> file.
5483 </para>
5484 </glossdef>
5485 </glossentry>
5486
5487 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
5488 <glossdef>
5489 <para>
5490 Specifies the utility used to apply patches for a recipe
5491 during <filename>do_patch</filename>.
5492 You can specify one of three utilities: "patch", "quilt", or
5493 "git".
5494 The default utility used is "quilt" except for the
5495 quilt-native recipe itself.
5496 Because the quilt tool is not available at the
5497 time quilt-native is being patched, it uses "patch".
5498 </para>
5499
5500 <para>
5501 If you wish to use an alternative patching tool, set the
5502 variable in the recipe using one of the following:
5503 <literallayout class='monospaced'>
5504 PATCHTOOL = "patch"
5505 PATCHTOOL = "quilt"
5506 PATCHTOOL = "git"
5507 </literallayout>
5508 </para>
5509 </glossdef>
5510 </glossentry>
5511
5512 <glossentry id='var-PE'><glossterm>PE</glossterm>
5513 <glossdef>
5514 <para>
5515 The epoch of the recipe.
5516 By default, this variable is unset.
5517 The variable is used to make upgrades possible when the
5518 versioning scheme changes in some backwards incompatible
5519 way.
5520 </para>
5521 </glossdef>
5522 </glossentry>
5523
5524 <glossentry id='var-PF'><glossterm>PF</glossterm>
5525 <glossdef>
5526 <para>Specifies the recipe or package name and includes all version and revision
5527 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
5528 <filename>bash-4.2-r1/</filename>).
5529 This variable is comprised of the following:
5530 <literallayout class='monospaced'>
5531 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
5532 </literallayout></para>
5533 </glossdef>
5534 </glossentry>
5535
5536 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
5537 <glossdef>
5538 <para>
5539 When a recipe inherits the
5540 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
5541 class, this variable identifies packages that contain
5542 the pixbuf loaders used with
5543 <filename>gdk-pixbuf</filename>.
5544 By default, the <filename>pixbufcache</filename> class
5545 assumes that the loaders are in the recipe's main package
5546 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5547 Use this variable if the loaders you need are in a package
5548 other than that main package.
5549 </para>
5550 </glossdef>
5551 </glossentry>
5552
5553 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
5554 <glossdef>
5555 <para>
5556 The name of the resulting package created by the
5557 OpenEmbedded build system.
5558 <note>
5559 When using the <filename>PKG</filename> variable, you
5560 must use a package name override.
5561 </note>
5562 For example, when the
5563 <link linkend='ref-classes-debian'><filename>debian</filename></link>
5564 class renames the output package, it does so by setting
5565 <filename>PKG_&lt;packagename&gt;</filename>.
5566 </para>
5567 </glossdef>
5568 </glossentry>
5569
5570 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
5571 <glossdef>
5572 <para>
5573 Points to the destination directory for files to be
5574 packaged before they are split into individual packages.
5575 This directory defaults to the following:
5576 <literallayout class='monospaced'>
5577 ${WORKDIR}/package
5578 </literallayout>
5579 Do not change this default.
5580 </para>
5581 </glossdef>
5582 </glossentry>
5583
5584 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
5585 <glossdef>
5586 <para>
5587 Points to a shared, global-state directory that holds data
5588 generated during the packaging process.
5589 During the packaging process, the
5590 <filename>do_packagedata</filename> task packages
5591 data for each recipe and installs it into this temporary,
5592 shared area.
5593 This directory defaults to the following:
5594 <literallayout class='monospaced'>
5595 ${STAGING_DIR_HOST}/pkgdata
5596 </literallayout>
5597 Do not change this default.
5598 </para>
5599 </glossdef>
5600 </glossentry>
5601
5602 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
5603 <glossdef>
5604 <para>
5605 Points to the parent directory for files to be packaged
5606 after they have been split into individual packages.
5607 This directory defaults to the following:
5608 <literallayout class='monospaced'>
5609 ${WORKDIR}/packages-split
5610 </literallayout>
5611 Under this directory, the build system creates
5612 directories for each package specified in
5613 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
5614 Do not change this default.
5615 </para>
5616 </glossdef>
5617 </glossentry>
5618
5619 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
5620 <glossdef>
5621 <para>
5622 Points to a temporary work area used by the
5623 <filename>do_package</filename> task to write output
5624 from the <filename>do_packagedata</filename> task.
5625 The <filename>PKGDESTWORK</filename> location defaults to
5626 the following:
5627 <literallayout class='monospaced'>
5628 ${WORKDIR}/pkgdata
5629 </literallayout>
5630 The <filename>do_packagedata</filename> task then packages
5631 the data in the temporary work area and installs it into a
5632 shared directory pointed to by
5633 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
5634 </para>
5635
5636 <para>
5637 Do not change this default.
5638 </para>
5639 </glossdef>
5640 </glossentry>
5641
5642 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
5643 <glossdef>
5644 <para>
5645 The epoch of the output package built by the
5646 OpenEmbedded build system.
5647 By default, <filename>PKGE</filename> is set to
5648 <link linkend='var-PE'><filename>PE</filename></link>.
5649 </para>
5650 </glossdef>
5651 </glossentry>
5652
5653 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
5654 <glossdef>
5655 <para>
5656 The revision of the output package built by the
5657 OpenEmbedded build system.
5658 By default, <filename>PKGR</filename> is set to
5659 <link linkend='var-PR'><filename>PR</filename></link>.
5660 </para>
5661 </glossdef>
5662 </glossentry>
5663
5664 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
5665 <glossdef>
5666 <para>
5667 The version of the output package built by the
5668 OpenEmbedded build system.
5669 By default, <filename>PKGV</filename> is set to
5670 <link linkend='var-PV'><filename>PV</filename></link>.
5671 </para>
5672 </glossdef>
5673 </glossentry>
5674
5675 <glossentry id='var-PN'><glossterm>PN</glossterm>
5676 <glossdef>
5677 <para>This variable can have two separate functions depending on the context: a recipe
5678 name or a resulting package name.</para>
5679 <para><filename>PN</filename> refers to a recipe name in the context of a file used
5680 by the OpenEmbedded build system as input to create a package.
5681 The name is normally extracted from the recipe file name.
5682 For example, if the recipe is named
5683 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
5684 will be "expat".</para>
5685 <para>
5686 The variable refers to a package name in the context of a file created or produced by the
5687 OpenEmbedded build system.</para>
5688 <para>If applicable, the <filename>PN</filename> variable also contains any special
5689 suffix or prefix.
5690 For example, using <filename>bash</filename> to build packages for the native
5691 machine, <filename>PN</filename> is <filename>bash-native</filename>.
5692 Using <filename>bash</filename> to build packages for the target and for Multilib,
5693 <filename>PN</filename> would be <filename>bash</filename> and
5694 <filename>lib64-bash</filename>, respectively.
5695 </para>
5696 </glossdef>
5697 </glossentry>
5698
5699 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
5700 <glossdef>
5701 <para>
5702 Lists recipes you do not want the OpenEmbedded build system
5703 to build.
5704 This variable works in conjunction with the
5705 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
5706 class, which the recipe must inherit globally.
5707 </para>
5708
5709 <para>
5710 To prevent a recipe from being built, inherit the class
5711 globally and use the variable in your
5712 <filename>local.conf</filename> file.
5713 Here is an example that prevents
5714 <filename>myrecipe</filename> from being built:
5715 <literallayout class='monospaced'>
5716 INHERIT += "blacklist"
5717 PNBLACKLIST[myrecipe] = "Not supported by our organization."
5718 </literallayout>
5719 </para>
5720 </glossdef>
5721 </glossentry>
5722
5723 <glossentry id='var-PR'><glossterm>PR</glossterm>
5724 <glossdef>
5725 <para>
5726 The revision of the recipe.
5727 The default value for this variable is "r0".
5728 </para>
5729 </glossdef>
5730 </glossentry>
5731
5732 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
5733 <glossdef>
5734 <para>
5735 If multiple recipes provide an item, this variable
5736 determines which recipe should be given preference.
5737 You should always suffix the variable with the name of the
5738 provided item, and you should set it to the
5739 <link linkend='var-PN'><filename>PN</filename></link>
5740 of the recipe to which you want to give precedence.
5741 Some examples:
5742 <literallayout class='monospaced'>
5743 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
5744 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
5745 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
5746 </literallayout>
5747 </para>
5748 </glossdef>
5749 </glossentry>
5750
5751 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
5752 <glossdef>
5753 <para>
5754 If there are multiple versions of recipes available, this
5755 variable determines which recipe should be given preference.
5756 You must always suffix the variable with the
5757 <link linkend='var-PN'><filename>PN</filename></link>
5758 you want to select, and you should set the
5759 <link linkend='var-PV'><filename>PV</filename></link>
5760 accordingly for precedence.
5761 You can use the "<filename>%</filename>" character as a
5762 wildcard to match any number of characters, which can be
5763 useful when specifying versions that contain long revision
5764 numbers that could potentially change.
5765 Here are two examples:
5766 <literallayout class='monospaced'>
5767 PREFERRED_VERSION_python = "2.7.3"
5768 PREFERRED_VERSION_linux-yocto = "3.10%"
5769 </literallayout>
5770 </para>
5771 </glossdef>
5772 </glossentry>
5773
5774 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
5775 <glossdef>
5776 <para>
5777 Specifies additional paths from which the OpenEmbedded
5778 build system gets source code.
5779 When the build system searches for source code, it first
5780 tries the local download directory.
5781 If that location fails, the build system tries locations
5782 defined by <filename>PREMIRRORS</filename>, the upstream
5783 source, and then locations specified by
5784 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
5785 in that order.
5786 </para>
5787
5788 <para>
5789 Assuming your distribution
5790 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
5791 is "poky", the default value for
5792 <filename>PREMIRRORS</filename> is defined in the
5793 <filename>conf/distro/poky.conf</filename> file in the
5794 <filename>meta-yocto</filename> Git repository.
5795 </para>
5796
5797 <para>
5798 Typically, you could add a specific server for the
5799 build system to attempt before any others by adding
5800 something like the following to the
5801 <filename>local.conf</filename> configuration file in the
5802 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
5803 <literallayout class='monospaced'>
5804 PREMIRRORS_prepend = "\
5805 git://.*/.* http://www.yoctoproject.org/sources/ \n \
5806 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5807 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5808 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5809 </literallayout>
5810 These changes cause the build system to intercept
5811 Git, FTP, HTTP, and HTTPS requests and direct them to
5812 the <filename>http://</filename> sources mirror.
5813 You can use <filename>file://</filename> URLs to point
5814 to local directories or network shares as well.
5815 </para>
5816 </glossdef>
5817 </glossentry>
5818
5819 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
5820 <glossdef>
5821
5822 <para>
5823 The <filename>PRINC</filename> variable has been deprecated
5824 and triggers a warning if detected during a build.
5825 For
5826 <link linkend='var-PR'><filename>PR</filename></link>
5827 increments on changes, use the PR service instead.
5828 You can find out more about this service in the
5829 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
5830 section in the Yocto Project Development Manual.
5831 </para>
5832<!--
5833
5834 <para>
5835 Causes the
5836 <link linkend='var-PR'><filename>PR</filename></link>
5837 variable of <filename>.bbappend</filename> files to
5838 dynamically increment.
5839 This increment minimizes the impact of layer ordering.
5840 </para>
5841
5842 <para>
5843 In order to ensure multiple <filename>.bbappend</filename>
5844 files can co-exist,
5845 <filename>PRINC</filename> should be self-referencing.
5846 This variable defaults to 0.
5847 </para>
5848
5849 <para>
5850 Following is an example that increments
5851 <filename>PR</filename> by two:
5852 <literallayout class='monospaced'>
5853 PRINC := "${@int(PRINC) + 2}"
5854 </literallayout>
5855 It is advisable not to use strings such as ".= '.1'" with the variable because
5856 this usage is very sensitive to layer ordering.
5857 You should avoid explicit assignments as they cannot
5858 adequately represent multiple
5859 <filename>.bbappend</filename> files.
5860 </para>
5861-->
5862 </glossdef>
5863 </glossentry>
5864
5865 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
5866 <glossdef>
5867 <para>
5868 A list of aliases that a recipe also provides.
5869 These aliases are useful for satisfying dependencies of
5870 other recipes during the build (as specified by
5871 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>).
5872 <note>
5873 A recipe's own
5874 <filename><link linkend='var-PN'>PN</link></filename>
5875 is implicitly already in its
5876 <filename>PROVIDES</filename> list.
5877 </note>
5878 </para>
5879 </glossdef>
5880 </glossentry>
5881
5882 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
5883 <glossdef>
5884 <para>
5885 The network based
5886 <link linkend='var-PR'><filename>PR</filename></link>
5887 service host and port.
5888 </para>
5889
5890 <para>
5891 The <filename>conf/local.conf.sample.extended</filename>
5892 configuration file in the
5893 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
5894 shows how the <filename>PRSERV_HOST</filename> variable is
5895 set:
5896 <literallayout class='monospaced'>
5897 PRSERV_HOST = "localhost:0"
5898 </literallayout>
5899 You must set the variable if you want to automatically
5900 start a local
5901 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
5902 You can set <filename>PRSERV_HOST</filename> to other
5903 values to use a remote PR service.
5904 </para>
5905 </glossdef>
5906 </glossentry>
5907
5908 <glossentry id='var-PV'><glossterm>PV</glossterm>
5909 <glossdef>
5910 <para>
5911 The version of the recipe.
5912 The version is normally extracted from the recipe filename.
5913 For example, if the recipe is named
5914 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
5915 will be "2.0.1".
5916 <filename>PV</filename> is generally not overridden within
5917 a recipe unless it is building an unstable (i.e. development) version from a source code repository
5918 (e.g. Git or Subversion).
5919 </para>
5920 </glossdef>
5921 </glossentry>
5922
5923 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
5924 <glossdef>
5925 <para>
5926 When used by recipes that inherit the
5927 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
5928 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
5929 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
5930 or
5931 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
5932 classes, denotes the Application Binary Interface (ABI)
5933 currently in use for Python.
5934 By default, the ABI is "m".
5935 You do not have to set this variable as the OpenEmbedded
5936 build system sets it for you.
5937 </para>
5938
5939 <para>
5940 The OpenEmbedded build system uses the ABI to construct
5941 directory names used when installing the Python headers
5942 and libraries in sysroot
5943 (e.g. <filename>.../python3.3m/...</filename>).
5944 </para>
5945
5946 <para>
5947 Recipes that inherit the
5948 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
5949 class during cross-builds also use this variable to
5950 locate the headers and libraries of the appropriate Python
5951 that the extension is targeting.
5952 </para>
5953 </glossdef>
5954 </glossentry>
5955
5956 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
5957 <glossdef>
5958 <para>
5959 When used by recipes that inherit the
5960 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
5961 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
5962 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
5963 or
5964 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
5965 classes, specifies the major Python version being built.
5966 For Python 2.x, <filename>PYTHON_PN</filename> would
5967 be "python2". For Python 3.x, the variable would be
5968 "python3".
5969 You do not have to set this variable as the
5970 OpenEmbedded build system automatically sets it for you.
5971 </para>
5972
5973 <para>
5974 The variable allows recipes to use common infrastructure
5975 such as the following:
5976 <literallayout class='monospaced'>
5977 DEPENDS += "${PYTHON_PN}-native"
5978 </literallayout>
5979 In the previous example, the version of the dependency
5980 is <filename>PYTHON_PN</filename>.
5981 </para>
5982 </glossdef>
5983 </glossentry>
5984
5985 </glossdiv>
5986
5987 <glossdiv id='var-glossary-q'><title>Q</title>
5988
5989 <glossentry id='var-QMAKE_PROFILES'><glossterm>QMAKE_PROFILES</glossterm>
5990 <glossdef>
5991 <para>
5992 Specifies your own subset of <filename>.pro</filename>
5993 files to be built for use with
5994 <filename>qmake</filename>.
5995 If you do not set this variable, all
5996 <filename>.pro</filename> files in the directory pointed to
5997 by <link linkend='var-S'><filename>S</filename></link>
5998 will be built by default.
5999 </para>
6000
6001 <para>
6002 This variable is used with recipes that inherit the
6003 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
6004 class or other classes that inherit
6005 <filename>qmake_base</filename>.
6006 </para>
6007 </glossdef>
6008 </glossentry>
6009
6010 </glossdiv>
6011
6012 <glossdiv id='var-glossary-r'><title>R</title>
6013
6014 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
6015 <glossdef>
6016 <para>
6017 The list of packages that conflict with packages.
6018 Note that packages will not be installed if conflicting
6019 packages are not first removed.
6020 </para>
6021
6022 <para>
6023 Like all package-controlling variables, you must always use
6024 them in conjunction with a package name override.
6025 Here is an example:
6026 <literallayout class='monospaced'>
6027 RCONFLICTS_${PN} = "another-conflicting-package-name"
6028 </literallayout>
6029 </para>
6030
6031 <para>
6032 BitBake, which the OpenEmbedded build system uses, supports
6033 specifying versioned dependencies.
6034 Although the syntax varies depending on the packaging
6035 format, BitBake hides these differences from you.
6036 Here is the general syntax to specify versions with
6037 the <filename>RCONFLICTS</filename> variable:
6038 <literallayout class='monospaced'>
6039 RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6040 </literallayout>
6041 For <filename>operator</filename>, you can specify the
6042 following:
6043 <literallayout class='monospaced'>
6044 =
6045 &lt;
6046 &gt;
6047 &lt;=
6048 &gt;=
6049 </literallayout>
6050 For example, the following sets up a dependency on version
6051 1.2 or greater of the package <filename>foo</filename>:
6052 <literallayout class='monospaced'>
6053 RCONFLICTS_${PN} = "foo (>= 1.2)"
6054 </literallayout>
6055 </para>
6056 </glossdef>
6057 </glossentry>
6058
6059 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
6060 <glossdef>
6061 <para>
6062 Lists a package's runtime dependencies (i.e. other packages)
6063 that must be installed in order for the built package to run
6064 correctly.
6065 If a package in this list cannot be found during the build,
6066 you will get a build error.
6067 </para>
6068
6069 <para>
6070 When you use the <filename>RDEPENDS</filename> variable
6071 in a recipe, you are essentially stating that the recipe's
6072 <filename>do_build</filename> task depends on the existence
6073 of a specific package.
6074 Consider this simple example for two recipes named "a" and
6075 "b" that produce similarly named IPK packages.
6076 In this example, the <filename>RDEPENDS</filename>
6077 statement appears in the "a" recipe:
6078 <literallayout class='monospaced'>
6079 RDEPENDS_${PN} = "b"
6080 </literallayout>
6081 Here, the dependency is such that the
6082 <filename>do_build</filename> task for recipe "a" depends
6083 on the <filename>do_package_write_ipk</filename> task
6084 of recipe "b".
6085 This means the package file for "b" must be available when
6086 the output for recipe "a" has been completely built.
6087 More importantly, package "a" will be marked as depending
6088 on package "b" in a manner that is understood by the
6089 package manager.
6090 </para>
6091
6092 <para>
6093 The names of the packages you list within
6094 <filename>RDEPENDS</filename> must be the names of other
6095 packages - they cannot be recipe names.
6096 Although package names and recipe names usually match,
6097 the important point here is that you are
6098 providing package names within the
6099 <filename>RDEPENDS</filename> variable.
6100 For an example of the default list of packages created from
6101 a recipe, see the
6102 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
6103 variable.
6104 </para>
6105
6106 <para>
6107 Because the <filename>RDEPENDS</filename> variable applies
6108 to packages being built, you should always use the variable
6109 in a form with an attached package name.
6110 For example, suppose you are building a development package
6111 that depends on the <filename>perl</filename> package.
6112 In this case, you would use the following
6113 <filename>RDEPENDS</filename> statement:
6114 <literallayout class='monospaced'>
6115 RDEPENDS_${PN}-dev += "perl"
6116 </literallayout>
6117 In the example, the development package depends on
6118 the <filename>perl</filename> package.
6119 Thus, the <filename>RDEPENDS</filename> variable has the
6120 <filename>${PN}-dev</filename> package name as part of the
6121 variable.
6122 </para>
6123
6124 <para>
6125 The package name you attach to the
6126 <filename>RDEPENDS</filename> variable must appear
6127 as it would in the <filename>PACKAGES</filename>
6128 namespace before any renaming of the output package by
6129 classes like <filename>debian.bbclass</filename>.
6130 </para>
6131
6132 <para>
6133 In many cases you do not need to explicitly add
6134 runtime dependencies using
6135 <filename>RDEPENDS</filename> since some automatic
6136 handling occurs:
6137 <itemizedlist>
6138 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
6139 a runtime package contains a shared library
6140 (<filename>.so</filename>), the build
6141 processes the library in order to determine other
6142 libraries to which it is dynamically linked.
6143 The build process adds these libraries to
6144 <filename>RDEPENDS</filename> when creating the runtime
6145 package.</para></listitem>
6146 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
6147 the package ships a <filename>pkg-config</filename>
6148 information file, the build process uses this file
6149 to add items to the <filename>RDEPENDS</filename>
6150 variable to create the runtime packages.
6151 </para></listitem>
6152 </itemizedlist>
6153 </para>
6154
6155 <para>
6156 BitBake, which the OpenEmbedded build system uses, supports
6157 specifying versioned dependencies.
6158 Although the syntax varies depending on the packaging
6159 format, BitBake hides these differences from you.
6160 Here is the general syntax to specify versions with
6161 the <filename>RDEPENDS</filename> variable:
6162 <literallayout class='monospaced'>
6163 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6164 </literallayout>
6165 For <filename>operator</filename>, you can specify the
6166 following:
6167 <literallayout class='monospaced'>
6168 =
6169 &lt;
6170 &gt;
6171 &lt;=
6172 &gt;=
6173 </literallayout>
6174 For example, the following sets up a dependency on version
6175 1.2 or greater of the package <filename>foo</filename>:
6176 <literallayout class='monospaced'>
6177 RDEPENDS_${PN} = "foo (>= 1.2)"
6178 </literallayout>
6179 </para>
6180
6181 <para>
6182 For information on build-time dependencies, see the
6183 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
6184 variable.
6185 </para>
6186 </glossdef>
6187 </glossentry>
6188
6189 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
6190 <glossdef>
6191 <para>
6192 When a recipe inherits the
6193 <filename>distro_features_check</filename> class, this
6194 variable identifies distribution features that must
6195 exist in the current configuration in order for the
6196 OpenEmbedded build system to build the recipe.
6197 In other words, if the
6198 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
6199 lists a feature that does not appear in
6200 <filename>DISTRO_FEATURES</filename> within the
6201 current configuration, an error occurs and the
6202 build stops.
6203 </para>
6204 </glossdef>
6205 </glossentry>
6206
6207 <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
6208 <glossdef>
6209 <para>
6210 Reclaims disk space by removing previously built
6211 versions of the same image from the
6212 <filename>images</filename> directory pointed to by the
6213 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
6214 variable.
6215 </para>
6216
6217 <para>
6218 Set this variable to "1" in your
6219 <filename>local.conf</filename> file to remove these
6220 images.
6221 </para>
6222 </glossdef>
6223 </glossentry>
6224
6225 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
6226 <glossdef>
6227 <para>
6228 With <filename>rm_work</filename> enabled, this
6229 variable specifies a list of recipes whose work directories
6230 should not be removed.
6231 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
6232 section for more details.
6233 </para>
6234 </glossdef>
6235 </glossentry>
6236
6237 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
6238 <glossdef>
6239 <para>
6240 Defines the root home directory.
6241 By default, this directory is set as follows in the
6242 BitBake configuration file:
6243 <literallayout class='monospaced'>
6244 ROOT_HOME ??= "/home/root"
6245 </literallayout>
6246 <note>
6247 This default value is likely used because some
6248 embedded solutions prefer to have a read-only root
6249 filesystem and prefer to keep writeable data in one
6250 place.
6251 </note>
6252 </para>
6253
6254 <para>
6255 You can override the default by setting the variable
6256 in any layer or in the <filename>local.conf</filename> file.
6257 Because the default is set using a "weak" assignment
6258 (i.e. "??="), you can use either of the following forms
6259 to define your override:
6260 <literallayout class='monospaced'>
6261 ROOT_HOME = "/root"
6262 ROOT_HOME ?= "/root"
6263 </literallayout>
6264 These override examples use <filename>/root</filename>,
6265 which is probably the most commonly used override.
6266 </para>
6267 </glossdef>
6268 </glossentry>
6269
6270 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
6271 <glossdef>
6272 <para>
6273 Indicates a filesystem image to include as the root
6274 filesystem.
6275 </para>
6276
6277 <para>
6278 The <filename>ROOTFS</filename> variable is an optional
6279 variable used with the
6280 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
6281 class.
6282 </para>
6283 </glossdef>
6284 </glossentry>
6285
6286 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
6287 <glossdef>
6288 <para>
6289 Added by classes to run post processing commands once the
6290 OpenEmbedded build system has created the root filesystem.
6291 You can specify shell commands separated by semicolons:
6292 <literallayout class='monospaced'>
6293 ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
6294 </literallayout>
6295 If you need to pass the path to the root filesystem within
6296 the command, you can use
6297 <filename>${IMAGE_ROOTFS}</filename>, which points to
6298 the root filesystem image.
6299 </para>
6300 </glossdef>
6301 </glossentry>
6302
6303 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
6304 <glossdef>
6305 <para>
6306 A list of package name aliases that a package also provides.
6307 These aliases are useful for satisfying runtime dependencies
6308 of other packages both during the build and on the target
6309 (as specified by
6310 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
6311 <note>
6312 A package's own name is implicitly already in its
6313 <filename>RPROVIDES</filename> list.
6314 </note>
6315 </para>
6316 <para>
6317 As with all package-controlling variables, you must always
6318 use the variable in conjunction with a package name override.
6319 Here is an example:
6320 <literallayout class='monospaced'>
6321 RPROVIDES_${PN} = "widget-abi-2"
6322 </literallayout>
6323 </para>
6324 </glossdef>
6325 </glossentry>
6326
6327 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
6328 <glossdef>
6329 <para>
6330 A list of packages that extends the usability of a package
6331 being built.
6332 The package being built does not depend on this list of
6333 packages in order to successfully build, but needs them for
6334 the extended usability.
6335 To specify runtime dependencies for packages, see the
6336 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
6337 variable.
6338 </para>
6339
6340 <para>
6341 The OpenEmbedded build process automatically installs the
6342 list of packages as part of the built package.
6343 However, you can remove these packages later if you want.
6344 If, during the build, a package from the
6345 <filename>RRECOMMENDS</filename> list cannot be
6346 found, the build process continues without an error.
6347 </para>
6348
6349 <para>
6350 You can also prevent packages in the list from being
6351 installed by using several variables.
6352 See the
6353 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
6354 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
6355 and
6356 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
6357 variables for more information.
6358 </para>
6359
6360 <para>
6361 Because the <filename>RRECOMMENDS</filename> variable
6362 applies to packages being built, you should always attach
6363 an override to the variable to specify the particular
6364 package whose usability is being extended.
6365 For example, suppose you are building a development package
6366 that is extended to support wireless functionality.
6367 In this case, you would use the following:
6368 <literallayout class='monospaced'>
6369 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
6370 </literallayout>
6371 In the example, the package name
6372 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
6373 must appear as it would in the
6374 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
6375 namespace before any renaming of the output package by
6376 classes such as <filename>debian.bbclass</filename>.
6377 </para>
6378
6379 <para>
6380 BitBake, which the OpenEmbedded build system uses, supports
6381 specifying versioned recommends.
6382 Although the syntax varies depending on the packaging
6383 format, BitBake hides these differences from you.
6384 Here is the general syntax to specify versions with
6385 the <filename>RRECOMMENDS</filename> variable:
6386 <literallayout class='monospaced'>
6387 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6388 </literallayout>
6389 For <filename>operator</filename>, you can specify the
6390 following:
6391 <literallayout class='monospaced'>
6392 =
6393 &lt;
6394 &gt;
6395 &lt;=
6396 &gt;=
6397 </literallayout>
6398 For example, the following sets up a recommend on version
6399 1.2 or greater of the package <filename>foo</filename>:
6400 <literallayout class='monospaced'>
6401 RRECOMMENDS_${PN} = "foo (>= 1.2)"
6402 </literallayout>
6403 </para>
6404 </glossdef>
6405 </glossentry>
6406
6407 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
6408 <glossdef>
6409 <para>
6410 A list of packages replaced by a package.
6411 The package manager uses this variable to determine which
6412 package should be installed to replace other package(s)
6413 during an upgrade.
6414 In order to also have the other package(s) removed at the
6415 same time, you must add the name of the other
6416 package to the
6417 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
6418 </para>
6419 <para>
6420 As with all package-controlling variables, you must use
6421 this variable in conjunction with a package name
6422 override.
6423 Here is an example:
6424 <literallayout class='monospaced'>
6425 RREPLACES_${PN} = "other-package-being-replaced"
6426 </literallayout>
6427 </para>
6428
6429 <para>
6430 BitBake, which the OpenEmbedded build system uses, supports
6431 specifying versioned replacements.
6432 Although the syntax varies depending on the packaging
6433 format, BitBake hides these differences from you.
6434 Here is the general syntax to specify versions with
6435 the <filename>RREPLACES</filename> variable:
6436 <literallayout class='monospaced'>
6437 RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6438 </literallayout>
6439 For <filename>operator</filename>, you can specify the
6440 following:
6441 <literallayout class='monospaced'>
6442 =
6443 &lt;
6444 &gt;
6445 &lt;=
6446 &gt;=
6447 </literallayout>
6448 For example, the following sets up a replacement using
6449 version 1.2 or greater of the package
6450 <filename>foo</filename>:
6451 <literallayout class='monospaced'>
6452 RREPLACES_${PN} = "foo (>= 1.2)"
6453 </literallayout>
6454 </para>
6455 </glossdef>
6456 </glossentry>
6457
6458 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
6459 <glossdef>
6460 <para>
6461 A list of additional packages that you can suggest for
6462 installation by the package manager at the time a package
6463 is installed.
6464 Not all package managers support this functionality.
6465 </para>
6466 <para>
6467 As with all package-controlling variables, you must always
6468 use this variable in conjunction with a package name
6469 override.
6470 Here is an example:
6471 <literallayout class='monospaced'>
6472 RSUGGESTS_${PN} = "useful-package another-package"
6473 </literallayout>
6474 </para>
6475 </glossdef>
6476 </glossentry>
6477
6478 </glossdiv>
6479
6480 <glossdiv id='var-glossary-s'><title>S</title>
6481
6482 <glossentry id='var-S'><glossterm>S</glossterm>
6483 <glossdef>
6484 <para>
6485 The location in the
6486 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
6487 where unpacked recipe source code resides.
6488 This location is within the work directory
6489 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
6490 which is not static.
6491 The unpacked source location depends on the recipe name
6492 (<filename><link linkend='var-PN'>PN</link></filename>) and
6493 recipe version
6494 (<filename><link linkend='var-PV'>PV</link></filename>) as
6495 follows:
6496 <literallayout class='monospaced'>
6497 ${WORKDIR}/${PN}-${PV}
6498 </literallayout>
6499 As an example, assume a
6500 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
6501 top-level folder named <filename>poky</filename> and a
6502 default Build Directory at <filename>poky/build</filename>.
6503 In this case, the work directory the build system uses
6504 to keep the unpacked recipe for <filename>db</filename>
6505 is the following:
6506 <literallayout class='monospaced'>
6507 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
6508 </literallayout>
6509 </para>
6510 </glossdef>
6511 </glossentry>
6512
6513 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
6514 <glossdef>
6515 <para>
6516 A list of the host distribution identifiers that the
6517 build system has been tested against.
6518 Identifiers consist of the host distributor ID
6519 followed by the release,
6520 as reported by the <filename>lsb_release</filename> tool
6521 or as read from <filename>/etc/lsb-release</filename>.
6522 Separate the list items with explicit newline
6523 characters (<filename>\n</filename>).
6524 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
6525 and the current value of
6526 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
6527 does not appear in the list, then the build system reports
6528 a warning that indicates the current host distribution has
6529 not been tested as a build host.
6530 </para>
6531 </glossdef>
6532 </glossentry>
6533
6534 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
6535 <glossdef>
6536 <para>
6537 The target architecture for the SDK.
6538 Typically, you do not directly set this variable.
6539 Instead, use
6540 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
6541 </para>
6542 </glossdef>
6543 </glossentry>
6544
6545 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
6546 <glossdef>
6547 <para>
6548 The directory set up and used by the
6549 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
6550 to which the SDK is deployed.
6551 The <filename>populate_sdk_base</filename> class defines
6552 <filename>SDK_DEPLOY</filename> as follows:
6553 <literallayout class='monospaced'>
6554 SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk"
6555 </literallayout>
6556 </para>
6557 </glossdef>
6558 </glossentry>
6559
6560 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
6561 <glossdef>
6562 <para>
6563 The parent directory used by the OpenEmbedded build system
6564 when creating SDK output.
6565 The
6566 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
6567 class defines the variable as follows:
6568 <literallayout class='monospaced'>
6569 SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"
6570 </literallayout>
6571 <note>
6572 The <filename>SDK_DIR</filename> directory is a
6573 temporary directory as it is part of
6574 <filename>WORKDIR</filename>.
6575 The final output directory is
6576 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
6577 </note>
6578 </para>
6579 </glossdef>
6580 </glossentry>
6581
6582 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
6583 <glossdef>
6584 <para>
6585 The base name for SDK output files.
6586 The name is derived from the
6587 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
6588 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
6589 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
6590 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
6591 and
6592 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
6593 variables:
6594 <literallayout class='monospaced'>
6595 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
6596 </literallayout>
6597 </para>
6598 </glossdef>
6599 </glossentry>
6600
6601 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
6602 <glossdef>
6603 <para>
6604 The location used by the OpenEmbedded build system when
6605 creating SDK output.
6606 The
6607 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
6608 class defines the variable as follows:
6609 <literallayout class='monospaced'>
6610 SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"
6611 </literallayout>
6612 <note>
6613 The <filename>SDK_OUTPUT</filename> directory is a
6614 temporary directory as it is part of
6615 <filename>WORKDIR</filename> by way of
6616 <filename>SDK_DIR</filename>.
6617 The final output directory is
6618 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
6619 </note>
6620
6621 </para>
6622 </glossdef>
6623 </glossentry>
6624
6625 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
6626 <glossdef>
6627 <para>Equivalent to
6628 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
6629 However, this variable applies to the SDK generated from an
6630 image using the following command:
6631 <literallayout class='monospaced'>
6632 $ bitbake -c populate_sdk imagename
6633 </literallayout>
6634 </para>
6635 </glossdef>
6636 </glossentry>
6637
6638 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
6639 <glossdef>
6640 <para>
6641 The architecture of the machine that runs Application
6642 Development Toolkit (ADT) items.
6643 In other words, packages are built so that they will run
6644 on the target you specify with the argument.
6645 This implies that you can build out ADT/SDK items that
6646 run on an architecture other than that of your build host.
6647 For example, you can use an x86_64-based build host to
6648 create packages that will run on an i686-based
6649 SDK Machine.
6650 </para>
6651
6652 <para>
6653 You can use "i686" and "x86_64" as possible values for this
6654 variable.
6655 The variable defaults to "i686" and is set in the
6656 <filename>local.conf</filename> file in the
6657 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
6658 <literallayout class='monospaced'>
6659 SDKMACHINE ?= "i686"
6660 </literallayout>
6661 <note>
6662 You cannot set the <filename>SDKMACHINE</filename>
6663 variable in your distribution configuration file.
6664 If you do, the configuration will not take affect.
6665 </note>
6666 </para>
6667 </glossdef>
6668 </glossentry>
6669
6670 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
6671 <glossdef>
6672 <para>
6673 Defines the path offered to the user for installation
6674 of the SDK that is generated by the OpenEmbedded build
6675 system.
6676 The path appears as the default location for installing
6677 the SDK when you run the SDK's installation script.
6678 You can override the offered path when you run the
6679 script.
6680 </para>
6681 </glossdef>
6682 </glossentry>
6683
6684 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
6685 <glossdef>
6686 <para>The section in which packages should be categorized.
6687 Package management utilities can make use of this variable.</para>
6688 </glossdef>
6689 </glossentry>
6690
6691 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
6692 <glossdef>
6693 <para>
6694 The variable takes the value of
6695 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
6696 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
6697 In this case the value of
6698 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
6699 </para>
6700 </glossdef>
6701 </glossentry>
6702
6703 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
6704 <glossdef>
6705 <para>
6706 Defines a serial console (TTY) to enable using getty.
6707 Provide a value that specifies the baud rate followed by
6708 the TTY device name separated by a space.
6709 You cannot specify more than one TTY device:
6710 <literallayout class='monospaced'>
6711 SERIAL_CONSOLE = "115200 ttyS0"
6712 </literallayout>
6713 <note>
6714 The <filename>SERIAL_CONSOLE</filename> variable
6715 is deprecated.
6716 Please use the
6717 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
6718 variable.
6719 </note>
6720 </para>
6721 </glossdef>
6722 </glossentry>
6723
6724 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
6725 <glossdef>
6726 <para>
6727 Defines the serial consoles (TTYs) to enable using getty.
6728 Provide a value that specifies the baud rate followed by
6729 the TTY device name separated by a semicolon.
6730 Use spaces to separate multiple devices:
6731 <literallayout class='monospaced'>
6732 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
6733 </literallayout>
6734 </para>
6735 </glossdef>
6736 </glossentry>
6737
6738 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
6739 <glossdef>
6740 <para>
6741 Similar to
6742 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
6743 except the device is checked for existence before attempting
6744 to enable it.
6745 This variable is currently only supported with SysVinit
6746 (i.e. not with systemd).
6747 </para>
6748 </glossdef>
6749 </glossentry>
6750
6751 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
6752 <glossdef>
6753 <para>
6754 A list of recipe dependencies that should not be used to
6755 determine signatures of tasks from one recipe when they
6756 depend on tasks from another recipe.
6757 For example:
6758 <literallayout class='monospaced'>
6759 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
6760 </literallayout>
6761 In this example, <filename>intone</filename> depends on
6762 <filename>mplayer2</filename>.
6763 </para>
6764
6765 <para>
6766 Use of this variable is one mechanism to remove dependencies
6767 that affect task signatures and thus force rebuilds when a
6768 recipe changes.
6769 <note><title>Caution</title>
6770 If you add an inappropriate dependency for a recipe
6771 relationship, the software might break during
6772 runtime if the interface of the second recipe was
6773 changed after the first recipe had been built.
6774 </note>
6775 </para>
6776 </glossdef>
6777 </glossentry>
6778
6779 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
6780 <glossdef>
6781 <para>
6782 A list of recipes that are completely stable and will
6783 never change.
6784 The ABI for the recipes in the list are presented by
6785 output from the tasks run to build the recipe.
6786 Use of this variable is one way to remove dependencies from
6787 one recipe on another that affect task signatures and
6788 thus force rebuilds when the recipe changes.
6789 <note><title>Caution</title>
6790 If you add an inappropriate variable to this list,
6791 the software might break at runtime if the
6792 interface of the recipe was changed after the other
6793 had been built.
6794 </note>
6795 </para>
6796 </glossdef>
6797 </glossentry>
6798
6799 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
6800 <glossdef>
6801 <para>
6802 Specifies the number of bits for the target system CPU.
6803 The value should be either "32" or "64".
6804 </para>
6805 </glossdef>
6806 </glossentry>
6807
6808 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
6809 <glossdef>
6810 <para>
6811 Specifies the endian byte order of the target system.
6812 The value should be either "le" for little-endian or "be" for big-endian.
6813 </para>
6814 </glossdef>
6815 </glossentry>
6816
6817 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
6818 <glossdef>
6819 <para>
6820 Groups together machines based upon the same family
6821 of SOC (System On Chip).
6822 You typically set this variable in a common
6823 <filename>.inc</filename> file that you include in the
6824 configuration files of all the machines.
6825 <note>
6826 You must include
6827 <filename>conf/machine/include/soc-family.inc</filename>
6828 for this variable to appear in
6829 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
6830 </note>
6831 </para>
6832 </glossdef>
6833 </glossentry>
6834
6835 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
6836 <glossdef>
6837 <para>
6838 Defines the suffix for shared libraries used on the
6839 target platform.
6840 By default, this suffix is ".so.*" for all Linux-based
6841 systems and is defined in the
6842 <filename>meta/conf/bitbake.conf</filename> configuration
6843 file.
6844 </para>
6845
6846 <para>
6847 You will see this variable referenced in the default values
6848 of <filename>FILES_${PN}</filename>.
6849 </para>
6850 </glossdef>
6851 </glossentry>
6852
6853 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
6854 <glossdef>
6855 <para>
6856 Defines the suffix for the development symbolic link
6857 (symlink) for shared libraries on the target platform.
6858 By default, this suffix is ".so" for Linux-based
6859 systems and is defined in the
6860 <filename>meta/conf/bitbake.conf</filename> configuration
6861 file.
6862 </para>
6863
6864 <para>
6865 You will see this variable referenced in the default values
6866 of <filename>FILES_${PN}-dev</filename>.
6867 </para>
6868 </glossdef>
6869 </glossentry>
6870
6871 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
6872 <glossdef>
6873 <para>
6874 Defines your own
6875 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
6876 from which to first fetch source before attempting to fetch
6877 from the upstream specified in
6878 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
6879 </para>
6880
6881 <para>
6882 To use this variable, you must globally inherit the
6883 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
6884 class and then provide the URL to your mirrors.
6885 Here is an example:
6886 <literallayout class='monospaced'>
6887 INHERIT += "own-mirrors"
6888 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
6889 </literallayout>
6890 <note>
6891 You can specify only a single URL in
6892 <filename>SOURCE_MIRROR_URL</filename>.
6893 </note>
6894 </para>
6895 </glossdef>
6896 </glossentry>
6897
6898 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
6899 <glossdef>
6900 <para>
6901 Maps commonly used license names to their SPDX counterparts
6902 found in <filename>meta/files/common-licenses/</filename>.
6903 For the default <filename>SPDXLICENSEMAP</filename>
6904 mappings, see the
6905 <filename>meta/conf/licenses.conf</filename> file.
6906 </para>
6907
6908 <para>
6909 For additional information, see the
6910 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
6911 variable.
6912 </para>
6913 </glossdef>
6914 </glossentry>
6915
6916 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
6917 <glossdef>
6918 <para>
6919 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
6920 OpenEmbedded build system to create variants of recipes or packages.
6921 The list specifies the prefixes to strip off during certain circumstances
6922 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
6923 </para>
6924 </glossdef>
6925 </glossentry>
6926
6927 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
6928 <glossdef>
6929 <para>The list of source files - local or remote.
6930 This variable tells the OpenEmbedded build system which bits
6931 to pull in for the build and how to pull them in.
6932 For example, if the recipe or append file only needs to
6933 fetch a tarball from the Internet, the recipe or
6934 append file uses a single <filename>SRC_URI</filename>
6935 entry.
6936 On the other hand, if the recipe or append file needs to
6937 fetch a tarball, apply two patches, and include a custom
6938 file, the recipe or append file would include four
6939 instances of the variable.</para>
6940 <para>The following list explains the available URI protocols:
6941 <itemizedlist>
6942 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
6943 Fetches files, which are usually files shipped with
6944 the
6945 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
6946 from the local machine.
6947 The path is relative to the
6948 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
6949 variable.
6950 Thus, the build system searches, in order, from the
6951 following directories, which are assumed to be a
6952 subdirectories of the directory in which the
6953 recipe file (<filename>.bb</filename>) or
6954 append file (<filename>.bbappend</filename>)
6955 resides:
6956 <itemizedlist>
6957 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
6958 The base recipe name without any special
6959 suffix or version numbers.
6960 </para></listitem>
6961 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
6962 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
6963 The base recipe name and version but without
6964 any special package name suffix.
6965 </para></listitem>
6966 <listitem><para><emphasis>files -</emphasis>
6967 Files within a directory, which is named
6968 <filename>files</filename> and is also
6969 alongside the recipe or append file.
6970 </para></listitem>
6971 </itemizedlist>
6972 <note>
6973 If you want the build system to pick up files
6974 specified through a
6975 <filename>SRC_URI</filename>
6976 statement from your append file, you need to be
6977 sure to extend the
6978 <filename>FILESPATH</filename>
6979 variable by also using the
6980 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
6981 variable from within your append file.
6982 </note>
6983 </para></listitem>
6984 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
6985 Bazaar revision control repository.</para></listitem>
6986 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
6987 Git revision control repository.</para></listitem>
6988 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
6989 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
6990 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
6991 a repo (Git) repository.</para></listitem>
6992 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
6993 an SVK revision control repository.</para></listitem>
6994 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
6995 the Internet using <filename>http</filename>.</para></listitem>
6996 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
6997 from the Internet using <filename>https</filename>.</para></listitem>
6998 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
6999 from the Internet using <filename>ftp</filename>.</para></listitem>
7000 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
7001 a CVS revision control repository.</para></listitem>
7002 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
7003 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
7004 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
7005 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
7006 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
7007 a secure shell.</para></listitem>
7008 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
7009 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
7010 </itemizedlist>
7011 </para>
7012 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
7013 Here are standard options:
7014 <itemizedlist>
7015 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
7016 the patch or not.
7017 The default action is to apply the patch.</para></listitem>
7018 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
7019 striplevel to use when applying the patch.
7020 The default level is 1.</para></listitem>
7021 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
7022 the directory in which the patch should be applied.
7023 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
7024 </para></listitem>
7025 </itemizedlist>
7026 </para>
7027 <para>Here are options specific to recipes building code from a revision control system:
7028 <itemizedlist>
7029 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
7030 Apply the patch only if
7031 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
7032 is equal to or greater than <filename>mindate</filename>.
7033 </para></listitem>
7034 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
7035 Apply the patch only if <filename>SRCDATE</filename>
7036 is not later than <filename>mindate</filename>.
7037 </para></listitem>
7038 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
7039 Apply the patch only if <filename>SRCREV</filename>
7040 is equal to or greater than <filename>minrev</filename>.
7041 </para></listitem>
7042 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
7043 Apply the patch only if <filename>SRCREV</filename>
7044 is not later than <filename>maxrev</filename>.
7045 </para></listitem>
7046 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
7047 Apply the patch only if <filename>SRCREV</filename>
7048 is equal to <filename>rev</filename>.
7049 </para></listitem>
7050 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
7051 Apply the patch only if <filename>SRCREV</filename>
7052 is not equal to <filename>rev</filename>.
7053 </para></listitem>
7054 </itemizedlist>
7055 </para>
7056 <para>Here are some additional options worth mentioning:
7057 <itemizedlist>
7058 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
7059 whether or not to unpack the file if it is an archive.
7060 The default action is to unpack the file.</para></listitem>
7061 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
7062 (or extracts its contents) into the specified
7063 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
7064 This option is useful for unusual tarballs or other archives that
7065 do not have their files already in a subdirectory within the archive.
7066 </para></listitem>
7067 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
7068 name to be used for association with <filename>SRC_URI</filename> checksums
7069 when you have more than one file specified in <filename>SRC_URI</filename>.
7070 </para></listitem>
7071 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
7072 the filename used when storing the downloaded file.</para></listitem>
7073 </itemizedlist>
7074 </para>
7075 </glossdef>
7076 </glossentry>
7077
7078 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
7079 <glossdef>
7080 <para></para>
7081 <para>
7082 By default, the OpenEmbedded build system automatically detects whether
7083 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
7084 contains files that are machine-specific.
7085 If so, the build system automatically changes
7086 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
7087 Setting this variable to "0" disables this behavior.
7088 </para>
7089 </glossdef>
7090 </glossentry>
7091
7092 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
7093 <glossdef>
7094 <para>
7095 The date of the source code used to build the package.
7096 This variable applies only if the source was fetched from a Source Code Manager (SCM).
7097 </para>
7098 </glossdef>
7099 </glossentry>
7100
7101 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
7102 <glossdef>
7103 <para>
7104 Returns the version string of the current package.
7105 This string is used to help define the value of
7106 <link linkend='var-PV'><filename>PV</filename></link>.
7107 </para>
7108
7109 <para>
7110 The <filename>SRCPV</filename> variable is defined in the
7111 <filename>meta/conf/bitbake.conf</filename> configuration
7112 file in the
7113 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
7114 as follows:
7115 <literallayout class='monospaced'>
7116 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7117 </literallayout>
7118 </para>
7119
7120 <para>
7121 Recipes that need to define <filename>PV</filename> do so
7122 with the help of the <filename>SRCPV</filename>.
7123 For example, the <filename>ofono</filename> recipe
7124 (<filename>ofono_git.bb</filename>) located in
7125 <filename>meta/recipes-connectivity</filename> in the
7126 Source Directory defines <filename>PV</filename> as
7127 follows:
7128 <literallayout class='monospaced'>
7129 PV = "0.12-git${SRCPV}"
7130 </literallayout>
7131 </para>
7132 </glossdef>
7133 </glossentry>
7134
7135 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
7136 <glossdef>
7137 <para>
7138 The revision of the source code used to build the package.
7139 This variable applies to Subversion, Git, Mercurial and Bazaar
7140 only.
7141 Note that if you wish to build a fixed revision and you wish
7142 to avoid performing a query on the remote repository every time
7143 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
7144 full revision identifier and not just a tag.
7145 </para>
7146 </glossdef>
7147 </glossentry>
7148
7149 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
7150 <glossdef>
7151 <para>The directory for the shared state cache.</para>
7152 </glossdef>
7153 </glossentry>
7154
7155 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
7156 <glossdef>
7157 <para>
7158 Configures the OpenEmbedded build system to search other
7159 mirror locations for prebuilt cache data objects before
7160 building out the data.
7161 This variable works like fetcher
7162 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
7163 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
7164 and points to the cache locations to check for the shared
7165 objects.
7166 </para>
7167
7168 <para>
7169 You can specify a filesystem directory or a remote URL such
7170 as HTTP or FTP.
7171 The locations you specify need to contain the shared state
7172 cache (sstate-cache) results from previous builds.
7173 The sstate-cache you point to can also be from builds on
7174 other machines.
7175 </para>
7176
7177 <para>
7178 If a mirror uses the same structure as
7179 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
7180 you need to add
7181 "PATH" at the end as shown in the examples below.
7182 The build system substitutes the correct path within the
7183 directory structure.
7184 <literallayout class='monospaced'>
7185 SSTATE_MIRRORS ?= "\
7186 file://.* http://someserver.tld/share/sstate/PATH \n \
7187 file://.* file:///some/local/dir/sstate/PATH"
7188 </literallayout>
7189 </para>
7190 </glossdef>
7191 </glossentry>
7192
7193 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
7194 <glossdef>
7195 <para>
7196 The directory with kernel headers that are required to build out-of-tree
7197 modules.
7198 </para>
7199 </glossdef>
7200 </glossentry>
7201
7202 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
7203 <glossdef>
7204 <para>
7205 Specifies the base path used to create recipe stamp files.
7206 The path to an actual stamp file is constructed by evaluating this
7207 string and then appending additional information.
7208 Currently, the default assignment for <filename>STAMP</filename>
7209 as set in the <filename>meta/conf/bitbake.conf</filename> file
7210 is:
7211 <literallayout class='monospaced'>
7212 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
7213 </literallayout>
7214 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
7215 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
7216 <link linkend='var-PN'><filename>PN</filename></link>,
7217 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
7218 <link linkend='var-PV'><filename>PV</filename></link>, and
7219 <link linkend='var-PR'><filename>PR</filename></link> for related variable
7220 information.
7221 </para>
7222 </glossdef>
7223 </glossentry>
7224
7225 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
7226 <glossdef>
7227 <para>
7228 Specifies the base directory in which the OpenEmbedded
7229 build system places stamps.
7230 The default directory is
7231 <filename>${TMPDIR}/stamps</filename>.
7232 </para>
7233 </glossdef>
7234 </glossentry>
7235
7236 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
7237 <glossdef>
7238 <para>The short (72 characters or less) summary of the binary package for packaging
7239 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
7240 <filename>dpkg</filename>.
7241 By default, <filename>SUMMARY</filename> is used to define
7242 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
7243 variable if <filename>DESCRIPTION</filename> is not set
7244 in the recipe.
7245 </para>
7246 </glossdef>
7247 </glossentry>
7248
7249 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
7250 <glossdef>
7251 <para>
7252 Specifies the kernel boot default console.
7253 If you want to use a console other than the default,
7254 set this variable in your recipe as follows where "X" is
7255 the console number you want to use:
7256 <literallayout class='monospaced'>
7257 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
7258 </literallayout>
7259 </para>
7260
7261 <para>
7262 The
7263 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7264 class initially sets this variable to null but then checks
7265 for a value later.
7266 </para>
7267 </glossdef>
7268 </glossentry>
7269
7270 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
7271 <glossdef>
7272 <para>
7273 Lists additional options to add to the syslinux file.
7274 You need to set this variable in your recipe.
7275 If you want to list multiple options, separate the options
7276 with a semicolon character (<filename>;</filename>).
7277 </para>
7278
7279 <para>
7280 The
7281 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7282 class uses this variable to create a set of options.
7283 </para>
7284 </glossdef>
7285 </glossentry>
7286
7287 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
7288 <glossdef>
7289 <para>
7290 Specifies the alternate serial port or turns it off.
7291 To turn off serial, set this variable to an empty string
7292 in your recipe.
7293 The variable's default value is set in the
7294 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7295 as follows:
7296 <literallayout class='monospaced'>
7297 SYSLINUX_SERIAL ?= "0 115200"
7298 </literallayout>
7299 The class checks for and uses the variable as needed. </para>
7300 </glossdef>
7301 </glossentry>
7302
7303 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
7304 <glossdef>
7305 <para>
7306 An <filename>.LSS</filename> file used as the background
7307 for the VGA boot menu when you are using the boot menu.
7308 You need to set this variable in your recipe.
7309 </para>
7310
7311 <para>
7312 The
7313 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7314 class checks for this variable and if found, the
7315 OpenEmbedded build system installs the splash screen.
7316 </para>
7317 </glossdef>
7318 </glossentry>
7319
7320 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
7321 <glossdef>
7322 <para>
7323 Specifies the alternate console=tty... kernel boot argument.
7324 The variable's default value is set in the
7325 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7326 as follows:
7327 <literallayout class='monospaced'>
7328 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
7329 </literallayout>
7330 The class checks for and uses the variable as needed.
7331 </para>
7332 </glossdef>
7333 </glossentry>
7334
7335 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
7336 <glossdef>
7337 <para>
7338 A list of functions to execute after files are staged into
7339 the sysroot.
7340 These functions are usually used to apply additional
7341 processing on the staged files, or to stage additional
7342 files.
7343 </para>
7344 </glossdef>
7345 </glossentry>
7346
7347 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
7348 <glossdef>
7349 <para>
7350 For recipes that inherit the
7351 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7352 class, this variable specifies whether the service you have
7353 specified in
7354 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
7355 should be started automatically or not.
7356 By default, the service is enabled to automatically start
7357 at boot time.
7358 The default setting is in the
7359 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7360 class as follows:
7361 <literallayout class='monospaced'>
7362 SYSTEMD_AUTO_ENABLE ??= "enable"
7363 </literallayout>
7364 You can disable the service by setting the variable to
7365 "disable".
7366 </para>
7367 </glossdef>
7368 </glossentry>
7369
7370 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
7371 <glossdef>
7372 <para>
7373 For recipes that inherit the
7374 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7375 class, this variable locates the systemd unit files when
7376 they are not found in the main recipe's package.
7377 By default, the
7378 <filename>SYSTEMD_PACKAGES</filename> variable is set
7379 such that the systemd unit files are assumed to reside in
7380 the recipes main package:
7381 <literallayout class='monospaced'>
7382 SYSTEMD_PACKAGES ?= "${PN}"
7383 </literallayout>
7384 If these unit files are not in this recipe's main
7385 package, you need to use
7386 <filename>SYSTEMD_PACKAGES</filename> to list the package
7387 or packages in which the build system can find the systemd
7388 unit files.
7389 </para>
7390 </glossdef>
7391 </glossentry>
7392
7393 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
7394 <glossdef>
7395 <para>
7396 For recipes that inherit the
7397 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7398 class, this variable specifies the systemd service name for
7399 a package.
7400 </para>
7401
7402 <para>
7403 When you specify this file in your recipe, use a package
7404 name override to indicate the package to which the value
7405 applies.
7406 Here is an example from the connman recipe:
7407 <literallayout class='monospaced'>
7408 SYSTEMD_SERVICE_${PN} = "connman.service"
7409 </literallayout>
7410 </para>
7411 </glossdef>
7412 </glossentry>
7413
7414 </glossdiv>
7415
7416 <glossdiv id='var-glossary-t'><title>T</title>
7417
7418 <glossentry id='var-T'><glossterm>T</glossterm>
7419 <glossdef>
7420 <para>This variable points to a directory were BitBake places
7421 temporary files, which consist mostly of task logs and
7422 scripts, when building a particular recipe.
7423 The variable is typically set as follows:
7424 <literallayout class='monospaced'>
7425 T = "${WORKDIR}/temp"
7426 </literallayout>
7427 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
7428 is the directory into which BitBake unpacks and builds the
7429 recipe.
7430 The default <filename>bitbake.conf</filename> file sets this variable.</para>
7431 <para>The <filename>T</filename> variable is not to be confused with
7432 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
7433 which points to the root of the directory tree where BitBake
7434 places the output of an entire build.
7435 </para>
7436 </glossdef>
7437 </glossentry>
7438
7439 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
7440 <glossdef>
7441 <para>
7442 The target machine's architecture.
7443 The OpenEmbedded build system supports many
7444 architectures.
7445 Here is an example list of architectures supported.
7446 This list is by no means complete as the architecture
7447 is configurable:
7448 <literallayout class='monospaced'>
7449 arm
7450 i586
7451 x86_64
7452 powerpc
7453 powerpc64
7454 mips
7455 mipsel
7456 </literallayout>
7457 </para>
7458 </glossdef>
7459 </glossentry>
7460
7461 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
7462 <glossdef>
7463 <para>
7464 Flags passed to the C compiler for the target system.
7465 This variable evaluates to the same as
7466 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
7467 </para>
7468 </glossdef>
7469 </glossentry>
7470
7471
7472 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
7473 <glossdef>
7474 <para>Specifies the method for handling FPU code.
7475 For FPU-less targets, which include most ARM CPUs, the variable must be
7476 set to "soft".
7477 If not, the kernel emulation gets used, which results in a performance penalty.</para>
7478 </glossdef>
7479 </glossentry>
7480
7481 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
7482 <glossdef>
7483 <para>Specifies the target's operating system.
7484 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
7485 to "linux-uclibc" for <filename>uclibc</filename>.
7486 For ARM/EABI targets, there are also "linux-gnueabi" and
7487 "linux-uclibc-gnueabi" values possible.</para>
7488 </glossdef>
7489 </glossentry>
7490
7491 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
7492 <glossdef>
7493 <para>
7494 Specifies the GNU standard C library (<filename>libc</filename>)
7495 variant to use during the build process.
7496 This variable replaces <filename>POKYLIBC</filename>, which is no longer
7497 supported.
7498 </para>
7499 <para>
7500 You can select "eglibc" or "uclibc".
7501 <note>
7502 This release of the Yocto Project does not support the
7503 <filename>glibc</filename> implementation of <filename>libc</filename>.
7504 </note>
7505 </para>
7506 </glossdef>
7507 </glossentry>
7508
7509 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
7510 <glossdef>
7511 <para>
7512 Specifies the toolchain selector.
7513 <filename>TCMODE</filename> controls the characteristics
7514 of the generated packages and images by telling the
7515 OpenEmbedded build system which toolchain profile to use.
7516 By default, the OpenEmbedded build system builds its own
7517 internal toolchain.
7518 The variable's default value is "default", which uses
7519 that internal toolchain.
7520 <note>
7521 If <filename>TCMODE</filename> is set to a value
7522 other than "default", then it is your responsibility
7523 to ensure that the toolchain is compatible with the
7524 default toolchain.
7525 Using older or newer versions of these components
7526 might cause build problems.
7527 See the
7528 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
7529 for the specific components with which the toolchain
7530 must be compatible.
7531 </note>
7532 </para>
7533
7534 <para>
7535 With additional layers, it is possible to use a pre-compiled
7536 external toolchain.
7537 One example is the Sourcery G++ Toolchain.
7538 The support for this toolchain resides in the separate
7539 <filename>meta-sourcery</filename> layer at
7540 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
7541 You can use <filename>meta-sourcery</filename> as a
7542 template for adding support for other external toolchains.
7543 </para>
7544
7545 <para>
7546 The <filename>TCMODE</filename> variable points the build
7547 system to a file in
7548 <filename>conf/distro/include/tcmode-${TCMODE}.inc</filename>.
7549 Thus, for <filename>meta-sourcery</filename>,
7550 which has <filename>conf/distro/include/tcmode-external-sourcery.inc</filename>,
7551 you would set the variable as follows:
7552 <literallayout class='monospaced'>
7553 TCMODE ?= "external-sourcery"
7554 </literallayout>
7555 </para>
7556
7557 <para>
7558 The variable is similar to
7559 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
7560 which controls the variant of the GNU standard C library
7561 (<filename>libc</filename>) used during the build process:
7562 <filename>eglibc</filename> or <filename>uclibc</filename>.
7563 </para>
7564 </glossdef>
7565 </glossentry>
7566
7567 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
7568 <glossdef>
7569 <para>
7570 The location the OpenEmbedded build system uses to export
7571 tests when the
7572 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
7573 variable is set to "1".
7574 </para>
7575
7576 <para>
7577 The <filename>TEST_EXPORT_DIR</filename> variable defaults
7578 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
7579 </para>
7580 </glossdef>
7581 </glossentry>
7582
7583 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
7584 <glossdef>
7585 <para>
7586 Specifies to export the tests only.
7587 Set this variable to "1" if you do not want to run the
7588 tests but you want them to be exported in a manner that
7589 you to run them outside of the build system.
7590 </para>
7591 </glossdef>
7592 </glossentry>
7593
7594 <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
7595 <glossdef>
7596 <para>
7597 Automatically runs the series of automated tests for
7598 images when an image is successfully built.
7599 </para>
7600
7601 <para>
7602 These tests are written in Python making use of the
7603 <filename>unittest</filename> module, and the majority of
7604 them run commands on the target system over
7605 <filename>ssh</filename>.
7606 You can set this variable to "1" in your
7607 <filename>local.conf</filename> file in the
7608 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
7609 to have the OpenEmbedded build system automatically run
7610 these tests after an image successfully builds:
7611 <literallayout class='monospaced'>
7612 TEST_IMAGE = "1"
7613 </literallayout>
7614 For more information on enabling, running, and writing
7615 these tests, see the
7616 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7617 section in the Yocto Project Development Manual and the
7618 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
7619 section.
7620 </para>
7621 </glossdef>
7622 </glossentry>
7623
7624 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
7625 <glossdef>
7626 <para>
7627 Holds the SSH log and the boot log for QEMU machines.
7628 The <filename>TEST_LOG_DIR</filename> variable defaults
7629 to <filename>"${WORKDIR}/testimage"</filename>.
7630 <note>
7631 Actual test results reside in the task log
7632 (<filename>log.do_testimage</filename>), which is in
7633 the <filename>${WORKDIR}/temp/</filename> directory.
7634 </note>
7635 </para>
7636 </glossdef>
7637 </glossentry>
7638
7639 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
7640 <glossdef>
7641 <para>
7642 The time in seconds allowed for an image to boot before
7643 automated runtime tests begin to run against an
7644 image.
7645 The default timeout period to allow the boot process to
7646 reach the login prompt is 500 seconds.
7647 You can specify a different value in the
7648 <filename>local.conf</filename> file.
7649 </para>
7650
7651 <para>
7652 For more information on testing images, see the
7653 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7654 section in the Yocto Project Development Manual.
7655 </para>
7656 </glossdef>
7657 </glossentry>
7658
7659 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
7660 <glossdef>
7661 <para>
7662 The IP address of the build machine (host machine).
7663 This IP address is usually automatically detected.
7664 However, if detection fails, this variable needs to be set
7665 to the IP address of the build machine (i.e. where
7666 the build is taking place).
7667 <note>
7668 The <filename>TEST_SERVER_IP</filename> variable
7669 is only used for a small number of tests such as
7670 the "smart" test suite, which needs to download
7671 packages from <filename>DEPLOY_DIR/rpm</filename>.
7672 </note>
7673 </para>
7674 </glossdef>
7675 </glossentry>
7676
7677 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
7678 <glossdef>
7679 <para>
7680 Specifies the target controller to use when running tests
7681 against a test image.
7682 The default controller to use is "qemu":
7683 <literallayout class='monospaced'>
7684 TEST_TARGET = "qemu"
7685 </literallayout>
7686 A target controller is a class that defines how an
7687 image gets deployed on a target and how a target is started.
7688 A layer can extend the controllers by adding a module
7689 in the layer's <filename>/lib/oeqa/controllers</filename>
7690 directory and by inheriting the
7691 <filename>BaseTarget</filename> class, which is an abstract
7692 class that cannot be used as a value of
7693 <filename>TEST_TARGET</filename>.
7694 </para>
7695
7696 <para>
7697 You can provide the following arguments with
7698 <filename>TEST_TARGET</filename>:
7699 <itemizedlist>
7700 <listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>
7701 Boots a QEMU image and runs the tests.
7702 See the
7703 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
7704 section in the Yocto Project Development Manual for
7705 more information.
7706 </para></listitem>
7707 <listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>
7708 Runs the tests on target hardware that is already
7709 up and running.
7710 The hardware can be on the network or it can be
7711 a device running an image on QEMU.
7712 You must also set
7713 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
7714 when you use "simpleremote" or "SimpleRemoteTarget".
7715 <note>
7716 This argument is defined in
7717 <filename>meta/lib/oeqa/targetcontrol.py</filename>.
7718 The small caps names are kept for compatibility
7719 reasons.
7720 </note>
7721 </para></listitem>
7722 <listitem><para><emphasis>"GummibootTarget":</emphasis>
7723 Automatically deploys and runs tests on an
7724 EFI-enabled machine that has a master image
7725 installed.
7726 <note>
7727 This argument is defined in
7728 <filename>meta/lib/oeqa/controllers/masterimage.py</filename>.
7729 </note>
7730 </para></listitem>
7731 </itemizedlist>
7732 </para>
7733
7734 <para>
7735 For information on running tests on hardware, see the
7736 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
7737 section in the Yocto Project Development Manual.
7738 </para>
7739 </glossdef>
7740 </glossentry>
7741
7742 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
7743 <glossdef>
7744 <para>
7745 The IP address of your hardware under test.
7746 The <filename>TEST_TARGET_IP</filename> variable has no
7747 effect when
7748 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
7749 is set to "qemu".
7750 </para>
7751
7752 <para>
7753 When you specify the IP address, you can also include a
7754 port.
7755 Here is an example:
7756 <literallayout class='monospaced'>
7757 TEST_TARGET_IP = "192.168.1.4:2201"
7758 </literallayout>
7759 Specifying a port is useful when SSH is started on a
7760 non-standard port or in cases when your hardware under test
7761 is behind a firewall or network that is not directly
7762 accessible from your host and you need to do port address
7763 translation.
7764 </para>
7765 </glossdef>
7766 </glossentry>
7767
7768 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
7769 <glossdef>
7770 <para>
7771 An ordered list of tests (modules) to run against
7772 an image when performing automated runtime testing.
7773 </para>
7774
7775 <para>
7776 The OpenEmbedded build system provides a core set of tests
7777 that can be used against images.
7778 <note>
7779 Currently, there is only support for running these tests
7780 under QEMU.
7781 </note>
7782 Tests include <filename>ping</filename>,
7783 <filename>ssh</filename>, <filename>df</filename> among
7784 others.
7785 You can add your own tests to the list of tests by
7786 appending <filename>TEST_SUITES</filename> as follows:
7787 <literallayout class='monospaced'>
7788 TEST_SUITES_append = " mytest"
7789 </literallayout>
7790 Alternatively, you can provide the "auto" option to
7791 have all applicable tests run against the image.
7792 <literallayout class='monospaced'>
7793 TEST_SUITES_append = " auto"
7794 </literallayout>
7795 Using this option causes the build system to automatically
7796 run tests that are applicable to the image.
7797 Tests that are not applicable are skipped.
7798 </para>
7799
7800 <para>
7801 The order in which tests are run is important.
7802 Tests that depend on another test must appear later in the
7803 list than the test on which they depend.
7804 For example, if you append the list of tests with two
7805 tests (<filename>test_A</filename> and
7806 <filename>test_B</filename>) where
7807 <filename>test_B</filename> is dependent on
7808 <filename>test_A</filename>, then you must order the tests
7809 as follows:
7810 <literallayout class='monospaced'>
7811 TEST_SUITES = " test_A test_B"
7812 </literallayout>
7813 </para>
7814
7815 <para>
7816 For more information on testing images, see the
7817 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7818 section in the Yocto Project Development Manual.
7819 </para>
7820 </glossdef>
7821 </glossentry>
7822
7823 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
7824 <glossdef>
7825 <para>
7826 The directory in which the file BitBake is currently
7827 parsing is located.
7828 Do not manually set this variable.
7829 </para>
7830 </glossdef>
7831 </glossentry>
7832
7833 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
7834 <glossdef>
7835 <para>
7836 This variable is the base directory the OpenEmbedded
7837 build system uses for all build output and intermediate
7838 files (other than the shared state cache).
7839 By default, the <filename>TMPDIR</filename> variable points
7840 to <filename>tmp</filename> within the
7841 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
7842 </para>
7843
7844 <para>
7845 If you want to establish this directory in a location other
7846 than the default, you can uncomment and edit the following
7847 statement in the
7848 <filename>conf/local.conf</filename> file in the
7849 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
7850 <literallayout class='monospaced'>
7851 #TMPDIR = "${TOPDIR}/tmp"
7852 </literallayout>
7853 An example use for this scenario is to set
7854 <filename>TMPDIR</filename> to a local disk, which does
7855 not use NFS, while having the Build Directory use NFS.
7856 </para>
7857
7858 <para>
7859 The filesystem used by <filename>TMPDIR</filename> must
7860 have standard filesystem semantics (i.e. mixed-case files
7861 are unique, POSIX file locking, and persistent inodes).
7862 Due to various issues with NFS and bugs in some
7863 implementations, NFS does not meet this minimum
7864 requirement.
7865 Consequently, <filename>TMPDIR</filename> cannot be on
7866 NFS.
7867 </para>
7868 </glossdef>
7869 </glossentry>
7870
7871 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
7872 <glossdef>
7873 <para>
7874 This variable lists packages the OpenEmbedded build system
7875 uses when building an SDK, which contains a
7876 cross-development environment.
7877 The packages specified by this variable are part of the
7878 toolchain set that runs on the
7879 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
7880 and each package should usually have the prefix
7881 "nativesdk-".
7882 When building an SDK using
7883 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
7884 a default list of packages is set in this variable, but
7885 you can add additional packages to the list.
7886 </para>
7887
7888 <para>
7889 For background information on cross-development toolchains
7890 in the Yocto Project development environment, see the
7891 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
7892 section.
7893 For information on setting up a cross-development
7894 environment, see the
7895 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
7896 section in the Yocto Project Application Developer's Guide.
7897 </para>
7898 </glossdef>
7899 </glossentry>
7900
7901 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
7902 <glossdef>
7903 <para>
7904 This variable lists packages the OpenEmbedded build system
7905 uses when it creates the target part of an SDK
7906 (i.e. the part built for the target hardware), which
7907 includes libraries and headers.
7908 </para>
7909
7910 <para>
7911 For background information on cross-development toolchains
7912 in the Yocto Project development environment, see the
7913 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
7914 section.
7915 For information on setting up a cross-development
7916 environment, see the
7917 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
7918 section in the Yocto Project Application Developer's Guide.
7919 </para>
7920 </glossdef>
7921 </glossentry>
7922
7923 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
7924 <glossdef>
7925 <para>
7926 The top-level
7927 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
7928 BitBake automatically sets this variable when you
7929 initialize your build environment using either
7930 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
7931 or
7932 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
7933 </para>
7934 </glossdef>
7935 </glossentry>
7936
7937 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
7938 <glossdef>
7939 <para>
7940 A sanitized version of
7941 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
7942 This variable is used where the architecture is needed in
7943 a value where underscores are not allowed, for example
7944 within package filenames.
7945 In this case, dash characters replace any underscore
7946 characters used in TARGET_ARCH.
7947 </para>
7948
7949 <para>
7950 Do not edit this variable.
7951 </para>
7952 </glossdef>
7953 </glossentry>
7954
7955 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
7956 <glossdef>
7957 <para>
7958 The package architecture understood by the packaging
7959 system to define the architecture, ABI, and tuning of
7960 output packages.
7961 </para>
7962 </glossdef>
7963 </glossentry>
7964
7965 </glossdiv>
7966
7967 <glossdiv id='var-glossary-u'><title>U</title>
7968
7969 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
7970 <glossdef>
7971 <para>
7972 Configures the
7973 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
7974 and can also define
7975 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
7976 for individual cases.
7977 </para>
7978
7979 <para>
7980 Following is an example from the
7981 <filename>meta-fsl-arm</filename> layer.
7982 <literallayout class='monospaced'>
7983 UBOOT_CONFIG ??= "sd"
7984 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
7985 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
7986 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
7987 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
7988 </literallayout>
7989 In this example, "sd" is selected as the configuration
7990 of the possible four for the
7991 <filename>UBOOT_MACHINE</filename>.
7992 The "sd" configuration defines "mx6qsabreauto_config"
7993 as the value for <filename>UBOOT_MACHINE</filename>, while
7994 the "sdcard" specifies the
7995 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
7996 image.
7997 </para>
7998
7999 <para>
8000 For more information on how the
8001 <filename>UBOOT_CONFIG</filename> is handled, see the
8002 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
8003 class.
8004 </para>
8005 </glossdef>
8006 </glossentry>
8007
8008 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
8009 <glossdef>
8010 <para>
8011 Specifies the entry point for the U-Boot image.
8012 During U-Boot image creation, the
8013 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
8014 as a command-line parameter to the
8015 <filename>uboot-mkimage</filename> utility.
8016 </para>
8017 </glossdef>
8018 </glossentry>
8019
8020 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
8021 <glossdef>
8022 <para>
8023 Specifies the load address for the U-Boot image.
8024 During U-Boot image creation, the
8025 <filename>UBOOT_LOADADDRESS</filename> variable is passed
8026 as a command-line parameter to the
8027 <filename>uboot-mkimage</filename> utility.
8028 </para>
8029 </glossdef>
8030 </glossentry>
8031
8032 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
8033 <glossdef>
8034 <para>
8035 Appends a string to the name of the local version of the
8036 U-Boot image.
8037 For example, assuming the version of the U-Boot image
8038 built was "2013.10, the full version string reported by
8039 U-Boot would be "2013.10-yocto" given the following
8040 statement:
8041 <literallayout class='monospaced'>
8042 UBOOT_LOCALVERSION = "-yocto"
8043 </literallayout>
8044 </para>
8045 </glossdef>
8046 </glossentry>
8047
8048 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
8049 <glossdef>
8050 <para>
8051 Specifies the value passed on the
8052 <filename>make</filename> command line when building
8053 a U-Boot image.
8054 The value indicates the target platform configuration.
8055 You typically set this variable from the machine
8056 configuration file (i.e.
8057 <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
8058 </para>
8059 </glossdef>
8060 </glossentry>
8061
8062 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
8063 <glossdef>
8064 <para>
8065 Specifies the target called in the
8066 <filename>Makefile</filename>.
8067 The default target is "all".
8068 </para>
8069 </glossdef>
8070 </glossentry>
8071
8072 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
8073 <glossdef>
8074 <para>
8075 Points to the generated U-Boot extension.
8076 For example, <filename>u-boot.sb</filename> has a
8077 <filename>.sb</filename> extension.
8078 </para>
8079
8080 <para>
8081 The default U-Boot extension is
8082 <filename>.bin</filename>
8083 </para>
8084 </glossdef>
8085 </glossentry>
8086
8087 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
8088 <glossdef>
8089 <para>
8090 Specifies the target used for building U-Boot.
8091 The target is passed directly as part of the "make" command
8092 (e.g. SPL and AIS).
8093 If you do not specifically set this variable, the
8094 OpenEmbedded build process passes and uses "all" for the
8095 target during the U-Boot building process.
8096 </para>
8097 </glossdef>
8098 </glossentry>
8099
8100 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
8101 <glossdef>
8102 <para>
8103 A list of classes to globally inherit.
8104 These classes are used by the OpenEmbedded build system
8105 to enable extra features (e.g.
8106 <filename>buildstats</filename>,
8107 <filename>image-mklibs</filename>, and so forth).
8108 </para>
8109
8110 <para>
8111 The default list is set in your
8112 <filename>local.conf</filename> file:
8113 <literallayout class='monospaced'>
8114 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
8115 </literallayout>
8116 For more information, see
8117 <filename>meta-yocto/conf/local.conf.sample</filename> in
8118 the
8119 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
8120 </para>
8121 </glossdef>
8122 </glossentry>
8123
8124 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
8125 <glossdef>
8126 <para>
8127 Forces the OpenEmbedded build system to produce an error
8128 if the user identification (<filename>uid</filename>) and
8129 group identification (<filename>gid</filename>) values
8130 are not defined in <filename>files/passwd</filename>
8131 and <filename>files/group</filename> files.
8132 </para>
8133
8134 <para>
8135 The default behavior for the build system is to dynamically
8136 apply <filename>uid</filename> and
8137 <filename>gid</filename> values.
8138 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
8139 variable is by default not set.
8140 If you plan on using statically assigned
8141 <filename>gid</filename> and <filename>uid</filename>
8142 values, you should set
8143 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
8144 your <filename>local.conf</filename> file as
8145 follows:
8146 <literallayout class='monospaced'>
8147 USERADD_ERROR_DYNAMIC = "1"
8148 </literallayout>
8149 Overriding the default behavior implies you are going to
8150 also take steps to set static <filename>uid</filename> and
8151 <filename>gid</filename> values through use of the
8152 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
8153 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
8154 and
8155 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
8156 variables.
8157 </para>
8158 </glossdef>
8159 </glossentry>
8160
8161 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
8162 <glossdef>
8163 <para>
8164 Specifies a password file to use for obtaining static
8165 group identification (<filename>gid</filename>) values
8166 when the OpenEmbedded build system adds a group to the
8167 system during package installation.
8168 </para>
8169
8170 <para>
8171 When applying static group identification
8172 (<filename>gid</filename>) values, the OpenEmbedded build
8173 system looks in
8174 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
8175 for a <filename>files/group</filename> file and then applies
8176 those <filename>uid</filename> values.
8177 Set the variable as follows in your
8178 <filename>local.conf</filename> file:
8179 <literallayout class='monospaced'>
8180 USERADD_GID_TABLES = "files/group"
8181 </literallayout>
8182 </para>
8183
8184 <note>
8185 Setting the
8186 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
8187 variable to "useradd-staticids" causes the build system
8188 to use static <filename>gid</filename> values.
8189 </note>
8190 </glossdef>
8191 </glossentry>
8192
8193 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
8194 <glossdef>
8195 <para>
8196 Specifies a password file to use for obtaining static
8197 user identification (<filename>uid</filename>) values
8198 when the OpenEmbedded build system adds a user to the
8199 system during package installation.
8200 </para>
8201
8202 <para>
8203 When applying static user identification
8204 (<filename>uid</filename>) values, the OpenEmbedded build
8205 system looks in
8206 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
8207 for a <filename>files/passwd</filename> file and then applies
8208 those <filename>uid</filename> values.
8209 Set the variable as follows in your
8210 <filename>local.conf</filename> file:
8211 <literallayout class='monospaced'>
8212 USERADD_UID_TABLES = "files/passwd"
8213 </literallayout>
8214 </para>
8215
8216 <note>
8217 Setting the
8218 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
8219 variable to "useradd-staticids" causes the build system
8220 to use static <filename>uid</filename> values.
8221 </note>
8222 </glossdef>
8223 </glossentry>
8224
8225 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
8226 <glossdef>
8227 <para>
8228 When a recipe inherits the
8229 <filename>useradd</filename> class, this variable
8230 specifies the individual packages within the recipe that
8231 require users and/or groups to be added.
8232 </para>
8233
8234 <para>
8235 You must set this variable if the recipe inherits the
8236 class.
8237 For example, the following enables adding a user for the
8238 main package in a recipe:
8239 <literallayout class='monospaced'>
8240 USERADD_PACKAGES = "${PN}"
8241 </literallayout>
8242 <note>
8243 If follows that if you are going to use the
8244 <filename>USERADD_PACKAGES</filename> variable,
8245 you need to set one or more of the
8246 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
8247 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
8248 or
8249 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
8250 variables.
8251 </note>
8252 </para>
8253
8254 </glossdef>
8255 </glossentry>
8256
8257 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
8258 <glossdef>
8259 <para>
8260 When a recipe inherits the
8261 <filename>useradd</filename> class, this variable
8262 specifies for a package what parameters should be passed
8263 to the <filename>useradd</filename> command
8264 if you wish to add a user to the system when the package
8265 is installed.
8266 </para>
8267
8268 <para>
8269 Here is an example from the <filename>dbus</filename>
8270 recipe:
8271 <literallayout class='monospaced'>
8272 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
8273 --no-create-home --shell /bin/false \
8274 --user-group messagebus"
8275 </literallayout>
8276 For information on the standard Linux shell command
8277 <filename>useradd</filename>, see
8278 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
8279 </para>
8280 </glossdef>
8281 </glossentry>
8282
8283 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
8284 <glossdef>
8285 <para>
8286 When set to "useradd-staticids", causes the
8287 OpenEmbedded build system to base all user and group
8288 additions on a static
8289 <filename>passwd</filename> and
8290 <filename>group</filename> files found in
8291 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
8292 </para>
8293
8294 <para>
8295 To use static user identification (<filename>uid</filename>)
8296 and group identification (<filename>gid</filename>)
8297 values, set the variable
8298 as follows in your <filename>local.conf</filename> file:
8299 <literallayout class='monospaced'>
8300 USERADDEXTENSION = "useradd-staticids"
8301 </literallayout>
8302 <note>
8303 Setting this variable to use static
8304 <filename>uid</filename> and <filename>gid</filename>
8305 values causes the OpenEmbedded build system to employ
8306 the
8307 <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link>
8308 class.
8309 </note>
8310 </para>
8311
8312 <para>
8313 If you use static <filename>uid</filename> and
8314 <filename>gid</filename> information, you must also
8315 specify the <filename>files/passwd</filename> and
8316 <filename>files/group</filename> files by setting the
8317 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
8318 and
8319 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
8320 variables.
8321 Additionally, you should also set the
8322 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
8323 variable.
8324 </para>
8325 </glossdef>
8326 </glossentry>
8327
8328 </glossdiv>
8329
8330<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
8331<!-- </glossdiv>-->
8332
8333 <glossdiv id='var-glossary-w'><title>W</title>
8334
8335 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
8336 <glossdef>
8337 <para>
8338 Specifies the quality assurance checks whose failures are
8339 reported as warnings by the OpenEmbedded build system.
8340 You set this variable in your distribution configuration
8341 file.
8342 For a list of the checks you can control with this variable,
8343 see the
8344 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
8345 section.
8346 </para>
8347 </glossdef>
8348 </glossentry>
8349
8350 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
8351 <glossdef>
8352 <para>
8353 The pathname of the work directory in which the OpenEmbedded
8354 build system builds a recipe.
8355 This directory is located within the
8356 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
8357 directory structure and is specific to the recipe being
8358 built and the system for which it is being built.
8359 </para>
8360
8361 <para>
8362 The <filename>WORKDIR</filename> directory is defined as
8363 follows:
8364 <literallayout class='monospaced'>
8365 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
8366 </literallayout>
8367 The actual directory depends on several things:
8368 <itemizedlist>
8369 <listitem><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>:
8370 The top-level build output directory</listitem>
8371 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
8372 The target system identifier</listitem>
8373 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
8374 The recipe name</listitem>
8375 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
8376 The epoch - (if
8377 <link linkend='var-PE'><filename>PE</filename></link>
8378 is not specified, which is usually the case for most
8379 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
8380 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
8381 The recipe version</listitem>
8382 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
8383 The recipe revision</listitem>
8384 </itemizedlist>
8385 </para>
8386
8387 <para>
8388 As an example, assume a Source Directory top-level folder
8389 name <filename>poky</filename>, a default Build Directory at
8390 <filename>poky/build</filename>, and a
8391 <filename>qemux86-poky-linux</filename> machine target
8392 system.
8393 Furthermore, suppose your recipe is named
8394 <filename>foo_1.3.0-r0.bb</filename>.
8395 In this case, the work directory the build system uses to
8396 build the package would be as follows:
8397 <literallayout class='monospaced'>
8398 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
8399 </literallayout>
8400 </para>
8401 </glossdef>
8402 </glossentry>
8403
8404 </glossdiv>
8405
8406<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
8407<!-- </glossdiv>-->
8408
8409<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
8410<!-- </glossdiv>-->
8411
8412<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
8413<!-- </glossdiv>-->
8414
8415</glossary>
8416</chapter>
8417<!--
8418vim: expandtab tw=80 ts=4
8419-->
diff --git a/documentation/ref-manual/ref-varlocality.xml b/documentation/ref-manual/ref-varlocality.xml
new file mode 100644
index 0000000..d3f8732
--- /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 0000000..c48951f
--- /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 0000000..d34be75
--- /dev/null
+++ b/documentation/ref-manual/technical-details.xml
@@ -0,0 +1,1409 @@
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
10 Yocto Project.
11 Currently, topics include Yocto Project components,
12 cross-toolchain generation, shared state (sstate) cache,
13 x32, Wayland support, and Licenses.
14 </para>
15
16<section id='usingpoky-components'>
17 <title>Yocto Project Components</title>
18
19 <para>
20 The
21 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
22 task executor together with various types of configuration files form
23 the OpenEmbedded Core.
24 This section overviews these components by describing their use and
25 how they interact.
26 </para>
27
28 <para>
29 BitBake handles the parsing and execution of the data files.
30 The data itself is of various types:
31 <itemizedlist>
32 <listitem><para><emphasis>Recipes:</emphasis> Provides details
33 about particular pieces of software.
34 </para></listitem>
35 <listitem><para><emphasis>Class Data:</emphasis> Abstracts
36 common build information (e.g. how to build a Linux kernel).
37 </para></listitem>
38 <listitem><para><emphasis>Configuration Data:</emphasis> Defines
39 machine-specific settings, policy decisions, and so forth.
40 Configuration data acts as the glue to bind everything
41 together.
42 </para></listitem>
43 </itemizedlist>
44 </para>
45
46 <para>
47 BitBake knows how to combine multiple data sources together and refers
48 to each data source as a layer.
49 For information on layers, see the
50 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
51 Creating Layers</ulink>" section of the Yocto Project Development Manual.
52 </para>
53
54 <para>
55 Following are some brief details on these core components.
56 For additional information on how these components interact during
57 a build, see the
58 "<link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>"
59 Chapter.
60 </para>
61
62 <section id='usingpoky-components-bitbake'>
63 <title>BitBake</title>
64
65 <para>
66 BitBake is the tool at the heart of the OpenEmbedded build system
67 and is responsible for parsing the
68 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
69 generating a list of tasks from it, and then executing those tasks.
70 </para>
71
72 <para>
73 This section briefly introduces BitBake.
74 If you want more information on BitBake, see the
75 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
76 </para>
77
78 <para>
79 To see a list of the options BitBake supports, use either of
80 the following commands:
81 <literallayout class='monospaced'>
82 $ bitbake -h
83 $ bitbake --help
84 </literallayout>
85 </para>
86
87 <para>
88 The most common usage for BitBake is <filename>bitbake &lt;packagename&gt;</filename>, where
89 <filename>packagename</filename> is the name of the package you want to build
90 (referred to as the "target" in this manual).
91 The target often equates to the first part of a recipe's filename
92 (e.g. "foo" for a recipe named
93 <filename>foo_1.3.0-r0.bb</filename>).
94 So, to process the <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you
95 might type the following:
96 <literallayout class='monospaced'>
97 $ bitbake matchbox-desktop
98 </literallayout>
99 Several different versions of <filename>matchbox-desktop</filename> might exist.
100 BitBake chooses the one selected by the distribution configuration.
101 You can get more details about how BitBake chooses between different
102 target versions and providers in the
103 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-bitbake-providers'>Preferences and Providers</ulink>"
104 section of the BitBake User Manual.
105 </para>
106
107 <para>
108 BitBake also tries to execute any dependent tasks first.
109 So for example, before building <filename>matchbox-desktop</filename>, BitBake
110 would build a cross compiler and <filename>eglibc</filename> if they had not already
111 been built.
112 <note>This release of the Yocto Project does not support the <filename>glibc</filename>
113 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
114 builds with <filename>eglibc</filename>.</note>
115 </para>
116
117 <para>
118 A useful BitBake option to consider is the <filename>-k</filename> or
119 <filename>--continue</filename> option.
120 This option instructs BitBake to try and continue processing the job
121 as long as possible even after encountering an error.
122 When an error occurs, the target that
123 failed and those that depend on it cannot be remade.
124 However, when you use this option other dependencies can still be
125 processed.
126 </para>
127 </section>
128
129 <section id='usingpoky-components-metadata'>
130 <title>Metadata (Recipes)</title>
131
132 <para>
133 Files that have the <filename>.bb</filename> suffix are "recipes"
134 files.
135 In general, a recipe contains information about a single piece of
136 software.
137 This information includes the location from which to download the
138 unaltered source, any source patches to be applied to that source
139 (if needed), which special configuration options to apply,
140 how to compile the source files, and how to package the compiled
141 output.
142 </para>
143
144 <para>
145 The term "package" is sometimes used to refer to recipes. However,
146 since the word "package" is used for the packaged output from the OpenEmbedded
147 build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
148 this document avoids using the term "package" when referring to recipes.
149 </para>
150 </section>
151
152 <section id='usingpoky-components-classes'>
153 <title>Classes</title>
154
155 <para>
156 Class files (<filename>.bbclass</filename>) contain information that
157 is useful to share between
158 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> files.
159 An example is the
160 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
161 class, which contains common settings for any application that
162 Autotools uses.
163 The "<link linkend='ref-classes'>Classes</link>" chapter provides
164 details about classes and how to use them.
165 </para>
166 </section>
167
168 <section id='usingpoky-components-configuration'>
169 <title>Configuration</title>
170
171 <para>
172 The configuration files (<filename>.conf</filename>) define various configuration variables
173 that govern the OpenEmbedded build process.
174 These files fall into several areas that define machine configuration options,
175 distribution configuration options, compiler tuning options, general common configuration
176 options, and user configuration options in <filename>local.conf</filename>, which is found
177 in the
178 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
179 </para>
180 </section>
181</section>
182
183<section id="cross-development-toolchain-generation">
184 <title>Cross-Development Toolchain Generation</title>
185
186 <para>
187 The Yocto Project does most of the work for you when it comes to
188 creating
189 <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
190 This section provides some technical background on how
191 cross-development toolchains are created and used.
192 For more information on toolchains, you can also see the
193 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>.
194 </para>
195
196 <para>
197 In the Yocto Project development environment, cross-development
198 toolchains are used to build the image and applications that run on the
199 target hardware.
200 With just a few commands, the OpenEmbedded build system creates
201 these necessary toolchains for you.
202 </para>
203
204 <para>
205 The following figure shows a high-level build environment regarding
206 toolchain construction and use.
207 </para>
208
209 <para>
210 <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
211 </para>
212
213 <para>
214 Most of the work occurs on the Build Host.
215 This is the machine used to build images and generally work within the
216 the Yocto Project environment.
217 When you run BitBake to create an image, the OpenEmbedded build system
218 uses the host <filename>gcc</filename> compiler to bootstrap a
219 cross-compiler named <filename>gcc-cross</filename>.
220 The <filename>gcc-cross</filename> compiler is what BitBake uses to
221 compile source files when creating the target image.
222 You can think of <filename>gcc-cross</filename> simply as an
223 automatically generated cross-compiler that is used internally within
224 BitBake only.
225 </para>
226
227 <para>
228 The chain of events that occurs when <filename>gcc-cross</filename> is
229 bootstrapped is as follows:
230 <literallayout class='monospaced'>
231 gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> eglibc-initial -> eglibc -> gcc-cross -> gcc-runtime
232 </literallayout>
233 <itemizedlist>
234 <listitem><para><filename>gcc</filename>:
235 The build host's GNU Compiler Collection (GCC).
236 </para></listitem>
237 <listitem><para><filename>binutils-cross</filename>:
238 The bare minimum binary utilities needed in order to run
239 the <filename>gcc-cross-initial</filename> phase of the
240 bootstrap operation.
241 </para></listitem>
242 <listitem><para><filename>gcc-cross-initial</filename>:
243 An early stage of the bootstrap process for creating
244 the cross-compiler.
245 This stage builds enough of the <filename>gcc-cross</filename>,
246 the C library, and other pieces needed to finish building the
247 final cross-compiler in later stages.
248 This tool is a "native" package (i.e. it is designed to run on
249 the build host).
250 </para></listitem>
251 <listitem><para><filename>linux-libc-headers</filename>:
252 Headers needed for the cross-compiler.
253 </para></listitem>
254 <listitem><para><filename>eglibc-initial</filename>:
255 An initial version of the Embedded GLIBC needed to bootstrap
256 <filename>eglibc</filename>.
257 </para></listitem>
258 <listitem><para><filename>gcc-cross</filename>:
259 The final stage of the bootstrap process for the
260 cross-compiler.
261 This stage results in the actual cross-compiler that
262 BitBake uses when it builds an image for a targeted
263 device.
264 <note>
265 If you are replacing this cross compiler toolchain
266 with a custom version, you must replace
267 <filename>gcc-cross</filename>.
268 </note>
269 This tool is also a "native" package (i.e. it is
270 designed to run on the build host).
271 </para></listitem>
272 <listitem><para><filename>gcc-runtime</filename>:
273 Runtime libraries resulting from the toolchain bootstrapping
274 process.
275 This tool produces a binary that consists of the
276 runtime libraries need for the targeted device.
277 </para></listitem>
278 </itemizedlist>
279 </para>
280
281 <para>
282 You can use the OpenEmbedded build system to build an installer for
283 the relocatable SDK used to develop applications.
284 When you run the installer, it installs the toolchain, which contains
285 the development tools (e.g., the
286 <filename>gcc-cross-canadian</filename>),
287 <filename>binutils-cross-canadian</filename>, and other
288 <filename>nativesdk-*</filename> tools you need to cross-compile and
289 test your software.
290 The figure shows the commands you use to easily build out this
291 toolchain.
292 This cross-development toolchain is built to execute on the
293 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
294 which might or might not be the same
295 machine as the Build Host.
296 <note>
297 If your target architecture is supported by the Yocto Project,
298 you can take advantage of pre-built images that ship with the
299 Yocto Project and already contain cross-development toolchain
300 installers.
301 </note>
302 </para>
303
304 <para>
305 Here is the bootstrap process for the relocatable toolchain:
306 <literallayout class='monospaced'>
307 gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> eglibc-initial -> nativesdk-eglibc -> gcc-crosssdk -> gcc-cross-canadian
308 </literallayout>
309 <itemizedlist>
310 <listitem><para><filename>gcc</filename>:
311 The build host's GNU Compiler Collection (GCC).
312 </para></listitem>
313 <listitem><para><filename>binutils-crosssdk</filename>:
314 The bare minimum binary utilities needed in order to run
315 the <filename>gcc-crosssdk-initial</filename> phase of the
316 bootstrap operation.
317 </para></listitem>
318 <listitem><para><filename>gcc-crosssdk-initial</filename>:
319 An early stage of the bootstrap process for creating
320 the cross-compiler.
321 This stage builds enough of the
322 <filename>gcc-crosssdk</filename> and supporting pieces so that
323 the final stage of the bootstrap process can produce the
324 finished cross-compiler.
325 This tool is a "native" binary that runs on the build host.
326 </para></listitem>
327 <listitem><para><filename>linux-libc-headers</filename>:
328 Headers needed for the cross-compiler.
329 </para></listitem>
330 <listitem><para><filename>eglibc-initial</filename>:
331 An initial version of the Embedded GLIBC needed to bootstrap
332 <filename>nativesdk-eglibc</filename>.
333 </para></listitem>
334 <listitem><para><filename>nativesdk-eglibc</filename>:
335 The Embedded GLIBC needed to bootstrap the
336 <filename>gcc-crosssdk</filename>.
337 </para></listitem>
338 <listitem><para><filename>gcc-crosssdk</filename>:
339 The final stage of the bootstrap process for the
340 relocatable cross-compiler.
341 The <filename>gcc-crosssdk</filename> is a transitory compiler
342 and never leaves the build host.
343 Its purpose is to help in the bootstrap process to create the
344 eventual relocatable <filename>gcc-cross-canadian</filename>
345 compiler, which is relocatable.
346 This tool is also a "native" package (i.e. it is
347 designed to run on the build host).
348 </para></listitem>
349 <listitem><para><filename>gcc-cross-canadian</filename>:
350 The final relocatable cross-compiler.
351 When run on the
352 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
353 this tool
354 produces executable code that runs on the target device.
355 Only one cross-canadian compiler is produced per architecture
356 since they can be targeted at different processor optimizations
357 using configurations passed to the compiler through the
358 compile commands.
359 This circumvents the need for multiple compilers and thus
360 reduces the size of the toolchains.
361 </para></listitem>
362 </itemizedlist>
363 </para>
364
365 <note>
366 For information on advantages gained when building a
367 cross-development toolchain installer, see the
368 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
369 section in the Yocto Project Application Developer's Guide.
370 </note>
371</section>
372
373<section id="shared-state-cache">
374 <title>Shared State Cache</title>
375
376 <para>
377 By design, the OpenEmbedded build system builds everything from scratch unless
378 BitBake can determine that parts do not need to be rebuilt.
379 Fundamentally, building from scratch is attractive as it means all parts are
380 built fresh and there is no possibility of stale data causing problems.
381 When developers hit problems, they typically default back to building from scratch
382 so they know the state of things from the start.
383 </para>
384
385 <para>
386 Building an image from scratch is both an advantage and a disadvantage to the process.
387 As mentioned in the previous paragraph, building from scratch ensures that
388 everything is current and starts from a known state.
389 However, building from scratch also takes much longer as it generally means
390 rebuilding things that do not necessarily need to be rebuilt.
391 </para>
392
393 <para>
394 The Yocto Project implements shared state code that supports incremental builds.
395 The implementation of the shared state code answers the following questions that
396 were fundamental roadblocks within the OpenEmbedded incremental build support system:
397 <itemizedlist>
398 <listitem><para>What pieces of the system have changed and what pieces have
399 not changed?</para></listitem>
400 <listitem><para>How are changed pieces of software removed and replaced?</para></listitem>
401 <listitem><para>How are pre-built components that do not need to be rebuilt from scratch
402 used when they are available?</para></listitem>
403 </itemizedlist>
404 </para>
405
406 <para>
407 For the first question, the build system detects changes in the "inputs" to a given task by
408 creating a checksum (or signature) of the task's inputs.
409 If the checksum changes, the system assumes the inputs have changed and the task needs to be
410 rerun.
411 For the second question, the shared state (sstate) code tracks which tasks add which output
412 to the build process.
413 This means the output from a given task can be removed, upgraded or otherwise manipulated.
414 The third question is partly addressed by the solution for the second question
415 assuming the build system can fetch the sstate objects from remote locations and
416 install them if they are deemed to be valid.
417 </para>
418
419 <note>
420 The OpenEmbedded build system does not maintain
421 <link linkend='var-PR'><filename>PR</filename></link> information
422 as part of the shared state packages.
423 Consequently, considerations exist that affect maintaining shared
424 state feeds.
425 For information on how the OpenEmbedded build system
426 works with packages and can
427 track incrementing <filename>PR</filename> information, see the
428 "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a Package Revision Number</ulink>"
429 section.
430 </note>
431
432 <para>
433 The rest of this section goes into detail about the overall incremental build
434 architecture, the checksums (signatures), shared state, and some tips and tricks.
435 </para>
436
437 <section id='overall-architecture'>
438 <title>Overall Architecture</title>
439
440 <para>
441 When determining what parts of the system need to be built, BitBake
442 works on a per-task basis rather than a per-recipe basis.
443 You might wonder why using a per-task basis is preferred over a per-recipe basis.
444 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
445 In this case, <filename>do_install</filename> and <filename>do_package</filename>
446 outputs are still valid.
447 However, with a per-recipe approach, the build would not include the
448 <filename>.deb</filename> files.
449 Consequently, you would have to invalidate the whole build and rerun it.
450 Rerunning everything is not the best solution.
451 Also, in this case, the core must be "taught" much about specific tasks.
452 This methodology does not scale well and does not allow users to easily add new tasks
453 in layers or as external recipes without touching the packaged-staging core.
454 </para>
455 </section>
456
457 <section id='checksums'>
458 <title>Checksums (Signatures)</title>
459
460 <para>
461 The shared state code uses a checksum, which is a unique signature of a task's
462 inputs, to determine if a task needs to be run again.
463 Because it is a change in a task's inputs that triggers a rerun, the process
464 needs to detect all the inputs to a given task.
465 For shell tasks, this turns out to be fairly easy because
466 the build process generates a "run" shell script for each task and
467 it is possible to create a checksum that gives you a good idea of when
468 the task's data changes.
469 </para>
470
471 <para>
472 To complicate the problem, there are things that should not be included in
473 the checksum.
474 First, there is the actual specific build path of a given task -
475 the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
476 It does not matter if the work directory changes because it should not
477 affect the output for target packages.
478 Also, the build process has the objective of making native or cross packages relocatable.
479 The checksum therefore needs to exclude <filename>WORKDIR</filename>.
480 The simplistic approach for excluding the work directory is to set
481 <filename>WORKDIR</filename> to some fixed value and create the checksum
482 for the "run" script.
483 </para>
484
485 <para>
486 Another problem results from the "run" scripts containing functions that
487 might or might not get called.
488 The incremental build solution contains code that figures out dependencies
489 between shell functions.
490 This code is used to prune the "run" scripts down to the minimum set,
491 thereby alleviating this problem and making the "run" scripts much more
492 readable as a bonus.
493 </para>
494
495 <para>
496 So far we have solutions for shell scripts.
497 What about Python tasks?
498 The same approach applies even though these tasks are more difficult.
499 The process needs to figure out what variables a Python function accesses
500 and what functions it calls.
501 Again, the incremental build solution contains code that first figures out
502 the variable and function dependencies, and then creates a checksum for the data
503 used as the input to the task.
504 </para>
505
506 <para>
507 Like the <filename>WORKDIR</filename> case, situations exist where dependencies
508 should be ignored.
509 For these cases, you can instruct the build process to ignore a dependency
510 by using a line like the following:
511 <literallayout class='monospaced'>
512 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
513 </literallayout>
514 This example ensures that the <filename>PACKAGE_ARCHS</filename>
515 variable does not
516 depend on the value of
517 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
518 even if it does reference it.
519 </para>
520
521 <para>
522 Equally, there are cases where we need to add dependencies BitBake is not able to find.
523 You can accomplish this by using a line like the following:
524 <literallayout class='monospaced'>
525 PACKAGE_ARCHS[vardeps] = "MACHINE"
526 </literallayout>
527 This example explicitly adds the <filename>MACHINE</filename> variable as a
528 dependency for <filename>PACKAGE_ARCHS</filename>.
529 </para>
530
531 <para>
532 Consider a case with in-line Python, for example, where BitBake is not
533 able to figure out dependencies.
534 When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
535 produces output when it discovers something for which it cannot figure out
536 dependencies.
537 The Yocto Project team has currently not managed to cover those dependencies
538 in detail and is aware of the need to fix this situation.
539 </para>
540
541 <para>
542 Thus far, this section has limited discussion to the direct inputs into a task.
543 Information based on direct inputs is referred to as the "basehash" in the
544 code.
545 However, there is still the question of a task's indirect inputs - the
546 things that were already built and present in the
547 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
548 The checksum (or signature) for a particular task needs to add the hashes
549 of all the tasks on which the particular task depends.
550 Choosing which dependencies to add is a policy decision.
551 However, the effect is to generate a master checksum that combines the basehash
552 and the hashes of the task's dependencies.
553 </para>
554
555 <para>
556 At the code level, there are a variety of ways both the basehash and the
557 dependent task hashes can be influenced.
558 Within the BitBake configuration file, we can give BitBake some extra information
559 to help it construct the basehash.
560 The following statement effectively results in a list of global variable
561 dependency excludes - variables never included in any checksum:
562 <literallayout class='monospaced'>
563 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
564 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
565 USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
566 PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
567 CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
568 </literallayout>
569 The previous example excludes
570 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
571 since that variable is actually constructed as a path within
572 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
573 the whitelist.
574 </para>
575
576 <para>
577 The rules for deciding which hashes of dependent tasks to include through
578 dependency chains are more complex and are generally accomplished with a
579 Python function.
580 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
581 of this and also illustrates how you can insert your own policy into the system
582 if so desired.
583 This file defines the two basic signature generators <filename>OE-Core</filename>
584 uses: "OEBasic" and "OEBasicHash".
585 By default, there is a dummy "noop" signature handler enabled in BitBake.
586 This means that behavior is unchanged from previous versions.
587 <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
588 through this setting in the <filename>bitbake.conf</filename> file:
589 <literallayout class='monospaced'>
590 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
591 </literallayout>
592 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
593 "OEBasic" version but adds the task hash to the stamp files.
594 This results in any
595 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
596 change that changes the task hash, automatically
597 causing the task to be run again.
598 This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
599 values, and changes to Metadata automatically ripple across the build.
600 </para>
601
602 <para>
603 It is also worth noting that the end result of these signature generators is to
604 make some dependency and hash information available to the build.
605 This information includes:
606 <itemizedlist>
607 <listitem><para><filename>BB_BASEHASH_task-&lt;taskname&gt;</filename>:
608 The base hashes for each task in the recipe.
609 </para></listitem>
610 <listitem><para><filename>BB_BASEHASH_&lt;filename:taskname&gt;</filename>:
611 The base hashes for each dependent task.
612 </para></listitem>
613 <listitem><para><filename>BBHASHDEPS_&lt;filename:taskname&gt;</filename>:
614 The task dependencies for each task.
615 </para></listitem>
616 <listitem><para><filename>BB_TASKHASH</filename>:
617 The hash of the currently running task.
618 </para></listitem>
619 </itemizedlist>
620 </para>
621 </section>
622
623 <section id='shared-state'>
624 <title>Shared State</title>
625
626 <para>
627 Checksums and dependencies, as discussed in the previous section, solve half the
628 problem of supporting a shared state.
629 The other part of the problem is being able to use checksum information during the build
630 and being able to reuse or rebuild specific components.
631 </para>
632
633 <para>
634 The
635 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
636 class is a relatively generic implementation of how to "capture"
637 a snapshot of a given task.
638 The idea is that the build process does not care about the source of a task's output.
639 Output could be freshly built or it could be downloaded and unpacked from
640 somewhere - the build process does not need to worry about its origin.
641 </para>
642
643 <para>
644 There are two types of output, one is just about creating a directory
645 in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
646 A good example is the output of either <filename>do_install</filename> or
647 <filename>do_package</filename>.
648 The other type of output occurs when a set of data is merged into a shared directory
649 tree such as the sysroot.
650 </para>
651
652 <para>
653 The Yocto Project team has tried to keep the details of the
654 implementation hidden in <filename>sstate</filename> class.
655 From a user's perspective, adding shared state wrapping to a task
656 is as simple as this <filename>do_deploy</filename> example taken
657 from the
658 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
659 class:
660 <literallayout class='monospaced'>
661 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
662 SSTATETASKS += "do_deploy"
663 do_deploy[sstate-name] = "deploy"
664 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
665 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
666
667 python do_deploy_setscene () {
668 sstate_setscene(d)
669 }
670 addtask do_deploy_setscene
671 do_deploy[dirs] = "${DEPLOYDIR} ${B}"
672 </literallayout>
673 In this example, we add some extra flags to the task, a name field ("deploy"), an
674 input directory where the task sends data, and the output
675 directory where the data from the task should eventually be copied.
676 We also add a <filename>_setscene</filename> variant of the task and add the task
677 name to the <filename>SSTATETASKS</filename> list.
678 </para>
679
680 <para>
681 If you have a directory whose contents you need to preserve, you can do this with
682 a line like the following:
683 <literallayout class='monospaced'>
684 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
685 </literallayout>
686 This method, as well as the following example, also works for multiple directories.
687 <literallayout class='monospaced'>
688 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
689 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
690 do_package[sstate-lockfile] = "${PACKAGELOCK}"
691 </literallayout>
692 These methods also include the ability to take a lockfile when manipulating
693 shared state directory structures since some cases are sensitive to file
694 additions or removals.
695 </para>
696
697 <para>
698 Behind the scenes, the shared state code works by looking in
699 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
700 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
701 for shared state files.
702 Here is an example:
703 <literallayout class='monospaced'>
704 SSTATE_MIRRORS ?= "\
705 file://.* http://someserver.tld/share/sstate/PATH \n \
706 file://.* file:///some/local/dir/sstate/PATH"
707 </literallayout>
708 <note>
709 The shared state directory (<filename>SSTATE_DIR</filename>) is
710 organized into two-character subdirectories, where the subdirectory
711 names are based on the first two characters of the hash.
712 If the shared state directory structure for a mirror has the
713 same structure as <filename>SSTATE_DIR</filename>, you must
714 specify "PATH" as part of the URI to enable the build system
715 to map to the appropriate subdirectory.
716 </note>
717 </para>
718
719 <para>
720 The shared state package validity can be detected just by looking at the
721 filename since the filename contains the task checksum (or signature) as
722 described earlier in this section.
723 If a valid shared state package is found, the build process downloads it
724 and uses it to accelerate the task.
725 </para>
726
727 <para>
728 The build processes use the <filename>*_setscene</filename> tasks
729 for the task acceleration phase.
730 BitBake goes through this phase before the main execution code and tries
731 to accelerate any tasks for which it can find shared state packages.
732 If a shared state package for a task is available, the shared state
733 package is used.
734 This means the task and any tasks on which it is dependent are not
735 executed.
736 </para>
737
738 <para>
739 As a real world example, the aim is when building an IPK-based image,
740 only the <filename>do_package_write_ipk</filename> tasks would have their
741 shared state packages fetched and extracted.
742 Since the sysroot is not used, it would never get extracted.
743 This is another reason why a task-based approach is preferred over a
744 recipe-based approach, which would have to install the output from every task.
745 </para>
746 </section>
747
748 <section id='tips-and-tricks'>
749 <title>Tips and Tricks</title>
750
751 <para>
752 The code in the build system that supports incremental builds is not
753 simple code.
754 This section presents some tips and tricks that help you work around
755 issues related to shared state code.
756 </para>
757
758 <section id='debugging'>
759 <title>Debugging</title>
760
761 <para>
762 When things go wrong, debugging needs to be straightforward.
763 Because of this, the Yocto Project includes strong debugging
764 tools:
765 <itemizedlist>
766 <listitem><para>Whenever a shared state package is written out, so is a
767 corresponding <filename>.siginfo</filename> file.
768 This practice results in a pickled Python database of all
769 the metadata that went into creating the hash for a given shared state
770 package.</para></listitem>
771 <listitem><para>If you run BitBake with the <filename>--dump-signatures</filename>
772 (or <filename>-S</filename>) option, BitBake dumps out
773 <filename>.siginfo</filename> files in
774 the stamp directory for every task it would have executed instead of
775 building the specified target package.</para></listitem>
776 <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
777 can process <filename>.siginfo</filename> files.
778 If you specify one of these files, BitBake dumps out the dependency
779 information in the file.
780 If you specify two files, BitBake compares the two files and dumps out
781 the differences between the two.
782 This more easily helps answer the question of "What
783 changed between X and Y?"</para></listitem>
784 </itemizedlist>
785 </para>
786 </section>
787
788 <section id='invalidating-shared-state'>
789 <title>Invalidating Shared State</title>
790
791 <para>
792 The OpenEmbedded build system uses checksums and shared state
793 cache to avoid unnecessarily rebuilding tasks.
794 Collectively, this scheme is known as "shared state code."
795 </para>
796
797 <para>
798 As with all schemes, this one has some drawbacks.
799 It is possible that you could make implicit changes to your
800 code that the checksum calculations do not take into
801 account.
802 These implicit changes affect a task's output but do not trigger
803 the shared state code into rebuilding a recipe.
804 Consider an example during which a tool changes its output.
805 Assume that the output of <filename>rpmdeps</filename> changes.
806 The result of the change should be that all the
807 <filename>package</filename> and
808 <filename>package_write_rpm</filename> shared state cache
809 items become invalid.
810 However, because the change to the output is
811 external to the code and therefore implicit,
812 the associated shared state cache items do not become
813 invalidated.
814 In this case, the build process uses the cached items rather
815 than running the task again.
816 Obviously, these types of implicit changes can cause problems.
817 </para>
818
819 <para>
820 To avoid these problems during the build, you need to
821 understand the effects of any changes you make.
822 Realize that changes you make directly to a function
823 are automatically factored into the checksum calculation.
824 Thus, these explicit changes invalidate the associated area of
825 shared state cache.
826 However, you need to be aware of any implicit changes that
827 are not obvious changes to the code and could affect the output
828 of a given task.
829 </para>
830
831 <para>
832 When you identify an implicit change, you can easily take steps
833 to invalidate the cache and force the tasks to run.
834 The steps you can take are as simple as changing a function's
835 comments in the source code.
836 For example, to invalidate package shared state files, change
837 the comment statements of <filename>do_package</filename> or
838 the comments of one of the functions it calls.
839 Even though the change is purely cosmetic, it causes the
840 checksum to be recalculated and forces the OpenEmbedded build
841 system to run the task again.
842 </para>
843
844 <note>
845 For an example of a commit that makes a cosmetic change to
846 invalidate shared state, see this
847 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
848 </note>
849 </section>
850 </section>
851</section>
852
853<section id='x32'>
854 <title>x32</title>
855
856 <para>
857 x32 is a processor-specific Application Binary Interface (psABI) for x86_64.
858 An ABI defines the calling conventions between functions in a processing environment.
859 The interface determines what registers are used and what the sizes are for various C data types.
860 </para>
861
862 <para>
863 Some processing environments prefer using 32-bit applications even when running
864 on Intel 64-bit platforms.
865 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
866 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
867 leaving the system underutilized.
868 Now consider the x86_64 psABI.
869 This ABI is newer and uses 64-bits for data sizes and program pointers.
870 The extra bits increase the footprint size of the programs, libraries,
871 and also increases the memory and file system size requirements.
872 Executing under the x32 psABI enables user programs to utilize CPU and system resources
873 more efficiently while keeping the memory footprint of the applications low.
874 Extra bits are used for registers but not for addressing mechanisms.
875 </para>
876
877 <section id='support'>
878 <title>Support</title>
879
880 <para>
881 This Yocto Project release supports the final specifications of x32
882 psABI.
883 Support for x32 psABI exists as follows:
884 <itemizedlist>
885 <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
886 </para></listitem>
887 <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
888 <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
889 <filename>core-image-sato</filename> images.</para></listitem>
890 </itemizedlist>
891 </para>
892 </section>
893
894 <section id='completing-x32'>
895 <title>Completing x32</title>
896
897 <para>
898 Future Plans for the x32 psABI in the Yocto Project include the following:
899 <itemizedlist>
900 <listitem><para>Enhance and fix the few remaining recipes so they
901 work with and support x32 toolchains.</para></listitem>
902 <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
903 <listitem><para>Support larger images.</para></listitem>
904 </itemizedlist>
905 </para>
906 </section>
907
908 <section id='using-x32-right-now'>
909 <title>Using x32 Right Now</title>
910
911 <para>
912 Follow these steps to use the x32 spABI:
913 <itemizedlist>
914 <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
915 machines by editing the <filename>conf/local.conf</filename> like this:
916 <literallayout class='monospaced'>
917 MACHINE = "qemux86-64"
918 DEFAULTTUNE = "x86-64-x32"
919 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
920 or 'INVALID'), True) or 'lib'}"
921 #MACHINE = "genericx86"
922 #DEFAULTTUNE = "core2-64-x32"
923 </literallayout></para></listitem>
924 <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
925 Here is an example:
926 <literallayout class='monospaced'>
927 $ bitbake core-image-sato
928 </literallayout></para></listitem>
929 <listitem><para>As usual, run your image using QEMU:
930 <literallayout class='monospaced'>
931 $ runqemu qemux86-64 core-image-sato
932 </literallayout></para></listitem>
933 </itemizedlist>
934 </para>
935 </section>
936</section>
937
938<section id="wayland">
939 <title>Wayland</title>
940
941 <para>
942 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink>
943 is a computer display server protocol that
944 provides a method for compositing window managers to communicate
945 directly with applications and video hardware and expects them to
946 communicate with input hardware using other libraries.
947 Using Wayland with supporting targets can result in better control
948 over graphics frame rendering than an application might otherwise
949 achieve.
950 </para>
951
952 <para>
953 The Yocto Project provides the Wayland protocol libraries and the
954 reference
955 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink>
956 compositor as part of its release.
957 This section describes what you need to do to implement Wayland and
958 use the compositor when building an image for a supporting target.
959 </para>
960
961 <section id="wayland-support">
962 <title>Support</title>
963
964 <para>
965 The Wayland protocol libraries and the reference Weston compositor
966 ship as integrated packages in the <filename>meta</filename> layer
967 of the
968 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
969 Specifically, you can find the recipes that build both Wayland
970 and Weston at <filename>meta/recipes-graphics/wayland</filename>.
971 </para>
972
973 <para>
974 You can build both the Wayland and Weston packages for use only
975 with targets that accept the
976 <ulink url='http://dri.freedesktop.org/wiki/'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
977 which is also known as Mesa DRI.
978 This implies that you cannot build and use the packages if your
979 target uses, for example, the
980 <trademark class='registered'>Intel</trademark> Embedded Media and
981 Graphics Driver (<trademark class='registered'>Intel</trademark>
982 EMGD) that overrides Mesa DRI.
983 </para>
984
985 <note>
986 Due to lack of EGL support, Weston 1.0.3 will not run directly on
987 the emulated QEMU hardware.
988 However, this version of Weston will run under X emulation without
989 issues.
990 </note>
991 </section>
992
993 <section id="enabling-wayland-in-an-image">
994 <title>Enabling Wayland in an Image</title>
995
996 <para>
997 To enable Wayland, you need to enable it to be built and enable
998 it to be included in the image.
999 </para>
1000
1001 <section id="enable-building">
1002 <title>Building</title>
1003
1004 <para>
1005 To cause Mesa to build the <filename>wayland-egl</filename>
1006 platform and Weston to build Wayland with Kernel Mode
1007 Setting
1008 (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
1009 support, include the "wayland" flag in the
1010 <link linkend="var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></link>
1011 statement in your <filename>local.conf</filename> file:
1012 <literallayout class='monospaced'>
1013 DISTRO_FEATURES_append = " wayland"
1014 </literallayout>
1015 </para>
1016
1017 <note>
1018 If X11 has been enabled elsewhere, Weston will build Wayland
1019 with X11 support
1020 </note>
1021 </section>
1022
1023 <section id="enable-installation-in-an-image">
1024 <title>Installing</title>
1025
1026 <para>
1027 To install the Wayland feature into an image, you must
1028 include the following
1029 <link linkend='var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></link>
1030 statement in your <filename>local.conf</filename> file:
1031 <literallayout class='monospaced'>
1032 CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
1033 </literallayout>
1034 </para>
1035 </section>
1036 </section>
1037
1038 <section id="running-weston">
1039 <title>Running Weston</title>
1040
1041 <para>
1042 To run Weston inside X11, enabling it as described earlier and
1043 building a Sato image is sufficient.
1044 If you are running your image under Sato, a Weston Launcher appears
1045 in the "Utility" category.
1046 </para>
1047
1048 <para>
1049 Alternatively, you can run Weston through the command-line
1050 interpretor (CLI), which is better suited for development work.
1051 To run Weston under the CLI, you need to do the following after
1052 your image is built:
1053 <orderedlist>
1054 <listitem><para>Run these commands to export
1055 <filename>XDG_RUNTIME_DIR</filename>:
1056 <literallayout class='monospaced'>
1057 mkdir -p /tmp/$USER-weston
1058 chmod 0700 /tmp/$USER-weston
1059 export XDG_RUNTIME_DIR=/tmp/$USER-weston
1060 </literallayout></para></listitem>
1061 <listitem><para>Launch Weston in the shell:
1062 <literallayout class='monospaced'>
1063 weston
1064 </literallayout></para></listitem>
1065 </orderedlist>
1066 </para>
1067 </section>
1068</section>
1069
1070<section id="licenses">
1071 <title>Licenses</title>
1072
1073 <para>
1074 This section describes the mechanism by which the OpenEmbedded build system
1075 tracks changes to licensing text.
1076 The section also describes how to enable commercially licensed recipes,
1077 which by default are disabled.
1078 </para>
1079
1080 <para>
1081 For information that can help you maintain compliance with various open
1082 source licensing during the lifecycle of the product, see the
1083 "<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
1084 in the Yocto Project Development Manual.
1085 </para>
1086
1087 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
1088 <title>Tracking License Changes</title>
1089
1090 <para>
1091 The license of an upstream project might change in the future.
1092 In order to prevent these changes going unnoticed, the
1093 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
1094 variable tracks changes to the license text. The checksums are validated at the end of the
1095 configure step, and if the checksums do not match, the build will fail.
1096 </para>
1097
1098 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
1099 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
1100
1101 <para>
1102 The <filename>LIC_FILES_CHKSUM</filename>
1103 variable contains checksums of the license text in the source code for the recipe.
1104 Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
1105 <literallayout class='monospaced'>
1106 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
1107 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
1108 file://licfile2.txt;endline=50;md5=zzzz \
1109 ..."
1110 </literallayout>
1111 </para>
1112
1113 <para>
1114 The build system uses the
1115 <filename><link linkend='var-S'>S</link></filename> variable as
1116 the default directory when searching files listed in
1117 <filename>LIC_FILES_CHKSUM</filename>.
1118 The previous example employs the default directory.
1119 </para>
1120
1121 <para>
1122 Consider this next example:
1123 <literallayout class='monospaced'>
1124 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
1125 md5=bb14ed3c4cda583abc85401304b5cd4e"
1126 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1127 </literallayout>
1128 </para>
1129
1130 <para>
1131 The first line locates a file in
1132 <filename>${S}/src/ls.c</filename>.
1133 The second line refers to a file in
1134 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
1135 </para>
1136 <para>
1137 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
1138 mandatory for all recipes, unless the
1139 <filename>LICENSE</filename> variable is set to "CLOSED".
1140 </para>
1141 </section>
1142
1143 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
1144 <title>Explanation of Syntax</title>
1145 <para>
1146 As mentioned in the previous section, the
1147 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
1148 important files that contain the license text for the source code.
1149 It is possible to specify a checksum for an entire file, or a specific section of a
1150 file (specified by beginning and ending line numbers with the "beginline" and "endline"
1151 parameters, respectively).
1152 The latter is useful for source files with a license notice header,
1153 README documents, and so forth.
1154 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
1155 first line of the file.
1156 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
1157 ends with the last line of the file.
1158 </para>
1159
1160 <para>
1161 The "md5" parameter stores the md5 checksum of the license text.
1162 If the license text changes in any way as compared to this parameter
1163 then a mismatch occurs.
1164 This mismatch triggers a build failure and notifies the developer.
1165 Notification allows the developer to review and address the license text changes.
1166 Also note that if a mismatch occurs during the build, the correct md5
1167 checksum is placed in the build log and can be easily copied to the recipe.
1168 </para>
1169
1170 <para>
1171 There is no limit to how many files you can specify using the
1172 <filename>LIC_FILES_CHKSUM</filename> variable.
1173 Generally, however, every project requires a few specifications for license tracking.
1174 Many projects have a "COPYING" file that stores the license information for all the source
1175 code files.
1176 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
1177 </para>
1178
1179 <tip>
1180 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
1181 error and displays the correct "md5" parameter value during the build.
1182 The correct parameter is also captured in the build log.
1183 </tip>
1184
1185 <tip>
1186 If the whole file contains only license text, you do not need to use the "beginline" and
1187 "endline" parameters.
1188 </tip>
1189 </section>
1190 </section>
1191
1192 <section id="enabling-commercially-licensed-recipes">
1193 <title>Enabling Commercially Licensed Recipes</title>
1194
1195 <para>
1196 By default, the OpenEmbedded build system disables
1197 components that have commercial or other special licensing
1198 requirements.
1199 Such requirements are defined on a
1200 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
1201 definition in the affected recipe.
1202 For instance, the
1203 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1204 recipe contains the following statement:
1205 <literallayout class='monospaced'>
1206 LICENSE_FLAGS = "commercial"
1207 </literallayout>
1208 Here is a slightly more complicated example that contains both an
1209 explicit recipe name and version (after variable expansion):
1210 <literallayout class='monospaced'>
1211 LICENSE_FLAGS = "license_${PN}_${PV}"
1212 </literallayout>
1213 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
1214 definition to be enabled and included in an image, it
1215 needs to have a matching entry in the global
1216 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
1217 typically defined in your <filename>local.conf</filename> file.
1218 For example, to enable
1219 the <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1220 package, you could add either the string
1221 "commercial_gst-plugins-ugly" or the more general string
1222 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
1223 See the
1224 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
1225 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
1226 Here is the example:
1227 <literallayout class='monospaced'>
1228 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
1229 </literallayout>
1230 Likewise, to additionally enable the package built from the recipe containing
1231 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
1232 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
1233 the following string would enable that package as well as
1234 the original <filename>gst-plugins-ugly</filename> package:
1235 <literallayout class='monospaced'>
1236 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
1237 </literallayout>
1238 As a convenience, you do not need to specify the complete license string
1239 in the whitelist for every package.
1240 You can use an abbreviated form, which consists
1241 of just the first portion or portions of the license string before
1242 the initial underscore character or characters.
1243 A partial string will match
1244 any license that contains the given string as the first
1245 portion of its license.
1246 For example, the following
1247 whitelist string will also match both of the packages
1248 previously mentioned as well as any other packages that have
1249 licenses starting with "commercial" or "license".
1250 <literallayout class='monospaced'>
1251 LICENSE_FLAGS_WHITELIST = "commercial license"
1252 </literallayout>
1253 </para>
1254
1255 <section id="license-flag-matching">
1256 <title>License Flag Matching</title>
1257
1258 <para>
1259 License flag matching allows you to control what recipes the
1260 OpenEmbedded build system includes in the build.
1261 Fundamentally, the build system attempts to match
1262 <filename>LICENSE_FLAGS</filename> strings found in
1263 recipes against <filename>LICENSE_FLAGS_WHITELIST</filename>
1264 strings found in the whitelist.
1265 A match causes the build system to include a recipe in the
1266 build, while failure to find a match causes the build system to
1267 exclude a recipe.
1268 </para>
1269
1270 <para>
1271 In general, license flag matching is simple.
1272 However, understanding some concepts will help you
1273 correctly and effectively use matching.
1274 </para>
1275
1276 <para>
1277 Before a flag
1278 defined by a particular recipe is tested against the
1279 contents of the whitelist, the expanded string
1280 <filename>_${PN}</filename> is appended to the flag.
1281 This expansion makes each <filename>LICENSE_FLAGS</filename>
1282 value recipe-specific.
1283 After expansion, the string is then matched against the
1284 whitelist.
1285 Thus, specifying
1286 <filename>LICENSE_FLAGS = "commercial"</filename>
1287 in recipe "foo", for example, results in the string
1288 <filename>"commercial_foo"</filename>.
1289 And, to create a match, that string must appear in the
1290 whitelist.
1291 </para>
1292
1293 <para>
1294 Judicious use of the <filename>LICENSE_FLAGS</filename>
1295 strings and the contents of the
1296 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
1297 allows you a lot of flexibility for including or excluding
1298 recipes based on licensing.
1299 For example, you can broaden the matching capabilities by
1300 using license flags string subsets in the whitelist.
1301 <note>When using a string subset, be sure to use the part of
1302 the expanded string that precedes the appended underscore
1303 character (e.g. <filename>usethispart_1.3</filename>,
1304 <filename>usethispart_1.4</filename>, and so forth).
1305 </note>
1306 For example, simply specifying the string "commercial" in
1307 the whitelist matches any expanded
1308 <filename>LICENSE_FLAGS</filename> definition that starts with
1309 the string "commercial" such as "commercial_foo" and
1310 "commercial_bar", which are the strings the build system
1311 automatically generates for hypothetical recipes named
1312 "foo" and "bar" assuming those recipes simply specify the
1313 following:
1314 <literallayout class='monospaced'>
1315 LICENSE_FLAGS = "commercial"
1316 </literallayout>
1317 Thus, you can choose to exhaustively
1318 enumerate each license flag in the whitelist and
1319 allow only specific recipes into the image, or
1320 you can use a string subset that causes a broader range of
1321 matches to allow a range of recipes into the image.
1322 </para>
1323
1324 <para>
1325 This scheme works even if the
1326 <filename>LICENSE_FLAGS</filename> string already
1327 has <filename>_${PN}</filename> appended.
1328 For example, the build system turns the license flag
1329 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
1330 match both the general "commercial" and the specific
1331 "commercial_1.2_foo" strings found in the whitelist, as
1332 expected.
1333 </para>
1334
1335 <para>
1336 Here are some other scenarios:
1337 <itemizedlist>
1338 <listitem><para>You can specify a versioned string in the
1339 recipe such as "commercial_foo_1.2" in a "foo" recipe.
1340 The build system expands this string to
1341 "commercial_foo_1.2_foo".
1342 Combine this license flag with a whitelist that has
1343 the string "commercial" and you match the flag along
1344 with any other flag that starts with the string
1345 "commercial".</para></listitem>
1346 <listitem><para>Under the same circumstances, you can
1347 use "commercial_foo" in the whitelist and the
1348 build system not only matches "commercial_foo_1.2" but
1349 also matches any license flag with the string
1350 "commercial_foo", regardless of the version.
1351 </para></listitem>
1352 <listitem><para>You can be very specific and use both the
1353 package and version parts in the whitelist (e.g.
1354 "commercial_foo_1.2") to specifically match a
1355 versioned recipe.</para></listitem>
1356 </itemizedlist>
1357 </para>
1358 </section>
1359
1360 <section id="other-variables-related-to-commercial-licenses">
1361 <title>Other Variables Related to Commercial Licenses</title>
1362
1363 <para>
1364 Other helpful variables related to commercial
1365 license handling exist and are defined in the
1366 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
1367 <literallayout class='monospaced'>
1368 COMMERCIAL_AUDIO_PLUGINS ?= ""
1369 COMMERCIAL_VIDEO_PLUGINS ?= ""
1370 COMMERCIAL_QT = ""
1371 </literallayout>
1372 If you want to enable these components, you can do so by making sure you have
1373 statements similar to the following
1374 in your <filename>local.conf</filename> configuration file:
1375 <literallayout class='monospaced'>
1376 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
1377 gst-plugins-ugly-mpegaudioparse"
1378 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
1379 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
1380 COMMERCIAL_QT ?= "qmmp"
1381 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
1382 </literallayout>
1383 Of course, you could also create a matching whitelist
1384 for those components using the more general "commercial"
1385 in the whitelist, but that would also enable all the
1386 other packages with <filename>LICENSE_FLAGS</filename> containing
1387 "commercial", which you may or may not want:
1388 <literallayout class='monospaced'>
1389 LICENSE_FLAGS_WHITELIST = "commercial"
1390 </literallayout>
1391 </para>
1392
1393 <para>
1394 Specifying audio and video plug-ins as part of the
1395 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
1396 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
1397 or commercial Qt components as part of
1398 the <filename>COMMERCIAL_QT</filename> statement (along
1399 with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
1400 plug-ins or components into built images, thus adding
1401 support for media formats or components.
1402 </para>
1403 </section>
1404 </section>
1405</section>
1406</chapter>
1407<!--
1408vim: expandtab tw=80 ts=4
1409-->
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
new file mode 100644
index 0000000..a8a6f3b
--- /dev/null
+++ b/documentation/ref-manual/usingpoky.xml
@@ -0,0 +1,882 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='usingpoky'>
6<title>Using the Yocto Project</title>
7
8 <para>
9 This chapter describes common usage for the Yocto Project.
10 The information is introductory in nature as other manuals in the Yocto Project
11 documentation set provide more details on how to use the Yocto Project.
12 </para>
13
14<section id='usingpoky-build'>
15 <title>Running a Build</title>
16
17 <para>
18 This section provides a summary of the build process and provides information
19 for less obvious aspects of the build process.
20 For general information on how to build an image using the OpenEmbedded build
21 system, see the
22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
23 section of the Yocto Project Quick Start.
24 </para>
25
26 <section id='build-overview'>
27 <title>Build Overview</title>
28
29 <para>
30 The first thing you need to do is set up the OpenEmbedded build
31 environment by sourcing an environment setup script
32 (i.e.
33 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
34 or
35 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
36 Here is an example:
37 <literallayout class='monospaced'>
38 $ source &OE_INIT_FILE; [&lt;build_dir&gt;]
39 </literallayout>
40 </para>
41
42 <para>
43 The <filename>build_dir</filename> argument is optional and specifies the directory the
44 OpenEmbedded build system uses for the build -
45 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
46 If you do not specify a Build Directory, it defaults to a directory
47 named <filename>build</filename> in your current working directory.
48 A common practice is to use a different Build Directory for different targets.
49 For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
50 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
51 </para>
52
53 <para>
54 Once the build environment is set up, you can build a target using:
55 <literallayout class='monospaced'>
56 $ bitbake &lt;target&gt;
57 </literallayout>
58 </para>
59
60 <para>
61 The <filename>target</filename> is the name of the recipe you want to build.
62 Common targets are the images in <filename>meta/recipes-core/images</filename>,
63 <filename>meta/recipes-sato/images</filename>, etc. all found in the
64 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
65 Or, the target can be the name of a recipe for a specific piece of software such as
66 BusyBox.
67 For more details about the images the OpenEmbedded build system supports, see the
68 "<link linkend="ref-images">Images</link>" chapter.
69 </para>
70
71 <note>
72 Building an image without GNU General Public License Version 3 (GPLv3) components
73 is supported for only minimal and base images.
74 See the "<link linkend='ref-images'>Images</link>" chapter for more information.
75 </note>
76 </section>
77
78 <section id='building-an-image-using-gpl-components'>
79 <title>Building an Image Using GPL Components</title>
80
81 <para>
82 When building an image using GPL components, you need to maintain your original
83 settings and not switch back and forth applying different versions of the GNU
84 General Public License.
85 If you rebuild using different versions of GPL, dependency errors might occur
86 due to some components not being rebuilt.
87 </para>
88 </section>
89</section>
90
91<section id='usingpoky-install'>
92 <title>Installing and Using the Result</title>
93
94 <para>
95 Once an image has been built, it often needs to be installed.
96 The images and kernels built by the OpenEmbedded build system are placed in the
97 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
98 <filename class="directory">tmp/deploy/images</filename>.
99 For information on how to run pre-built images such as <filename>qemux86</filename>
100 and <filename>qemuarm</filename>, see the
101 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
102 section in the Yocto Project Quick Start.
103 For information about how to install these images, see the documentation for your
104 particular board or machine.
105 </para>
106</section>
107
108<section id='usingpoky-debugging'>
109 <title>Debugging Build Failures</title>
110
111 <para>
112 The exact method for debugging build failures depends on the nature of
113 the problem and on the system's area from which the bug originates.
114 Standard debugging practices such as comparison against the last
115 known working version with examination of the changes and the
116 re-application of steps to identify the one causing the problem are
117 valid for the Yocto Project just as they are for any other system.
118 Even though it is impossible to detail every possible potential failure,
119 this section provides some general tips to aid in debugging.
120 </para>
121
122 <para>
123 A useful feature for debugging is the error reporting tool.
124 Configuring the Yocto Project to use this tool causes the
125 OpenEmbedded build system to produce error reporting commands as
126 part of the console output.
127 You can enter the commands after the build completes
128 to log error information
129 into a common database, that can help you figure out what might be
130 going wrong.
131 For information on how to enable and use this feature, see the
132 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>Using the Error Reporting Tool</ulink>"
133 section in the Yocto Project Development Manual.
134 </para>
135
136 <para>
137 For discussions on debugging, see the
138 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
139 and
140 "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working within Eclipse</ulink>"
141 sections in the Yocto Project Development Manual.
142 </para>
143
144 <note>
145 The remainder of this section presents many examples of the
146 <filename>bitbake</filename> command.
147 You can learn about BitBake by reading the
148 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
149 </note>
150
151
152 <section id='usingpoky-debugging-taskfailures'>
153 <title>Task Failures</title>
154
155 <para>The log file for shell tasks is available in
156 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
157 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
158 machine (<filename>qemux86</filename>) might be
159 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>.
160 To see what
161 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
162 runs to generate that log, look at the corresponding
163 <filename>run.do_taskname.pid</filename> file located in the same directory.
164 </para>
165
166 <para>
167 Presently, the output from Python tasks is sent directly to the console.
168 </para>
169 </section>
170
171 <section id='usingpoky-debugging-taskrunning'>
172 <title>Running Specific Tasks</title>
173
174 <para>
175 Any given package consists of a set of tasks.
176 The standard BitBake behavior in most cases is: <filename>fetch</filename>,
177 <filename>unpack</filename>,
178 <filename>patch</filename>, <filename>configure</filename>,
179 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
180 <filename>package_write</filename>, and <filename>build</filename>.
181 The default task is <filename>build</filename> and any tasks on which it depends
182 build first.
183 Some tasks, such as <filename>devshell</filename>, are not part of the
184 default build chain.
185 If you wish to run a task that is not part of the default build chain, you can use the
186 <filename>-c</filename> option in BitBake.
187 Here is an example:
188 <literallayout class='monospaced'>
189 $ bitbake matchbox-desktop -c devshell
190 </literallayout>
191 </para>
192
193 <para>
194 If you wish to rerun a task, use the <filename>-f</filename> force
195 option.
196 For example, the following sequence forces recompilation after
197 changing files in the work directory.
198 <literallayout class='monospaced'>
199 $ bitbake matchbox-desktop
200 .
201 .
202 [make some changes to the source code in the work directory]
203 .
204 .
205 $ bitbake matchbox-desktop -c compile -f
206 $ bitbake matchbox-desktop
207 </literallayout>
208 </para>
209
210 <para>
211 This sequence first builds and then recompiles
212 <filename>matchbox-desktop</filename>.
213 The last command reruns all tasks (basically the packaging tasks) after the compile.
214 BitBake recognizes that the <filename>compile</filename> task was rerun and therefore
215 understands that the other tasks also need to be run again.
216 </para>
217
218 <para>
219 You can view a list of tasks in a given package by running the
220 <filename>listtasks</filename> task as follows:
221 <literallayout class='monospaced'>
222 $ bitbake matchbox-desktop -c listtasks
223 </literallayout>
224 The results appear as output to the console and are also in the
225 file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
226 </para>
227 </section>
228
229 <section id='usingpoky-debugging-dependencies'>
230 <title>Dependency Graphs</title>
231
232 <para>
233 Sometimes it can be hard to see why BitBake wants to build
234 other packages before building a given package you have specified.
235 The <filename>bitbake -g &lt;targetname&gt;</filename> command
236 creates the <filename>pn-buildlist</filename>,
237 <filename>pn-depends.dot</filename>,
238 <filename>package-depends.dot</filename>, and
239 <filename>task-depends.dot</filename> files in the current
240 directory.
241 These files show what will be built and the package and task
242 dependencies, which are useful for debugging problems.
243 You can use the
244 <filename>bitbake -g -u depexp &lt;targetname&gt;</filename>
245 command to display the results in a more human-readable form.
246 </para>
247 </section>
248
249 <section id='usingpoky-debugging-bitbake'>
250 <title>General BitBake Problems</title>
251
252 <para>
253 You can see debug output from BitBake by using the <filename>-D</filename> option.
254 The debug output gives more information about what BitBake
255 is doing and the reason behind it.
256 Each <filename>-D</filename> option you use increases the logging level.
257 The most common usage is <filename>-DDD</filename>.
258 </para>
259
260 <para>
261 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
262 BitBake chose a certain version of a package or why BitBake
263 picked a certain provider.
264 This command could also help you in a situation where you think BitBake did something
265 unexpected.
266 </para>
267 </section>
268
269 <section id='development-host-system-issues'>
270 <title>Development Host System Issues</title>
271
272 <para>
273 Sometimes issues on the host development system can cause your
274 build to fail.
275 Following are known, host-specific problems.
276 Be sure to always consult the
277 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
278 for a look at all release-related issues.
279 <itemizedlist>
280 <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>:
281 If your development host system has the unpatched
282 <filename>GNU Make 3.82</filename>,
283 the <filename>do_install</filename> task
284 fails for <filename>eglibc-initial</filename> during the
285 build.</para>
286 <para>Typically, every distribution that ships
287 <filename>GNU Make 3.82</filename> as
288 the default already has the patched version.
289 However, some distributions, such as Debian, have
290 <filename>GNU Make 3.82</filename> as an option, which
291 is unpatched.
292 You will see this error on these types of distributions.
293 Switch to <filename>GNU Make 3.81</filename> or patch
294 your <filename>make</filename> to solve the problem.
295 </para></listitem>
296 </itemizedlist>
297 </para>
298 </section>
299
300 <section id='usingpoky-debugging-buildfile'>
301 <title>Building with No Dependencies</title>
302 <para>
303 To build a specific recipe (<filename>.bb</filename> file),
304 you can use the following command form:
305 <literallayout class='monospaced'>
306 $ bitbake -b &lt;somepath/somerecipe.bb&gt;
307 </literallayout>
308 This command form does not check for dependencies.
309 Consequently, you should use it
310 only when you know existing dependencies have been met.
311 <note>
312 You can also specify fragments of the filename.
313 In this case, BitBake checks for a unique match.
314 </note>
315 </para>
316 </section>
317
318 <section id='usingpoky-debugging-variables'>
319 <title>Variables</title>
320 <para>
321 You can use the <filename>-e</filename> BitBake option to
322 display the parsing environment for a configuration.
323 The following displays the general parsing environment:
324 <literallayout class='monospaced'>
325 $ bitbake -e
326 </literallayout>
327 This next example shows the parsing environment for a specific
328 recipe:
329 <literallayout class='monospaced'>
330 $ bitbake -e &lt;recipename&gt;
331 </literallayout>
332 </para>
333 </section>
334
335 <section id='recipe-logging-mechanisms'>
336 <title>Recipe Logging Mechanisms</title>
337 <para>
338 Best practices exist while writing recipes that both log build progress and
339 act on build conditions such as warnings and errors.
340 Both Python and Bash language bindings exist for the logging mechanism:
341 <itemizedlist>
342 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
343 supports several loglevels: <filename>bb.fatal</filename>,
344 <filename>bb.error</filename>, <filename>bb.warn</filename>,
345 <filename>bb.note</filename>, <filename>bb.plain</filename>,
346 and <filename>bb.debug</filename>.</para></listitem>
347 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
348 of loglevels exist and are accessed with a similar syntax:
349 <filename>bbfatal</filename>, <filename>bberror</filename>,
350 <filename>bbwarn</filename>, <filename>bbnote</filename>,
351 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
352 </itemizedlist>
353 </para>
354
355 <para>
356 For guidance on how logging is handled in both Python and Bash recipes, see the
357 <filename>logging.bbclass</filename> file in the
358 <filename>meta/classes</filename> folder of the
359 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
360 </para>
361
362 <section id='logging-with-python'>
363 <title>Logging With Python</title>
364 <para>
365 When creating recipes using Python and inserting code that handles build logs,
366 keep in mind the goal is to have informative logs while keeping the console as
367 "silent" as possible.
368 Also, if you want status messages in the log, use the "debug" loglevel.
369 </para>
370
371 <para>
372 Following is an example written in Python.
373 The code handles logging for a function that determines the number of tasks
374 needed to be run:
375 <literallayout class='monospaced'>
376 python do_listtasks() {
377 bb.debug(2, "Starting to figure out the task list")
378 if noteworthy_condition:
379 bb.note("There are 47 tasks to run")
380 bb.debug(2, "Got to point xyz")
381 if warning_trigger:
382 bb.warn("Detected warning_trigger, this might be a problem later.")
383 if recoverable_error:
384 bb.error("Hit recoverable_error, you really need to fix this!")
385 if fatal_error:
386 bb.fatal("fatal_error detected, unable to print the task list")
387 bb.plain("The tasks present are abc")
388 bb.debug(2, "Finished figuring out the tasklist")
389 }
390 </literallayout>
391 </para>
392 </section>
393
394 <section id='logging-with-bash'>
395 <title>Logging With Bash</title>
396 <para>
397 When creating recipes using Bash and inserting code that handles build
398 logs, you have the same goals - informative with minimal console output.
399 The syntax you use for recipes written in Bash is similar to that of
400 recipes written in Python described in the previous section.
401 </para>
402
403 <para>
404 Following is an example written in Bash.
405 The code logs the progress of the <filename>do_my_function</filename> function.
406 <literallayout class='monospaced'>
407 do_my_function() {
408 bbdebug 2 "Running do_my_function"
409 if [ exceptional_condition ]; then
410 bbnote "Hit exceptional_condition"
411 fi
412 bbdebug 2 "Got to point xyz"
413 if [ warning_trigger ]; then
414 bbwarn "Detected warning_trigger, this might cause a problem later."
415 fi
416 if [ recoverable_error ]; then
417 bberror "Hit recoverable_error, correcting"
418 fi
419 if [ fatal_error ]; then
420 bbfatal "fatal_error detected"
421 fi
422 bbdebug 2 "Completed do_my_function"
423 }
424 </literallayout>
425 </para>
426 </section>
427 </section>
428
429 <section id='usingpoky-debugging-others'>
430 <title>Other Tips</title>
431
432 <para>
433 Here are some other tips that you might find useful:
434 <itemizedlist>
435 <listitem><para>When adding new packages, it is worth watching for
436 undesirable items making their way into compiler command lines.
437 For example, you do not want references to local system files like
438 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
439 </para></listitem>
440 <listitem><para>If you want to remove the <filename>psplash</filename>
441 boot splashscreen,
442 add <filename>psplash=false</filename> to the kernel command line.
443 Doing so prevents <filename>psplash</filename> from loading
444 and thus allows you to see the console.
445 It is also possible to switch out of the splashscreen by
446 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
447 </para></listitem>
448 </itemizedlist>
449 </para>
450 </section>
451</section>
452
453<section id='maintaining-build-output-quality'>
454 <title>Maintaining Build Output Quality</title>
455
456 <para>
457 Many factors can influence the quality of a build.
458 For example, if you upgrade a recipe to use a new version of an upstream software
459 package or you experiment with some new configuration options, subtle changes
460 can occur that you might not detect until later.
461 Consider the case where your recipe is using a newer version of an upstream package.
462 In this case, a new version of a piece of software might introduce an optional
463 dependency on another library, which is auto-detected.
464 If that library has already been built when the software is building,
465 the software will link to the built library and that library will be pulled
466 into your image along with the new software even if you did not want the
467 library.
468 </para>
469
470 <para>
471 The
472 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
473 class exists to help you maintain
474 the quality of your build output.
475 You can use the class to highlight unexpected and possibly unwanted
476 changes in the build output.
477 When you enable build history, it records information about the contents of
478 each package and image and then commits that information to a local Git
479 repository where you can examine the information.
480 </para>
481
482 <para>
483 The remainder of this section describes the following:
484 <itemizedlist>
485 <listitem><para>How you can enable and disable
486 build history</para></listitem>
487 <listitem><para>How to understand what the build history contains
488 </para></listitem>
489 <listitem><para>How to limit the information used for build history
490 </para></listitem>
491 <listitem><para>How to examine the build history from both a
492 command-line and web interface</para></listitem>
493 </itemizedlist>
494 </para>
495
496 <section id='enabling-and-disabling-build-history'>
497 <title>Enabling and Disabling Build History</title>
498
499 <para>
500 Build history is disabled by default.
501 To enable it, add the following <filename>INHERIT</filename>
502 statement and set the
503 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
504 variable to "1" at the end of your
505 <filename>conf/local.conf</filename> file found in the
506 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
507 <literallayout class='monospaced'>
508 INHERIT += "buildhistory"
509 BUILDHISTORY_COMMIT = "1"
510 </literallayout>
511 Enabling build history as previously described
512 causes the build process to collect build
513 output information and commit it to a local
514 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
515 <note>
516 Enabling build history increases your build times slightly,
517 particularly for images, and increases the amount of disk
518 space used during the build.
519 </note>
520 </para>
521
522 <para>
523 You can disable build history by removing the previous statements
524 from your <filename>conf/local.conf</filename> file.
525 </para>
526 </section>
527
528 <section id='understanding-what-the-build-history-contains'>
529 <title>Understanding What the Build History Contains</title>
530
531 <para>
532 Build history information is kept in
533 <filename>$</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>/buildhistory</filename>
534 in the Build Directory as defined by the
535 <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link>
536 variable.
537 The following is an example abbreviated listing:
538 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
539 </para>
540
541 <para>
542 At the top level, there is a <filename>metadata-revs</filename> file
543 that lists the revisions of the repositories for the layers enabled
544 when the build was produced.
545 The rest of the data splits into separate
546 <filename>packages</filename>, <filename>images</filename> and
547 <filename>sdk</filename> directories, the contents of which are
548 described below.
549 </para>
550
551 <section id='build-history-package-information'>
552 <title>Build History Package Information</title>
553
554 <para>
555 The history for each package contains a text file that has
556 name-value pairs with information about the package.
557 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
558 contains the following:
559 <literallayout class='monospaced'>
560 PV = 1.19.3
561 PR = r3
562 RDEPENDS = update-rc.d eglibc (>= 2.13)
563 RRECOMMENDS = busybox-syslog busybox-udhcpc
564 PKGSIZE = 564701
565 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
566 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
567 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
568 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
569 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
570 </literallayout>
571 Most of these name-value pairs correspond to variables used
572 to produce the package.
573 The exceptions are <filename>FILELIST</filename>, which is the
574 actual list of files in the package, and
575 <filename>PKGSIZE</filename>, which is the total size of files
576 in the package in bytes.
577 </para>
578
579 <para>
580 There is also a file corresponding to the recipe from which the
581 package came (e.g.
582 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
583 <literallayout class='monospaced'>
584 PV = 1.19.3
585 PR = r3
586 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
587 virtual/libc update-rc.d-native
588 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
589 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
590 busybox-staticdev busybox-locale
591 </literallayout>
592 </para>
593
594 <para>
595 Finally, for those recipes fetched from a version control
596 system (e.g., Git), a file exists that lists source revisions
597 that are specified in the recipe and lists the actual revisions
598 used during the build.
599 Listed and actual revisions might differ when
600 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
601 is set to
602 <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>.
603 Here is an example assuming
604 <filename>buildhistory/packages/emenlow-poky-linux/linux-yocto/latest_srcrev</filename>):
605 <literallayout class='monospaced'>
606 # SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
607 SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
608 # SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
609 SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
610 # SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
611 SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
612 </literallayout>
613 You can use the <filename>buildhistory-collect-srcrevs</filename>
614 command to collect the stored <filename>SRCREV</filename> values
615 from build history and report them in a format suitable for use in
616 global configuration (e.g., <filename>local.conf</filename>
617 or a distro include file) to override floating
618 <filename>AUTOREV</filename> values to a fixed set of revisions.
619 Here is some example output from this command:
620 <literallayout class='monospaced'>
621 # emenlow-poky-linux
622 SRCREV_machine_pn-linux-yocto = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
623 SRCREV_emgd_pn-linux-yocto = "caea08c988e0f41103bbe18eafca20348f95da02"
624 SRCREV_meta_pn-linux-yocto = "c2ed0f16fdec628242a682897d5d86df4547cf24"
625 # core2-poky-linux
626 SRCREV_pn-kmod = "62081c0f68905b22f375156d4532fd37fa5c8d33"
627 SRCREV_pn-blktrace = "d6918c8832793b4205ed3bfede78c2f915c23385"
628 SRCREV_pn-opkg = "649"
629 </literallayout>
630 <note>
631 Here are some notes on using the
632 <filename>buildhistory-collect-srcrevs</filename> command:
633 <itemizedlist>
634 <listitem><para>By default, only values where the
635 <filename>SRCREV</filename> was
636 not hardcoded (usually when <filename>AUTOREV</filename>
637 was used) are reported.
638 Use the <filename>-a</filename> option to see all
639 <filename>SRCREV</filename> values.
640 </para></listitem>
641 <listitem><para>The output statements might not have any effect
642 if overrides are applied elsewhere in the build system
643 configuration.
644 Use the <filename>-f</filename> option to add the
645 <filename>forcevariable</filename> override to each output line
646 if you need to work around this restriction.
647 </para></listitem>
648 <listitem><para>The script does apply special handling when
649 building for multiple machines.
650 However, the script does place a
651 comment before each set of values that specifies
652 which triplet to which they belong as shown above
653 (e.g., <filename>emenlow-poky-linux</filename>).
654 </para></listitem>
655 </itemizedlist>
656 </note>
657 </para>
658 </section>
659
660 <section id='build-history-image-information'>
661 <title>Build History Image Information</title>
662
663 <para>
664 The files produced for each image are as follows:
665 <itemizedlist>
666 <listitem><para><filename>image-files:</filename>
667 A directory containing selected files from the root
668 filesystem.
669 The files are defined by
670 <link linkend='var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></link>.
671 </para></listitem>
672 <listitem><para><filename>build-id:</filename>
673 Human-readable information about the build configuration
674 and metadata source revisions.</para></listitem>
675 <listitem><para><filename>*.dot:</filename>
676 Dependency graphs for the image that are
677 compatible with <filename>graphviz</filename>.
678 </para></listitem>
679 <listitem><para><filename>files-in-image.txt:</filename>
680 A list of files in the image with permissions,
681 owner, group, size, and symlink information.
682 </para></listitem>
683 <listitem><para><filename>image-info.txt:</filename>
684 A text file containing name-value pairs with information
685 about the image.
686 See the following listing example for more information.
687 </para></listitem>
688 <listitem><para><filename>installed-package-names.txt:</filename>
689 A list of installed packages by name only.</para></listitem>
690 <listitem><para><filename>installed-package-sizes.txt:</filename>
691 A list of installed packages ordered by size.
692 </para></listitem>
693 <listitem><para><filename>installed-packages.txt:</filename>
694 A list of installed packages with full package
695 filenames.</para></listitem>
696 </itemizedlist>
697 <note>
698 Installed package information is able to be gathered and
699 produced even if package management is disabled for the final
700 image.
701 </note>
702 </para>
703
704 <para>
705 Here is an example of <filename>image-info.txt</filename>:
706 <literallayout class='monospaced'>
707 DISTRO = poky
708 DISTRO_VERSION = 1.1+snapshot-20120207
709 USER_CLASSES = image-mklibs image-prelink
710 IMAGE_CLASSES = image_types
711 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
712 package-management ssh-server-dropbear package-management
713 IMAGE_LINGUAS = en-us en-gb
714 IMAGE_INSTALL = task-core-boot task-base-extended
715 BAD_RECOMMENDATIONS =
716 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
717 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
718 IMAGESIZE = 171816
719 </literallayout>
720 Other than <filename>IMAGESIZE</filename>, which is the
721 total size of the files in the image in Kbytes, the
722 name-value pairs are variables that may have influenced the
723 content of the image.
724 This information is often useful when you are trying to determine
725 why a change in the package or file listings has occurred.
726 </para>
727 </section>
728
729 <section id='using-build-history-to-gather-image-information-only'>
730 <title>Using Build History to Gather Image Information Only</title>
731
732 <para>
733 As you can see, build history produces image information,
734 including dependency graphs, so you can see why something
735 was pulled into the image.
736 If you are just interested in this information and not
737 interested in collecting specific package or SDK information,
738 you can enable writing only image information without
739 any history by adding the following to your
740 <filename>conf/local.conf</filename> file found in the
741 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
742 <literallayout class='monospaced'>
743 INHERIT += "buildhistory"
744 BUILDHISTORY_COMMIT = "0"
745 BUILDHISTORY_FEATURES = "image"
746 </literallayout>
747 Here, you set the
748 <link linkend='var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></link>
749 variable to use the image feature only.
750 </para>
751 </section>
752
753 <section id='build-history-sdk-information'>
754 <title>Build History SDK Information</title>
755 <para>
756 Build history collects similar information on the contents
757 of SDKs (e.g. <filename>meta-toolchain</filename>
758 or <filename>bitbake -c populate_sdk imagename</filename>)
759 as compared to information it collects for images.
760 The following list shows the files produced for each SDK:
761 <itemizedlist>
762 <listitem><para><filename>files-in-sdk.txt:</filename>
763 A list of files in the SDK with permissions,
764 owner, group, size, and symlink information.
765 This list includes both the host and target parts
766 of the SDK.
767 </para></listitem>
768 <listitem><para><filename>sdk-info.txt:</filename>
769 A text file containing name-value pairs with information
770 about the SDK.
771 See the following listing example for more information.
772 </para></listitem>
773 <listitem><para>The following information appears under
774 each of the <filename>host</filename>
775 and <filename>target</filename> directories
776 for the portions of the SDK that run on the host and
777 on the target, respectively:
778 <itemizedlist>
779 <listitem><para><filename>depends.dot:</filename>
780 Dependency graph for the SDK that is
781 compatible with <filename>graphviz</filename>.
782 </para></listitem>
783 <listitem><para><filename>installed-package-names.txt:</filename>
784 A list of installed packages by name only.
785 </para></listitem>
786 <listitem><para><filename>installed-package-sizes.txt:</filename>
787 A list of installed packages ordered by size.
788 </para></listitem>
789 <listitem><para><filename>installed-packages.txt:</filename>
790 A list of installed packages with full package
791 filenames.</para></listitem>
792 </itemizedlist>
793 </para></listitem>
794 </itemizedlist>
795 </para>
796
797 <para>
798 Here is an example of <filename>sdk-info.txt</filename>:
799 <literallayout class='monospaced'>
800 DISTRO = poky
801 DISTRO_VERSION = 1.3+snapshot-20130327
802 SDK_NAME = poky-eglibc-i686-arm
803 SDK_VERSION = 1.3+snapshot
804 SDKMACHINE =
805 SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
806 BAD_RECOMMENDATIONS =
807 SDKSIZE = 352712
808 </literallayout>
809 Other than <filename>SDKSIZE</filename>, which is the
810 total size of the files in the SDK in Kbytes, the
811 name-value pairs are variables that might have influenced the
812 content of the SDK.
813 This information is often useful when you are trying to
814 determine why a change in the package or file listings
815 has occurred.
816 </para>
817 </section>
818
819 <section id='examining-build-history-information'>
820 <title>Examining Build History Information</title>
821
822 <para>
823 You can examine build history output from the command line or
824 from a web interface.
825 </para>
826
827 <para>
828 To see any changes that have occurred (assuming you have
829 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT = "1"</filename></link>),
830 you can simply
831 use any Git command that allows you to view the history of
832 a repository.
833 Here is one method:
834 <literallayout class='monospaced'>
835 $ git log -p
836 </literallayout>
837 You need to realize, however, that this method does show
838 changes that are not significant (e.g. a package's size
839 changing by a few bytes).
840 </para>
841
842 <para>
843 A command-line tool called <filename>buildhistory-diff</filename>
844 does exist, though, that queries the Git repository and prints just
845 the differences that might be significant in human-readable form.
846 Here is an example:
847 <literallayout class='monospaced'>
848 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
849 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
850 /etc/anotherpkg.conf was added
851 /sbin/anotherpkg was added
852 * (installed-package-names.txt):
853 * anotherpkg was added
854 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
855 anotherpkg was added
856 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
857 * PR changed from "r0" to "r1"
858 * PV changed from "0.1.10" to "0.1.12"
859 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
860 * PR changed from "r0" to "r1"
861 * PV changed from "0.1.10" to "0.1.12"
862 </literallayout>
863 </para>
864
865 <para>
866 To see changes to the build history using a web interface, follow
867 the instruction in the <filename>README</filename> file here.
868 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
869 </para>
870
871 <para>
872 Here is a sample screenshot of the interface:
873 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
874 </para>
875 </section>
876 </section>
877</section>
878
879</chapter>
880<!--
881vim: expandtab tw=80 ts=4
882-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-07 21:41:47 +0000