summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorAdrian Dudau <adrian.dudau@enea.com>2014-06-26 14:38:37 +0200
committerAdrian Dudau <adrian.dudau@enea.com>2014-06-26 14:38:37 +0200
commit067445c1487c1a73e0ee8a9ae3e82d446406ab57 (patch)
treed47aa232ce1c82cf47aa348f20902937e073239a /documentation/ref-manual
downloadyocto-docs-daisy.tar.gz
initial commit for Enea Linux 4.0daisy
Migrated from the internal git server on the daisy-enea branch Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/TODO11
-rw-r--r--documentation/ref-manual/closer-look.xml1304
-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.xml690
-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.xml560
-rw-r--r--documentation/ref-manual/migration.xml1697
-rw-r--r--documentation/ref-manual/ref-bitbake.xml472
-rw-r--r--documentation/ref-manual/ref-classes.xml3300
-rw-r--r--documentation/ref-manual/ref-features.xml346
-rw-r--r--documentation/ref-manual/ref-images.xml166
-rw-r--r--documentation/ref-manual/ref-manual-customization.xsl20
-rw-r--r--documentation/ref-manual/ref-manual-eclipse-customization.xsl27
-rw-r--r--documentation/ref-manual/ref-manual.xml150
-rw-r--r--documentation/ref-manual/ref-qa-checks.xml1151
-rw-r--r--documentation/ref-manual/ref-structure.xml1130
-rw-r--r--documentation/ref-manual/ref-style.css985
-rw-r--r--documentation/ref-manual/ref-tasks.xml684
-rw-r--r--documentation/ref-manual/ref-variables.xml9714
-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.xml1419
-rw-r--r--documentation/ref-manual/usingpoky.xml891
43 files changed, 25103 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..f0ed967
--- /dev/null
+++ b/documentation/ref-manual/closer-look.xml
@@ -0,0 +1,1304 @@
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
572 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
573 task inside BitBake uses
574 the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
575 variable and the argument's prefix to determine the correct
576 fetcher module.
577 </para>
578
579 <note>
580 For information on how to have the OpenEmbedded build system
581 generate tarballs for Git repositories and place them in the
582 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
583 directory, see the
584 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
585 variable.
586 </note>
587
588 <para>
589 When fetching a repository, BitBake uses the
590 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
591 variable to determine the specific revision from which to
592 build.
593 </para>
594 </section>
595
596 <section id='source-mirrors'>
597 <title>Source Mirror(s)</title>
598
599 <para>
600 Two kinds of mirrors exist: pre-mirrors and regular mirrors.
601 The <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
602 and
603 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
604 variables point to these, respectively.
605 BitBake checks pre-mirrors before looking upstream for any
606 source files.
607 Pre-mirrors are appropriate when you have a shared directory
608 that is not a directory defined by the
609 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
610 variable.
611 A Pre-mirror typically points to a shared directory that is
612 local to your organization.
613 </para>
614
615 <para>
616 Regular mirrors can be any site across the Internet that is
617 used as an alternative location for source code should the
618 primary site not be functioning for some reason or another.
619 </para>
620 </section>
621 </section>
622
623 <section id="package-feeds-dev-environment">
624 <title>Package Feeds</title>
625
626 <para>
627 When the OpenEmbedded build system generates an image or an SDK,
628 it gets the packages from a package feed area located in the
629 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
630 The
631 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
632 shows this package feeds area in the upper-right corner.
633 </para>
634
635 <para>
636 This section looks a little closer into the package feeds area used
637 by the build system.
638 Here is a more detailed look at the area:
639 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
640 </para>
641
642 <para>
643 Package feeds are an intermediary step in the build process.
644 BitBake generates packages whose types are defined by the
645 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
646 variable.
647 Before placing the packages into package feeds,
648 the build process validates them with generated output quality
649 assurance checks through the
650 <link linkend='ref-classes-insane'><filename>insane</filename></link>
651 class.
652 </para>
653
654 <para>
655 The package feed area resides in
656 <filename>tmp/deploy</filename> of the Build Directory.
657 Folders are created that correspond to the package type
658 (IPK, DEB, or RPM) created.
659 Further organization is derived through the value of the
660 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
661 variable for each package.
662 For example, packages can exist for the i586 or qemux86
663 architectures.
664 The package files themselves reside within the appropriate
665 architecture folder.
666 </para>
667
668 <para>
669 BitBake uses the <filename>do_package_write_*</filename> tasks to
670 place generated packages into the package holding area (e.g.
671 <filename>do_package_write_ipk</filename> for IPK packages).
672 See the
673 "<link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>",
674 "<link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>",
675 "<link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>",
676 and
677 "<link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>"
678 sections for additional information.
679 </para>
680 </section>
681
682 <section id='bitbake-dev-environment'>
683 <title>BitBake</title>
684
685 <para>
686 The OpenEmbedded build system uses
687 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
688 to produce images.
689 You can see from the
690 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
691 the BitBake area consists of several functional areas.
692 This section takes a closer look at each of those areas.
693 </para>
694
695 <para>
696 Separate documentation exists for the BitBake tool.
697 See the
698 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>
699 for reference material on BitBake.
700 </para>
701
702 <section id='source-fetching-dev-environment'>
703 <title>Source Fetching</title>
704
705 <para>
706 The first stages of building a recipe are to fetch and unpack
707 the source code:
708 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
709 </para>
710
711 <para>
712 The
713 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
714 and
715 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
716 tasks fetch the source files and unpack them into the work
717 directory.
718 <note>
719 For every local file (e.g. <filename>file://</filename>)
720 that is part of a recipe's
721 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
722 statement, the OpenEmbedded build system takes a checksum
723 of the file for the recipe and inserts the checksum into
724 the signature for the <filename>do_fetch</filename>.
725 If any local file has been modified, the
726 <filename>do_fetch</filename> task and all tasks that
727 depend on it are re-executed.
728 </note>
729 By default, everything is accomplished in the
730 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
731 which has a defined structure.
732 For additional general information on the Build Directory,
733 see the
734 "<link linkend='structure-core-build'><filename>build/</filename></link>"
735 section.
736 </para>
737
738 <para>
739 Unpacked source files are pointed to by the
740 <link linkend='var-S'><filename>S</filename></link> variable.
741 Each recipe has an area in the Build Directory where the
742 unpacked source code resides.
743 The name of that directory for any given recipe is defined from
744 several different variables.
745 You can see the variables that define these directories
746 by looking at the figure:
747 <itemizedlist>
748 <listitem><para><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> -
749 The base directory where the OpenEmbedded build system
750 performs all its work during the build.
751 </para></listitem>
752 <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link> -
753 The architecture of the built package or packages.
754 </para></listitem>
755 <listitem><para><link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link> -
756 The operating system of the target device.
757 </para></listitem>
758 <listitem><para><link linkend='var-PN'><filename>PN</filename></link> -
759 The name of the built package.
760 </para></listitem>
761 <listitem><para><link linkend='var-PV'><filename>PV</filename></link> -
762 The version of the recipe used to build the package.
763 </para></listitem>
764 <listitem><para><link linkend='var-PR'><filename>PR</filename></link> -
765 The revision of the recipe used to build the package.
766 </para></listitem>
767 <listitem><para><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> -
768 The location within <filename>TMPDIR</filename> where
769 a specific package is built.
770 </para></listitem>
771 <listitem><para><link linkend='var-S'><filename>S</filename></link> -
772 Contains the unpacked source files for a given recipe.
773 </para></listitem>
774 </itemizedlist>
775 </para>
776 </section>
777
778 <section id='patching-dev-environment'>
779 <title>Patching</title>
780
781 <para>
782 Once source code is fetched and unpacked, BitBake locates
783 patch files and applies them to the source files:
784 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
785 </para>
786
787 <para>
788 The
789 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
790 task processes recipes by
791 using the
792 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
793 variable to locate applicable patch files, which by default
794 are <filename>*.patch</filename> or
795 <filename>*.diff</filename> files, or any file if
796 "apply=yes" is specified for the file in
797 <filename>SRC_URI</filename>.
798 </para>
799
800 <para>
801 BitBake finds and applies multiple patches for a single recipe
802 in the order in which it finds the patches.
803 Patches are applied to the recipe's source files located in the
804 <link linkend='var-S'><filename>S</filename></link> directory.
805 </para>
806
807 <para>
808 For more information on how the source directories are
809 created, see the
810 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
811 section.
812 </para>
813 </section>
814
815 <section id='configuration-and-compilation-dev-environment'>
816 <title>Configuration and Compilation</title>
817
818 <para>
819 After source code is patched, BitBake executes tasks that
820 configure and compile the source code:
821 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
822 </para>
823
824 <para>
825 This step in the build process consists of three tasks:
826 <itemizedlist>
827 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
828 This task configures the source by enabling and
829 disabling any build-time and configuration options for
830 the software being built.
831 Configurations can come from the recipe itself as well
832 as from an inherited class.
833 Additionally, the software itself might configure itself
834 depending on the target for which it is being built.
835 </para>
836
837 <para>The configurations handled by the
838 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
839 task are specific
840 to source code configuration for the source code
841 being built by the recipe.</para>
842
843 <para>If you are using the
844 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
845 class,
846 you can add additional configuration options by using
847 the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
848 variable.
849 For information on how this variable works within
850 that class, see the
851 <filename>meta/classes/autotools.bbclass</filename> file.
852 </para></listitem>
853 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
854 Once a configuration task has been satisfied, BitBake
855 compiles the source using the
856 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
857 task.
858 Compilation occurs in the directory pointed to by the
859 <link linkend='var-B'><filename>B</filename></link>
860 variable.
861 Realize that the <filename>B</filename> directory is, by
862 default, the same as the
863 <link linkend='var-S'><filename>S</filename></link>
864 directory.</para></listitem>
865 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
866 Once compilation is done, BitBake executes the
867 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
868 task.
869 This task copies files from the <filename>B</filename>
870 directory and places them in a holding area pointed to
871 by the
872 <link linkend='var-D'><filename>D</filename></link>
873 variable.</para></listitem>
874 </itemizedlist>
875 </para>
876 </section>
877
878 <section id='package-splitting-dev-environment'>
879 <title>Package Splitting</title>
880
881 <para>
882 After source code is configured and compiled, the
883 OpenEmbedded build system analyzes
884 the results and splits the output into packages:
885 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
886 </para>
887
888 <para>
889 The
890 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
891 and
892 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
893 tasks combine to analyze
894 the files found in the
895 <link linkend='var-D'><filename>D</filename></link> directory
896 and split them into subsets based on available packages and
897 files.
898 The analyzing process involves the following as well as other
899 items: splitting out debugging symbols,
900 looking at shared library dependencies between packages,
901 and looking at package relationships.
902 The <filename>do_packagedata</filename> task creates package
903 metadata based on the analysis such that the
904 OpenEmbedded build system can generate the final packages.
905 Working, staged, and intermediate results of the analysis
906 and package splitting process use these areas:
907 <itemizedlist>
908 <listitem><para><link linkend='var-PKGD'><filename>PKGD</filename></link> -
909 The destination directory for packages before they are
910 split.
911 </para></listitem>
912 <listitem><para><link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> -
913 A shared, global-state directory that holds data
914 generated during the packaging process.
915 </para></listitem>
916 <listitem><para><link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link> -
917 A temporary work area used by the
918 <filename>do_package</filename> task.
919 </para></listitem>
920 <listitem><para><link linkend='var-PKGDEST'><filename>PKGDEST</filename></link> -
921 The parent directory for packages after they have
922 been split.
923 </para></listitem>
924 </itemizedlist>
925 The <link linkend='var-FILES'><filename>FILES</filename></link>
926 variable defines the files that go into each package in
927 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
928 If you want details on how this is accomplished, you can
929 look at the
930 <link linkend='ref-classes-package'><filename>package</filename></link>
931 class.
932 </para>
933
934 <para>
935 Depending on the type of packages being created (RPM, DEB, or
936 IPK), the <filename>do_package_write_*</filename> task
937 creates the actual packages and places them in the
938 Package Feed area, which is
939 <filename>${TMPDIR}/deploy</filename>.
940 You can see the
941 "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
942 section for more detail on that part of the build process.
943 <note>
944 Support for creating feeds directly from the
945 <filename>deploy/*</filename> directories does not exist.
946 Creating such feeds usually requires some kind of feed
947 maintenance mechanism that would upload the new packages
948 into an official package feed (e.g. the
949 Ångström distribution).
950 This functionality is highly distribution-specific
951 and thus is not provided out of the box.
952 </note>
953 </para>
954 </section>
955
956 <section id='image-generation-dev-environment'>
957 <title>Image Generation</title>
958
959 <para>
960 Once packages are split and stored in the Package Feeds area,
961 the OpenEmbedded build system uses BitBake to generate the
962 root filesystem image:
963 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
964 </para>
965
966 <para>
967 The image generation process consists of several stages and
968 depends on many variables.
969 The
970 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
971 task uses these key variables
972 to help create the list of packages to actually install:
973 <itemizedlist>
974 <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
975 Lists out the base set of packages to install from
976 the Package Feeds area.</para></listitem>
977 <listitem><para><link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>:
978 Specifies packages that should not be installed.
979 </para></listitem>
980 <listitem><para><link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
981 Specifies features to include in the image.
982 Most of these features map to additional packages for
983 installation.</para></listitem>
984 <listitem><para><link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>:
985 Specifies the package backend to use and consequently
986 helps determine where to locate packages within the
987 Package Feeds area.</para></listitem>
988 <listitem><para><link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>:
989 Determines the language(s) for which additional
990 language support packages are installed.
991 </para></listitem>
992 </itemizedlist>
993 </para>
994
995 <para>
996 Package installation is under control of the package manager
997 (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
998 not package management is enabled for the target.
999 At the end of the process, if package management is not
1000 enabled for the target, the package manager's data files
1001 are deleted from the root filesystem.
1002 </para>
1003
1004 <para>
1005 During image generation, the build system attempts to run
1006 all post-installation scripts.
1007 Any that fail to run on the build host are run on the
1008 target when the target system is first booted.
1009 If you are using a
1010 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
1011 all the post installation scripts must succeed during the
1012 package installation phase since the root filesystem is
1013 read-only.
1014 </para>
1015
1016 <para>
1017 During Optimization, optimizing processes are run across
1018 the image.
1019 These processes include <filename>mklibs</filename> and
1020 <filename>prelink</filename>.
1021 The <filename>mklibs</filename> process optimizes the size
1022 of the libraries.
1023 A <filename>prelink</filename> process optimizes the dynamic
1024 linking of shared libraries to reduce start up time of
1025 executables.
1026 </para>
1027
1028 <para>
1029 Along with writing out the root filesystem image, the
1030 <filename>do_rootfs</filename> task creates a manifest file
1031 (<filename>.manifest</filename>) in the same directory as
1032 the root filesystem image that lists out, line-by-line, the
1033 installed packages.
1034 This manifest file is useful for the
1035 <link linkend='ref-classes-testimage'><filename>testimage</filename></link>
1036 class, for example, to determine whether or not to run
1037 specific tests.
1038 See the
1039 <link linkend='var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></link>
1040 variable for additional information.
1041 </para>
1042
1043 <para>
1044 Part of the image generation process includes compressing the
1045 root filesystem image.
1046 Compression is accomplished through several optimization
1047 routines designed to reduce the overall size of the image.
1048 </para>
1049
1050 <para>
1051 After the root filesystem has been constructed, the image
1052 generation process turns everything into an image file or
1053 a set of image files.
1054 The formats used for the root filesystem depend on the
1055 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1056 variable.
1057 </para>
1058
1059 <note>
1060 The entire image generation process is run under Pseudo.
1061 Running under Pseudo ensures that the files in the root
1062 filesystem have correct ownership.
1063 </note>
1064 </section>
1065
1066 <section id='sdk-generation-dev-environment'>
1067 <title>SDK Generation</title>
1068
1069 <para>
1070 The OpenEmbedded build system uses BitBake to generate the
1071 Software Development Kit (SDK) installer script:
1072 <imagedata fileref="figures/sdk-generation.png" align="center" width="6in" depth="7in" />
1073 </para>
1074
1075 <note>
1076 For more information on the cross-development toolchain
1077 generation, see the
1078 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1079 section.
1080 For information on advantages gained when building a
1081 cross-development toolchain using the
1082 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1083 task, see the
1084 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
1085 section in the Yocto Project Application Developer's Guide.
1086 </note>
1087
1088 <para>
1089 Like image generation, the SDK script process consists of
1090 several stages and depends on many variables.
1091 The <filename>do_populate_sdk</filename> task uses these
1092 key variables to help create the list of packages to actually
1093 install.
1094 For information on the variables listed in the figure, see the
1095 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1096 section.
1097 </para>
1098
1099 <para>
1100 The <filename>do_populate_sdk</filename> task handles two
1101 parts: a target part and a host part.
1102 The target part is the part built for the target hardware and
1103 includes libraries and headers.
1104 The host part is the part of the SDK that runs on the
1105 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
1106 </para>
1107
1108 <para>
1109 Once both parts are constructed, the
1110 <filename>do_populate_sdk</filename> task performs some cleanup
1111 on both parts.
1112 After the cleanup, the task creates a cross-development
1113 environment setup script and any configuration files that
1114 might be needed.
1115 </para>
1116
1117 <para>
1118 The final output of the task is the Cross-development
1119 toolchain installation script (<filename>.sh</filename> file),
1120 which includes the environment setup script.
1121 </para>
1122 </section>
1123 </section>
1124
1125 <section id='images-dev-environment'>
1126 <title>Images</title>
1127
1128 <para>
1129 The images produced by the OpenEmbedded build system
1130 are compressed forms of the
1131 root filesystem that are ready to boot on a target device.
1132 You can see from the
1133 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1134 that BitBake output, in part, consists of images.
1135 This section is going to look more closely at this output:
1136 <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
1137 </para>
1138
1139 <para>
1140 For a list of example images that the Yocto Project provides,
1141 see the
1142 "<link linkend='ref-images'>Images</link>" chapter.
1143 </para>
1144
1145 <para>
1146 Images are written out to the
1147 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1148 inside the <filename>tmp/deploy/images/&lt;machine&gt;/</filename>
1149 folder as shown in the figure.
1150 This folder contains any files expected to be loaded on the
1151 target device.
1152 The
1153 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
1154 variable points to the <filename>deploy</filename> directory,
1155 while the
1156 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
1157 variable points to the appropriate directory containing images for
1158 the current configuration.
1159 <itemizedlist>
1160 <listitem><para><filename>&lt;kernel-image&gt;</filename>:
1161 A kernel binary file.
1162 The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
1163 variable setting determines the naming scheme for the
1164 kernel image file.
1165 Depending on that variable, the file could begin with
1166 a variety of naming strings.
1167 The <filename>deploy/images/&lt;machine&gt;</filename>
1168 directory can contain multiple image files for the
1169 machine.</para></listitem>
1170 <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
1171 Root filesystems for the target device (e.g.
1172 <filename>*.ext3</filename> or <filename>*.bz2</filename>
1173 files).
1174 The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1175 variable setting determines the root filesystem image
1176 type.
1177 The <filename>deploy/images/&lt;machine&gt;</filename>
1178 directory can contain multiple root filesystems for the
1179 machine.</para></listitem>
1180 <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
1181 Tarballs that contain all the modules built for the kernel.
1182 Kernel module tarballs exist for legacy purposes and
1183 can be suppressed by setting the
1184 <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
1185 variable to "0".
1186 The <filename>deploy/images/&lt;machine&gt;</filename>
1187 directory can contain multiple kernel module tarballs
1188 for the machine.</para></listitem>
1189 <listitem><para><filename>&lt;bootloaders&gt;</filename>:
1190 Bootloaders supporting the image, if applicable to the
1191 target machine.
1192 The <filename>deploy/images/&lt;machine&gt;</filename>
1193 directory can contain multiple bootloaders for the
1194 machine.</para></listitem>
1195 <listitem><para><filename>&lt;symlinks&gt;</filename>:
1196 The <filename>deploy/images/&lt;machine&gt;</filename>
1197 folder contains
1198 a symbolic link that points to the most recently built file
1199 for each machine.
1200 These links might be useful for external scripts that
1201 need to obtain the latest version of each file.
1202 </para></listitem>
1203 </itemizedlist>
1204 </para>
1205 </section>
1206
1207 <section id='sdk-dev-environment'>
1208 <title>Application Development SDK</title>
1209
1210 <para>
1211 In the
1212 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
1213 the output labeled "Application Development SDK" represents an
1214 SDK.
1215 This section is going to take a closer look at this output:
1216 <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
1217 </para>
1218
1219 <para>
1220 The specific form of this output is a self-extracting
1221 SDK installer (<filename>*.sh</filename>) that, when run,
1222 installs the SDK, which consists of a cross-development
1223 toolchain, a set of libraries and headers, and an SDK
1224 environment setup script.
1225 Running this installer essentially sets up your
1226 cross-development environment.
1227 You can think of the cross-toolchain as the "host"
1228 part because it runs on the SDK machine.
1229 You can think of the libraries and headers as the "target"
1230 part because they are built for the target hardware.
1231 The setup script is added so that you can initialize the
1232 environment before using the tools.
1233 </para>
1234
1235 <note>
1236 <para>
1237 The Yocto Project supports several methods by which you can
1238 set up this cross-development environment.
1239 These methods include downloading pre-built SDK installers,
1240 building and installing your own SDK installer, or running
1241 an Application Development Toolkit (ADT) installer to
1242 install not just cross-development toolchains
1243 but also additional tools to help in this type of
1244 development.
1245 </para>
1246
1247 <para>
1248 For background information on cross-development toolchains
1249 in the Yocto Project development environment, see the
1250 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1251 section.
1252 For information on setting up a cross-development
1253 environment, see the
1254 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
1255 section in the Yocto Project Application Developer's Guide.
1256 </para>
1257 </note>
1258
1259 <para>
1260 Once built, the SDK installers are written out to the
1261 <filename>deploy/sdk</filename> folder inside the
1262 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1263 as shown in the figure at the beginning of this section.
1264 Several variables exist that help configure these files:
1265 <itemizedlist>
1266 <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
1267 Points to the <filename>deploy</filename>
1268 directory.</para></listitem>
1269 <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
1270 Specifies the architecture of the machine
1271 on which the cross-development tools are run to
1272 create packages for the target hardware.
1273 </para></listitem>
1274 <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
1275 Lists the features to include in the "target" part
1276 of the SDK.
1277 </para></listitem>
1278 <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
1279 Lists packages that make up the host
1280 part of the SDK (i.e. the part that runs on
1281 the <filename>SDKMACHINE</filename>).
1282 When you use
1283 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
1284 to create the SDK, a set of default packages
1285 apply.
1286 This variable allows you to add more packages.
1287 </para></listitem>
1288 <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
1289 Lists packages that make up the target part
1290 of the SDK (i.e. the part built for the
1291 target hardware).
1292 </para></listitem>
1293 <listitem><para><link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>:
1294 Defines the default SDK installation path offered by the
1295 installation script.
1296 </para></listitem>
1297 </itemizedlist>
1298 </para>
1299 </section>
1300
1301</chapter>
1302<!--
1303vim: expandtab tw=80 ts=4
1304-->
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..bc147ce
--- /dev/null
+++ b/documentation/ref-manual/faq.xml
@@ -0,0 +1,690 @@
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 <note>
648 You can find more information on the
649 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
650 Wiki page.
651 </note>
652 </answer>
653 </qandaentry>
654
655 <qandaentry>
656 <question>
657 <para>
658 Can I get rid of build output so I can start over?
659 </para>
660 </question>
661 <answer>
662 <para>
663 Yes - you can easily do this.
664 When you use BitBake to build an image, all the build output
665 goes into the directory created when you run the
666 build environment setup script (i.e.
667 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
668 or
669 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
670 By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
671 is named <filename>build</filename> but can be named
672 anything you want.
673 </para>
674
675 <para>
676 Within the Build Directory, is the <filename>tmp</filename>
677 directory.
678 To remove all the build output yet preserve any source code or
679 downloaded files from previous builds, simply remove the
680 <filename>tmp</filename> directory.
681 </para>
682 </answer>
683 </qandaentry>
684
685
686</qandaset>
687</chapter>
688<!--
689vim: expandtab tw=80 ts=4
690-->
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..a61740d
--- /dev/null
+++ b/documentation/ref-manual/introduction.xml
@@ -0,0 +1,560 @@
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-tasks'>Tasks</link>:</emphasis>
73 Describes the tasks defined by the OpenEmbedded build system.
74 </para></listitem>
75 <listitem><para><emphasis>
76 <link linkend='ref-images'>Images</link>:</emphasis>
77 Describes the standard images that the Yocto Project supports.
78 </para></listitem>
79 <listitem><para><emphasis>
80 <link linkend='ref-features'>Features</link>:</emphasis>
81 Describes mechanisms for creating distribution, machine, and image
82 features during the build process using the OpenEmbedded build system.</para></listitem>
83 <listitem><para><emphasis>
84 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
85 Presents most variables used by the OpenEmbedded build system, which
86 uses BitBake.
87 Entries describe the function of the variable and how to apply them.
88 </para></listitem>
89 <listitem><para><emphasis>
90 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
91 Provides variable locality or context.</para></listitem>
92 <listitem><para><emphasis>
93 <link linkend='faq'>FAQ</link>:</emphasis>
94 Provides answers for commonly asked questions in the Yocto Project
95 development environment.</para></listitem>
96 <listitem><para><emphasis>
97 <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
98 Provides guidance on how you can contribute back to the Yocto
99 Project.</para></listitem>
100 </itemizedlist>
101 </para>
102</section>
103
104
105<section id='intro-requirements'>
106<title>System Requirements</title>
107 <para>
108 For general Yocto Project system requirements, see the
109 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
110 in the Yocto Project Quick Start.
111 The remainder of this section provides details on system requirements
112 not covered in the Yocto Project Quick Start.
113 </para>
114
115 <section id='detailed-supported-distros'>
116 <title>Supported Linux Distributions</title>
117
118 <para>
119 Currently, the Yocto Project is supported on the following
120 distributions:
121 <note>
122 <para>
123 Yocto Project releases are tested against the stable Linux
124 distributions in the following list.
125 The Yocto Project should work on other distributions but
126 validation is not performed against them.
127 </para>
128
129 <para>
130 In particular, the Yocto Project does not support
131 and currently has no plans to support
132 rolling-releases or development distributions due to their
133 constantly changing nature.
134 We welcome patches and bug reports, but keep in mind that
135 our priority is on the supported platforms listed below.
136 </para>
137
138 <para>
139 If you encounter problems, please go to
140 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
141 and submit a bug.
142 We are interested in hearing about your experience.
143 </para>
144 </note>
145 <itemizedlist>
146<!-- <listitem><para>Ubuntu 10.04</para></listitem>
147 <listitem><para>Ubuntu 11.10</para></listitem> -->
148 <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
149 <listitem><para>Ubuntu 13.10</para></listitem>
150 <listitem><para>Ubuntu 14.04 (LTS)</para></listitem>
151<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
152 <listitem><para>Fedora 17 (Spherical)</para></listitem> -->
153 <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
154 <listitem><para>Fedora release 20 (Heisenbug)</para></listitem>
155<!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem>
156 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
157 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
158 <listitem><para>CentOS release 6.3 (Final)</para></listitem> -->
159 <listitem><para>CentOS release 6.4</para></listitem>
160 <listitem><para>CentOS release 6.5</para></listitem>
161<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> -->
162 <listitem><para>Debian GNU/Linux 7.0 (Wheezy)</para></listitem>
163 <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
164 <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
165 <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
166 <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
167<!-- <listitem><para>openSUSE 11.4</para></listitem>
168 <listitem><para>openSUSE 12.1</para></listitem> -->
169 <listitem><para>openSUSE 12.2</para></listitem>
170 <listitem><para>openSUSE 12.3</para></listitem>
171 <listitem><para>openSUSE 13.1</para></listitem>
172 </itemizedlist>
173 </para>
174
175 <note>
176 While the Yocto Project Team attempts to ensure all Yocto Project
177 releases are one hundred percent compatible with each officially
178 supported Linux distribution, instances might exist where you
179 encounter a problem while using the Yocto Project on a specific
180 distribution.
181 For example, the CentOS 6.4 distribution does not include the
182 Gtk+ 2.20.0 and PyGtk 2.21.0 (or higher) packages, which are
183 required to run
184 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
185 </note>
186 </section>
187
188 <section id='required-packages-for-the-host-development-system'>
189 <title>Required Packages for the Host Development System</title>
190
191 <para>
192 The list of packages you need on the host development system can
193 be large when covering all build scenarios using the Yocto Project.
194 This section provides required packages according to
195 Linux distribution and function.
196 </para>
197
198 <section id='ubuntu-packages'>
199 <title>Ubuntu and Debian</title>
200
201 <para>
202 The following list shows the required packages by function
203 given a supported Ubuntu or Debian Linux distribution:
204 <itemizedlist>
205 <listitem><para><emphasis>Essentials:</emphasis>
206 Packages needed to build an image on a headless
207 system:
208 <literallayout class='monospaced'>
209 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
210 </literallayout></para></listitem>
211 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
212 Packages recommended if the host system has graphics
213 support or if you are going to use the Eclipse
214 IDE:
215 <literallayout class='monospaced'>
216 $ sudo apt-get install libsdl1.2-dev xterm
217 </literallayout></para></listitem>
218 <listitem><para><emphasis>Documentation:</emphasis>
219 Packages needed if you are going to build out the
220 Yocto Project documentation manuals:
221 <literallayout class='monospaced'>
222 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
223 </literallayout></para></listitem>
224 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
225 Packages needed if you are going to be using the
226 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
227 <literallayout class='monospaced'>
228 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
229 </literallayout></para></listitem>
230 </itemizedlist>
231 </para>
232 </section>
233
234 <section id='fedora-packages'>
235 <title>Fedora Packages</title>
236
237 <para>
238 The following list shows the required packages by function
239 given a supported Fedora Linux distribution:
240 <itemizedlist>
241 <listitem><para><emphasis>Essentials:</emphasis>
242 Packages needed to build an image for a headless
243 system:
244 <literallayout class='monospaced'>
245 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
246 </literallayout></para></listitem>
247 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
248 Packages recommended if the host system has graphics
249 support or if you are going to use the Eclipse
250 IDE:
251 <literallayout class='monospaced'>
252 $ sudo yum install SDL-devel xterm perl-Thread-Queue
253 </literallayout></para></listitem>
254 <listitem><para><emphasis>Documentation:</emphasis>
255 Packages needed if you are going to build out the
256 Yocto Project documentation manuals:
257 <literallayout class='monospaced'>
258 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
259 docbook-dtds docbook-utils fop libxslt dblatex xmlto
260 </literallayout></para></listitem>
261 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
262 Packages needed if you are going to be using the
263 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
264 <literallayout class='monospaced'>
265 $ sudo yum install autoconf automake libtool glib2-devel
266 </literallayout></para></listitem>
267 </itemizedlist>
268 </para>
269 </section>
270
271 <section id='opensuse-packages'>
272 <title>openSUSE Packages</title>
273
274 <para>
275 The following list shows the required packages by function
276 given a supported openSUSE Linux distribution:
277 <itemizedlist>
278 <listitem><para><emphasis>Essentials:</emphasis>
279 Packages needed to build an image for a headless
280 system:
281 <literallayout class='monospaced'>
282 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
283 </literallayout></para></listitem>
284 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
285 Packages recommended if the host system has graphics
286 support or if you are going to use the Eclipse
287 IDE:
288 <literallayout class='monospaced'>
289 $ sudo zypper install libSDL-devel xterm
290 </literallayout></para></listitem>
291 <listitem><para><emphasis>Documentation:</emphasis>
292 Packages needed if you are going to build out the
293 Yocto Project documentation manuals:
294 <literallayout class='monospaced'>
295 $ sudo zypper install make fop xsltproc dblatex xmlto
296 </literallayout></para></listitem>
297 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
298 Packages needed if you are going to be using the
299 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
300 <literallayout class='monospaced'>
301 $ sudo zypper install autoconf automake libtool glib2-devel
302 </literallayout></para></listitem>
303 </itemizedlist>
304 </para>
305 </section>
306
307 <section id='centos-packages'>
308 <title>CentOS Packages</title>
309
310 <para>
311 The following list shows the required packages by function
312 given a supported CentOS Linux distribution:
313 <note>Depending on the CentOS version you are using, other requirements
314 and dependencies might exist.
315 For details, you should look at the CentOS sections on the
316 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
317 wiki page.
318 </note>
319 <itemizedlist>
320 <listitem><para><emphasis>Essentials:</emphasis>
321 Packages needed to build an image for a headless
322 system:
323 <literallayout class='monospaced'>
324 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;
325 </literallayout></para></listitem>
326 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
327 Packages recommended if the host system has graphics
328 support or if you are going to use the Eclipse
329 IDE:
330 <literallayout class='monospaced'>
331 $ sudo yum install SDL-devel xterm
332 </literallayout></para></listitem>
333 <listitem><para><emphasis>Documentation:</emphasis>
334 Packages needed if you are going to build out the
335 Yocto Project documentation manuals:
336 <literallayout class='monospaced'>
337 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
338 docbook-dtds docbook-utils fop libxslt dblatex xmlto
339 </literallayout></para></listitem>
340 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
341 Packages needed if you are going to be using the
342 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
343 <literallayout class='monospaced'>
344 $ sudo yum install autoconf automake libtool glib2-devel
345 </literallayout></para></listitem>
346 </itemizedlist>
347 </para>
348 </section>
349 </section>
350
351 <section id='required-git-tar-and-python-versions'>
352 <title>Required Git, tar, and Python Versions</title>
353
354 <para>
355 In order to use the build system, your host development system
356 must meet the following version requirements for Git, tar, and
357 Python:
358 <itemizedlist>
359 <listitem><para>Git 1.7.5 or greater</para></listitem>
360 <listitem><para>tar 1.24 or greater</para></listitem>
361 <listitem><para>Python 2.7.3 or greater not including
362 Python 3.x, which is not supported.</para></listitem>
363 </itemizedlist>
364 </para>
365
366 <para>
367 If your host development system does not meet all these requirements,
368 you can resolve this by installing a <filename>buildtools</filename>
369 tarball that contains these tools.
370 You can get the tarball one of two ways: download a pre-built
371 tarball or use BitBake to build the tarball.
372 </para>
373
374 <section id='downloading-a-pre-built-buildtools-tarball'>
375 <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
376
377 <para>
378 Downloading and running a pre-built buildtools installer is
379 the easiest of the two methods by which you can get these tools:
380 <orderedlist>
381 <listitem><para>
382 Locate and download the <filename>*.sh</filename> at
383 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
384 </para></listitem>
385 <listitem><para>
386 Execute the installation script.
387 Here is an example:
388 <literallayout class='monospaced'>
389 $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
390 </literallayout>
391 During execution, a prompt appears that allows you to
392 choose the installation directory.
393 For example, you could choose the following:
394 <literallayout class='monospaced'>
395 /home/your-username/buildtools
396 </literallayout>
397 </para></listitem>
398 <listitem><para>
399 Source the tools environment setup script by using a
400 command like the following:
401 <literallayout class='monospaced'>
402 $ source /home/your-username/buildtools/environment-setup-i586-poky-linux
403 </literallayout>
404 Of course, you need to supply your installation directory and be
405 sure to use the right file (i.e. i585 or x86-64).
406 </para>
407 <para>
408 After you have sourced the setup script,
409 the tools are added to <filename>PATH</filename>
410 and any other environment variables required to run the
411 tools are initialized.
412 The results are working versions versions of Git, tar,
413 Python and <filename>chrpath</filename>.
414 </para></listitem>
415 </orderedlist>
416 </para>
417 </section>
418
419 <section id='building-your-own-buildtools-tarball'>
420 <title>Building Your Own <filename>buildtools</filename> Tarball</title>
421
422 <para>
423 Building and running your own buildtools installer applies
424 only when you have a build host that can already run BitBake.
425 In this case, you use that machine to build the
426 <filename>.sh</filename> file and then
427 take steps to transfer and run it on a
428 machine that does not meet the minimal Git, tar, and Python
429 requirements.
430 </para>
431
432 <para>
433 Here are the steps to take to build and run your own
434 buildtools installer:
435 <orderedlist>
436 <listitem><para>
437 On the machine that is able to run BitBake,
438 be sure you have set up your build environment with
439 the setup script
440 (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
441 or
442 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
443 </para></listitem>
444 <listitem><para>
445 Run the BitBake command to build the tarball:
446 <literallayout class='monospaced'>
447 $ bitbake buildtools-tarball
448 </literallayout>
449 <note>
450 The
451 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
452 variable in your <filename>local.conf</filename> file
453 determines whether you build tools for a 32-bit
454 or 64-bit system.
455 </note>
456 Once the build completes, you can find the
457 <filename>.sh</filename> file that installs
458 the tools in the <filename>tmp/deploy/sdk</filename>
459 subdirectory of the
460 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
461 The installer file has the string "buildtools"
462 in the name.
463 </para></listitem>
464 <listitem><para>
465 Transfer the <filename>.sh</filename> file from the
466 build host to the machine that does not meet the
467 Git, tar, or Python requirements.
468 </para></listitem>
469 <listitem><para>
470 On the machine that does not meet the requirements,
471 run the <filename>.sh</filename> file
472 to install the tools.
473 Here is an example:
474 <literallayout class='monospaced'>
475 $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
476 </literallayout>
477 During execution, a prompt appears that allows you to
478 choose the installation directory.
479 For example, you could choose the following:
480 <literallayout class='monospaced'>
481 /home/your-username/buildtools
482 </literallayout>
483 </para></listitem>
484 <listitem><para>
485 Source the tools environment setup script by using a
486 command like the following:
487 <literallayout class='monospaced'>
488 $ source /home/your-username/buildtools/environment-setup-i586-poky-linux
489 </literallayout>
490 Of course, you need to supply your installation directory and be
491 sure to use the right file (i.e. i585 or x86-64).
492 </para>
493 <para>
494 After you have sourced the setup script,
495 the tools are added to <filename>PATH</filename>
496 and any other environment variables required to run the
497 tools are initialized.
498 The results are working versions versions of Git, tar,
499 Python and <filename>chrpath</filename>.
500 </para></listitem>
501 </orderedlist>
502 </para>
503 </section>
504 </section>
505</section>
506
507<section id='intro-getit'>
508 <title>Obtaining the Yocto Project</title>
509 <para>
510 The Yocto Project development team makes the Yocto Project available through a number
511 of methods:
512 <itemizedlist>
513 <listitem><para><emphasis>Source Repositories:</emphasis>
514 Working from a copy of the upstream
515 <filename>poky</filename> repository is the
516 preferred method for obtaining and using a Yocto Project
517 release.
518 You can view the Yocto Project Source Repositories at
519 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
520 In particular, you can find the
521 <filename>poky</filename> repository at
522 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
523 </para></listitem>
524 <listitem><para><emphasis>Releases:</emphasis> Stable, tested
525 releases are available as tarballs through
526 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
527 <listitem><para><emphasis>Nightly Builds:</emphasis> These
528 tarball releases are available at
529 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
530 These builds include Yocto Project releases, meta-toolchain
531 tarball installation scripts, and experimental builds.
532 </para></listitem>
533 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can
534 find tarball releases of the Yocto Project and supported BSPs
535 at the
536 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
537 Along with these downloads, you can find lots of other
538 information at this site.
539 </para></listitem>
540 </itemizedlist>
541 </para>
542</section>
543
544<section id='intro-getit-dev'>
545 <title>Development Checkouts</title>
546 <para>
547 Development using the Yocto Project requires a local
548 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
549 You can set up the Source Directory by cloning a copy of the upstream
550 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> Git repository.
551 For information on how to do this, see the
552 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
553 section in the Yocto Project Development Manual.
554 </para>
555</section>
556
557</chapter>
558<!--
559vim: expandtab tw=80 ts=4
560-->
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
new file mode 100644
index 0000000..d51bc4d
--- /dev/null
+++ b/documentation/ref-manual/migration.xml
@@ -0,0 +1,1697 @@
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='general-migration-considerations'>
15 <title>General Migration Considerations</title>
16
17 <para>
18 Some considerations are not tied to a specific Yocto Project
19 release.
20 This section presents information you should consider when
21 migrating to any new Yocto Project release.
22 <itemizedlist>
23 <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
24 Issues could arise if you take older recipes that contain
25 customizations and simply copy them forward expecting them
26 to work after you migrate to new Yocto Project metadata.
27 For example, suppose you have a recipe in your layer that is
28 a customized version of a core recipe copied from the earlier
29 release, rather than through the use of an append file.
30 When you migrate to a newer version of Yocto Project, the
31 metadata (e.g. perhaps an include file used by the recipe)
32 could have changed in a way that would break the build.
33 Say, for example, a function is removed from an include file
34 and the customized recipe tries to call that function.
35 </para>
36
37 <para>You could "forward-port" all your customizations in your
38 recipe so that everything works for the new release.
39 However, this is not the optimal solution as you would have
40 to repeat this process with each new release if changes
41 occur that give rise to problems.</para>
42
43 <para>The better solution (where practical) is to use append
44 files (<filename>*.bbappend</filename>) to capture any
45 customizations you want to make to a recipe.
46 Doing so, isolates your changes from the main recipe making
47 them much more manageable.
48 However, sometimes it is not practical to use an append
49 file.
50 A good example of this is when introducing a newer or older
51 version of a recipe in another layer.</para>
52 </listitem>
53 <listitem><para><emphasis>Updating Append Files</emphasis>:
54 Since append files generally only contain your customizations,
55 they often do not need to be adjusted for new releases.
56 However, if the <filename>.bbappend</filename> file is
57 specific to a particular version of the recipe (i.e. its
58 name does not use the % wildcard) and the version of the
59 recipe to which it is appending has changed, then you will
60 at a minimum need to rename the append file to match the
61 name of the recipe file.
62 A mismatch between an append file and its corresponding
63 recipe file (<filename>.bb</filename>) will
64 trigger an error during parsing.</para>
65 <para>Depending on the type of customization the append file
66 applies, other incompatibilities might occur when you
67 upgrade.
68 For example, if your append file applies a patch and the
69 recipe to which it is appending is updated to a newer
70 version, the patch might no longer apply.
71 If this is the case and assuming the patch is still needed,
72 you must modify the patch file so that it does apply.
73 </para></listitem>
74 </itemizedlist>
75 </para>
76</section>
77
78<section id='moving-to-the-yocto-project-1.3-release'>
79 <title>Moving to the Yocto Project 1.3 Release</title>
80
81 <para>
82 This section provides migration information for moving to the
83 Yocto Project 1.3 Release from the prior release.
84 </para>
85
86 <section id='1.3-local-configuration'>
87 <title>Local Configuration</title>
88
89 <para>
90 Differences include changes for
91 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
92 and <filename>bblayers.conf</filename>.
93 </para>
94
95 <section id='migration-1.3-sstate-mirrors'>
96 <title>SSTATE_MIRRORS</title>
97
98 <para>
99 The shared state cache (sstate-cache), as pointed to by
100 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, by default
101 now has two-character subdirectories to prevent issues arising
102 from too many files in the same directory.
103 Also, native sstate-cache packages will go into a subdirectory named using
104 the distro ID string.
105 If you copy the newly structured sstate-cache to a mirror location
106 (either local or remote) and then point to it in
107 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
108 you need to append "PATH" to the end of the mirror URL so that
109 the path used by BitBake before the mirror substitution is
110 appended to the path used to access the mirror.
111 Here is an example:
112 <literallayout class='monospaced'>
113 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
114 </literallayout>
115 </para>
116 </section>
117
118 <section id='migration-1.3-bblayers-conf'>
119 <title>bblayers.conf</title>
120
121 <para>
122 The <filename>meta-yocto</filename> layer consists of two parts
123 that correspond to the Poky reference distribution and the
124 reference hardware Board Support Packages (BSPs), respectively:
125 <filename>meta-yocto</filename> and
126 <filename>meta-yocto-bsp</filename>.
127 When running BitBake or Hob for the first time after upgrading,
128 your <filename>conf/bblayers.conf</filename> file will be
129 updated to handle this change and you will be asked to
130 re-run or restart for the changes to take effect.
131 </para>
132 </section>
133 </section>
134
135 <section id='1.3-recipes'>
136 <title>Recipes</title>
137
138 <para>
139 Differences include changes for the following:
140 <itemizedlist>
141 <listitem><para>Python function whitespace</para></listitem>
142 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
143 <listitem><para><filename>nativesdk</filename></para></listitem>
144 <listitem><para>Task recipes</para></listitem>
145 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
146 <listitem><para>Removed recipes</para></listitem>
147 </itemizedlist>
148 </para>
149
150 <section id='migration-1.3-python-function-whitespace'>
151 <title>Python Function Whitespace</title>
152
153 <para>
154 All Python functions must now use four spaces for indentation.
155 Previously, an inconsistent mix of spaces and tabs existed,
156 which made extending these functions using
157 <filename>_append</filename> or <filename>_prepend</filename>
158 complicated given that Python treats whitespace as
159 syntactically significant.
160 If you are defining or extending any Python functions (e.g.
161 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
162 <filename>do_patch</filename> and so forth) in custom recipes
163 or classes, you need to ensure you are using consistent
164 four-space indentation.
165 </para>
166 </section>
167
168 <section id='migration-1.3-proto=-in-src-uri'>
169 <title>proto= in SRC_URI</title>
170
171 <para>
172 Any use of <filename>proto=</filename> in
173 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
174 needs to be changed to <filename>protocol=</filename>.
175 In particular, this applies to the following URIs:
176 <itemizedlist>
177 <listitem><para><filename>svn://</filename></para></listitem>
178 <listitem><para><filename>bzr://</filename></para></listitem>
179 <listitem><para><filename>hg://</filename></para></listitem>
180 <listitem><para><filename>osc://</filename></para></listitem>
181 </itemizedlist>
182 Other URIs were already using <filename>protocol=</filename>.
183 This change improves consistency.
184 </para>
185 </section>
186
187 <section id='migration-1.3-nativesdk'>
188 <title>nativesdk</title>
189
190 <para>
191 The suffix <filename>nativesdk</filename> is now implemented
192 as a prefix, which simplifies a lot of the packaging code for
193 <filename>nativesdk</filename> recipes.
194 All custom <filename>nativesdk</filename> recipes and any
195 references need to be updated to use
196 <filename>nativesdk-*</filename> instead of
197 <filename>*-nativesdk</filename>.
198 </para>
199 </section>
200
201 <section id='migration-1.3-task-recipes'>
202 <title>Task Recipes</title>
203
204 <para>
205 "Task" recipes are now known as "Package groups" and have
206 been renamed from <filename>task-*.bb</filename> to
207 <filename>packagegroup-*.bb</filename>.
208 Existing references to the previous <filename>task-*</filename>
209 names should work in most cases as there is an automatic
210 upgrade path for most packages.
211 However, you should update references in your own recipes and
212 configurations as they could be removed in future releases.
213 You should also rename any custom <filename>task-*</filename>
214 recipes to <filename>packagegroup-*</filename>, and change
215 them to inherit <filename>packagegroup</filename> instead of
216 <filename>task</filename>, as well as taking the opportunity
217 to remove anything now handled by
218 <filename>packagegroup.bbclass</filename>, such as providing
219 <filename>-dev</filename> and <filename>-dbg</filename>
220 packages, setting
221 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
222 and so forth.
223 See the
224 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
225 section for further details.
226 </para>
227 </section>
228
229 <section id='migration-1.3-image-features'>
230 <title>IMAGE_FEATURES</title>
231
232 <para>
233 Image recipes that previously included "apps-console-core"
234 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
235 should now include "splash" instead to enable the boot-up
236 splash screen.
237 Retaining "apps-console-core" will still include the splash
238 screen but generates a warning.
239 The "apps-x11-core" and "apps-x11-games"
240 <filename>IMAGE_FEATURES</filename> features have been removed.
241 </para>
242 </section>
243
244 <section id='migration-1.3-removed-recipes'>
245 <title>Removed Recipes</title>
246
247 <para>
248 The following recipes have been removed.
249 For most of them, it is unlikely that you would have any
250 references to them in your own
251 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>.
252 However, you should check your metadata against this list to be sure:
253 <itemizedlist>
254 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
255 Replaced by <filename>libx11</filename>, which has a negligible
256 size difference with modern Xorg.</para></listitem>
257 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
258 Use <filename>xserver-xorg</filename>, which has a negligible
259 size difference when DRI and GLX modules are not installed.</para></listitem>
260 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
261 Effectively unmaintained for many years.</para></listitem>
262 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
263 No longer serves any purpose.</para></listitem>
264 <listitem><para><emphasis><filename>galago</filename></emphasis>:
265 Replaced by telepathy.</para></listitem>
266 <listitem><para><emphasis><filename>gail</filename></emphasis>:
267 Functionality was integrated into GTK+ 2.13.</para></listitem>
268 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
269 No longer needed.</para></listitem>
270 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
271 The build has been restructured to avoid the need for
272 this step.</para></listitem>
273 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
274 Unmaintained for many years.
275 Functionality now provided by
276 <filename>ofono</filename> instead.</para></listitem>
277 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
278 Largely unmaintained PIM application suite.
279 It has been moved to <filename>meta-gnome</filename>
280 in <filename>meta-openembedded</filename>.</para></listitem>
281 </itemizedlist>
282 In addition to the previously listed changes, the
283 <filename>meta-demoapps</filename> directory has also been removed
284 because the recipes in it were not being maintained and many
285 had become obsolete or broken.
286 Additionally, these recipes were not parsed in the default configuration.
287 Many of these recipes are already provided in an updated and
288 maintained form within the OpenEmbedded community layers such as
289 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
290 For the remainder, you can now find them in the
291 <filename>meta-extras</filename> repository, which is in the
292 Yocto Project
293 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>.
294 </para>
295 </section>
296 </section>
297
298 <section id='1.3-linux-kernel-naming'>
299 <title>Linux Kernel Naming</title>
300
301 <para>
302 The naming scheme for kernel output binaries has been changed to
303 now include
304 <link linkend='var-PE'><filename>PE</filename></link> as part of the
305 filename:
306 <literallayout class='monospaced'>
307 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
308 </literallayout>
309 </para>
310
311 <para>
312 Because the <filename>PE</filename> variable is not set by default,
313 these binary files could result with names that include two dash
314 characters.
315 Here is an example:
316 <literallayout class='monospaced'>
317 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
318 </literallayout>
319 </para>
320 </section>
321</section>
322
323<section id='moving-to-the-yocto-project-1.4-release'>
324 <title>Moving to the Yocto Project 1.4 Release</title>
325
326 <para>
327 This section provides migration information for moving to the
328 Yocto Project 1.4 Release from the prior release.
329 </para>
330
331 <section id='migration-1.4-bitbake'>
332 <title>BitBake</title>
333
334 <para>
335 Differences include the following:
336 <itemizedlist>
337 <listitem><para><emphasis>Comment Continuation:</emphasis>
338 If a comment ends with a line continuation (\) character,
339 then the next line must also be a comment.
340 Any instance where this is not the case, now triggers
341 a warning.
342 You must either remove the continuation character, or be
343 sure the next line is a comment.
344 </para></listitem>
345 <listitem><para><emphasis>Package Name Overrides:</emphasis>
346 The runtime package specific variables
347 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
348 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
349 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
350 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
351 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
352 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
353 <link linkend='var-FILES'><filename>FILES</filename></link>,
354 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
355 and the pre, post, install, and uninstall script functions
356 <filename>pkg_preinst</filename>,
357 <filename>pkg_postinst</filename>,
358 <filename>pkg_prerm</filename>, and
359 <filename>pkg_postrm</filename> should always have a
360 package name override.
361 For example, use <filename>RDEPENDS_${PN}</filename> for
362 the main package instead of <filename>RDEPENDS</filename>.
363 BitBake uses more strict checks when it parses recipes.
364 </para></listitem>
365 </itemizedlist>
366 </para>
367 </section>
368
369 <section id='migration-1.4-build-behavior'>
370 <title>Build Behavior</title>
371
372 <para>
373 Differences include the following:
374 <itemizedlist>
375 <listitem><para><emphasis>Shared State Code:</emphasis>
376 The shared state code has been optimized to avoid running
377 unnecessary tasks.
378 For example,
379 <filename>bitbake -c rootfs some-image</filename> from
380 shared state no longer populates the target sysroot
381 since that is not necessary.
382 Instead, the system just needs to extract the output
383 package contents, re-create the packages, and construct
384 the root filesystem.
385 This change is unlikely to cause any problems unless
386 you have missing declared dependencies.
387 </para></listitem>
388 <listitem><para><emphasis>Scanning Directory Names:</emphasis>
389 When scanning for files in
390 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
391 the build system now uses
392 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
393 instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
394 for the directory names.
395 In general, the values previously in
396 <filename>OVERRIDES</filename> are now in
397 <filename>FILESOVERRIDES</filename> as well.
398 However, if you relied upon an additional value
399 you previously added to <filename>OVERRIDES</filename>,
400 you might now need to add it to
401 <filename>FILESOVERRIDES</filename> unless you are already
402 adding it through the
403 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>
404 or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
405 variables, as appropriate.
406 For more related changes, see the
407 "<link linkend='migration-1.4-variables'>Variables</link>"
408 section.
409 </para></listitem>
410 </itemizedlist>
411 </para>
412 </section>
413
414
415 <section id='migration-1.4-proxies-and-fetching-source'>
416 <title>Proxies and Fetching Source</title>
417
418 <para>
419 A new <filename>oe-git-proxy</filename> script has been added to
420 replace previous methods of handling proxies and fetching source
421 from Git.
422 See the <filename>meta-yocto/conf/site.conf.sample</filename> file
423 for information on how to use this script.
424 </para>
425 </section>
426
427 <section id='migration-1.4-custom-interfaces-file-netbase-change'>
428 <title>Custom Interfaces File (netbase change)</title>
429
430 <para>
431 If you have created your own custom
432 <filename>etc/network/interfaces</filename> file by creating
433 an append file for the <filename>netbase</filename> recipe,
434 you now need to create an append file for the
435 <filename>init-ifupdown</filename> recipe instead, which you can
436 find in the
437 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
438 at <filename>meta/recipes-core/init-ifupdown</filename>.
439 For information on how to use append files, see the
440 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
441 in the Yocto Project Development Manual.
442 </para>
443 </section>
444
445 <section id='migration-1.4-remote-debugging'>
446 <title>Remote Debugging</title>
447
448 <para>
449 Support for remote debugging with the Eclipse IDE is now
450 separated into an image feature
451 (<filename>eclipse-debug</filename>) that corresponds to the
452 <filename>packagegroup-core-eclipse-debug</filename> package group.
453 Previously, the debugging feature was included through the
454 <filename>tools-debug</filename> image feature, which corresponds
455 to the <filename>packagegroup-core-tools-debug</filename>
456 package group.
457 </para>
458 </section>
459
460 <section id='migration-1.4-variables'>
461 <title>Variables</title>
462
463 <para>
464 The following variables have changed:
465 <itemizedlist>
466 <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
467 This variable now uses a distribution ID, which is composed
468 of the host distributor ID followed by the release.
469 Previously,
470 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
471 was composed of the description field.
472 For example, "Ubuntu 12.10" becomes "Ubuntu-12.10".
473 You do not need to worry about this change if you are not
474 specifically setting this variable, or if you are
475 specifically setting it to "".
476 </para></listitem>
477 <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
478 The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>,
479 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>,
480 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>,
481 and <filename>FILE_DIRNAME</filename> directories have been
482 dropped from the default value of the
483 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
484 variable, which is used as the search path for finding files
485 referred to in
486 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
487 If you have a recipe that relied upon these directories,
488 which would be unusual, then you will need to add the
489 appropriate paths within the recipe or, alternatively,
490 rearrange the files.
491 The most common locations are still covered by
492 <filename>${BP}</filename>, <filename>${BPN}</filename>,
493 and "files", which all remain in the default value of
494 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
495 </para></listitem>
496 </itemizedlist>
497 </para>
498 </section>
499
500 <section id='migration-target-package-management-with-rpm'>
501 <title>Target Package Management with RPM</title>
502
503 <para>
504 If runtime package management is enabled and the RPM backend
505 is selected, Smart is now installed for package download, dependency
506 resolution, and upgrades instead of Zypper.
507 For more information on how to use Smart, run the following command
508 on the target:
509 <literallayout class='monospaced'>
510 smart --help
511 </literallayout>
512 </para>
513 </section>
514
515 <section id='migration-1.4-recipes-moved'>
516 <title>Recipes Moved</title>
517
518 <para>
519 The following recipes were moved from their previous locations
520 because they are no longer used by anything in
521 the OpenEmbedded-Core:
522 <itemizedlist>
523 <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis>
524 Now resides in the <filename>meta-oe</filename> layer.
525 </para></listitem>
526 <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis>
527 Now resides in the <filename>meta-gnome</filename> layer.
528 </para></listitem>
529 <listitem><para><emphasis><filename>gthumb</filename>:</emphasis>
530 Now resides in the <filename>meta-gnome</filename> layer.
531 </para></listitem>
532 <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis>
533 Now resides in the <filename>meta-oe</filename> layer.
534 </para></listitem>
535 <listitem><para><emphasis><filename>gupnp</filename>:</emphasis>
536 Now resides in the <filename>meta-multimedia</filename> layer.
537 </para></listitem>
538 <listitem><para><emphasis><filename>gypsy</filename>:</emphasis>
539 Now resides in the <filename>meta-oe</filename> layer.
540 </para></listitem>
541 <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis>
542 Now resides in the <filename>meta-gnome</filename> layer.
543 </para></listitem>
544 <listitem><para><emphasis><filename>libgdata</filename>:</emphasis>
545 Now resides in the <filename>meta-gnome</filename> layer.
546 </para></listitem>
547 <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis>
548 Now resides in the <filename>meta-multimedia</filename> layer.
549 </para></listitem>
550 <listitem><para><emphasis><filename>metacity</filename>:</emphasis>
551 Now resides in the <filename>meta-gnome</filename> layer.
552 </para></listitem>
553 <listitem><para><emphasis><filename>polkit</filename>:</emphasis>
554 Now resides in the <filename>meta-oe</filename> layer.
555 </para></listitem>
556 <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis>
557 Now resides in the <filename>meta-networking</filename> layer.
558 </para></listitem>
559 </itemizedlist>
560 </para>
561 </section>
562
563 <section id='migration-1.4-removals-and-renames'>
564 <title>Removals and Renames</title>
565
566 <para>
567 The following list shows what has been removed or renamed:
568 <itemizedlist>
569 <listitem><para><emphasis><filename>evieext</filename>:</emphasis>
570 Removed because it has been removed from
571 <filename>xserver</filename> since 2008.
572 </para></listitem>
573 <listitem><para><emphasis>Gtk+ DirectFB:</emphasis>
574 Removed support because upstream Gtk+ no longer supports it
575 as of version 2.18.
576 </para></listitem>
577 <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis>
578 Removed because they were removed from the Xorg server in 2008.
579 </para></listitem>
580 <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis>
581 Removed because the XPrint server was removed from
582 Xorg in 2008.
583 </para></listitem>
584 <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis>
585 Removed because their functionality was broken upstream.
586 </para></listitem>
587 <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis>
588 Removed with linux-yocto 3.8 kernel being added.
589 The linux-yocto 3.2 and linux-yocto 3.4 kernels remain
590 as part of the release.
591 </para></listitem>
592 <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis>
593 Removed with functionality now provided by
594 <filename>lsbtest</filename>.
595 </para></listitem>
596 <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis>
597 Removed because it was never more than a proof-of-concept.
598 </para></listitem>
599 <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis>
600 Removed because they are not maintained.
601 However, <filename>matchbox-wm</filename> and
602 <filename>matchbox-theme-sato</filename> are still
603 provided.
604 </para></listitem>
605 <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis>
606 Renamed to <filename>mesa</filename>.
607 </para></listitem>
608 <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis>
609 Removed because it was no longer useful.
610 </para></listitem>
611 <listitem><para><emphasis><filename>mutter</filename>:</emphasis>
612 Removed because nothing ever uses it and the recipe is
613 very old.
614 </para></listitem>
615 <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis>
616 Removed because it has become obsolete.
617 </para></listitem>
618 <listitem><para><emphasis><filename>update-modules</filename>:</emphasis>
619 Removed because it is no longer used.
620 The kernel module <filename>postinstall</filename> and
621 <filename>postrm</filename> scripts can now do the same
622 task without the use of this script.
623 </para></listitem>
624 <listitem><para><emphasis><filename>web</filename>:</emphasis>
625 Removed because it is not maintained. Superseded by
626 <filename>web-webkit</filename>.
627 </para></listitem>
628 <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis>
629 Removed because upstream it has been disabled by default
630 since 2007.
631 Nothing uses <filename>xf86bigfontproto</filename>.
632 </para></listitem>
633 <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis>
634 Removed because its dependency in
635 <filename>xserver</filename> was spurious and it was
636 removed in 2005.
637 </para></listitem>
638 <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis>
639 Removed and been functionally replaced with Smart
640 (<filename>python-smartpm</filename>) when RPM packaging
641 is used and package management is enabled on the target.
642 </para></listitem>
643 </itemizedlist>
644 </para>
645 </section>
646</section>
647
648<section id='moving-to-the-yocto-project-1.5-release'>
649 <title>Moving to the Yocto Project 1.5 Release</title>
650
651 <para>
652 This section provides migration information for moving to the
653 Yocto Project 1.5 Release from the prior release.
654 </para>
655
656 <section id='migration-1.5-host-dependency-changes'>
657 <title>Host Dependency Changes</title>
658
659 <para>
660 The OpenEmbedded build system now has some additional requirements
661 on the host system:
662 <itemizedlist>
663 <listitem><para>Python 2.7.3+</para></listitem>
664 <listitem><para>Tar 1.24+</para></listitem>
665 <listitem><para>Git 1.7.5+</para></listitem>
666 <listitem><para>Patched version of Make if you are using
667 3.82.
668 Most distributions that provide Make 3.82 use the patched
669 version.</para></listitem>
670 </itemizedlist>
671 If the Linux distribution you are using on your build host
672 does not provide packages for these, you can install and use
673 the Buildtools tarball, which provides an SDK-like environment
674 containing them.
675 </para>
676
677 <para>
678 For more information on this requirement, see the
679 "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
680 section.
681 </para>
682 </section>
683
684 <section id='migration-1.5-atom-pc-bsp'>
685 <title><filename>atom-pc</filename> Board Support Package (BSP)</title>
686
687 <para>
688 The <filename>atom-pc</filename> hardware reference BSP has been
689 replaced by a <filename>genericx86</filename> BSP.
690 This BSP is not necessarily guaranteed to work on all x86
691 hardware, but it will run on a wider range of systems than the
692 <filename>atom-pc</filename> did.
693 <note>
694 Additionally, a <filename>genericx86-64</filename> BSP has
695 been added for 64-bit Atom systems.
696 </note>
697 </para>
698 </section>
699
700 <section id='migration-1.5-bitbake'>
701 <title>BitBake</title>
702
703 <para>
704 The following changes have been made that relate to BitBake:
705 <itemizedlist>
706 <listitem><para>
707 BitBake now supports a <filename>_remove</filename>
708 operator.
709 The addition of this operator means you will have to
710 rename any items in recipe space (functions, variables)
711 whose names currently contain
712 <filename>_remove_</filename> or end with
713 <filename>_remove</filename> to avoid unexpected behavior.
714 </para></listitem>
715 <listitem><para>
716 BitBake's global method pool has been removed.
717 This method is not particularly useful and led to clashes
718 between recipes containing functions that had the
719 same name.</para></listitem>
720 <listitem><para>
721 The "none" server backend has been removed.
722 The "process" server backend has been serving well as the
723 default for a long time now.</para></listitem>
724 <listitem><para>
725 The <filename>bitbake-runtask</filename> script has been
726 removed.</para></listitem>
727 <listitem><para>
728 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
729 and
730 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
731 are no longer added to
732 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
733 by default in <filename>bitbake.conf</filename>.
734 These version-specific <filename>PROVIDES</filename>
735 items were seldom used.
736 Attempting to use them could result in two versions being
737 built simultaneously rather than just one version due to
738 the way BitBake resolves dependencies.</para></listitem>
739 </itemizedlist>
740 </para>
741 </section>
742
743 <section id='migration-1.5-qa-warnings'>
744 <title>QA Warnings</title>
745
746 <para>
747 The following changes have been made to the package QA checks:
748 <itemizedlist>
749 <listitem><para>
750 If you have customized
751 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
752 or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>
753 values in your configuration, check that they contain all of
754 the issues that you wish to be reported.
755 Previous Yocto Project versions contained a bug that meant
756 that any item not mentioned in <filename>ERROR_QA</filename>
757 or <filename>WARN_QA</filename> would be treated as a
758 warning.
759 Consequently, several important items were not already in
760 the default value of <filename>WARN_QA</filename>.
761 All of the possible QA checks are now documented in the
762 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
763 section.</para></listitem>
764 <listitem><para>
765 An additional QA check has been added to check if
766 <filename>/usr/share/info/dir</filename> is being installed.
767 Your recipe should delete this file within
768 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
769 if "make install" is installing it.
770 </para></listitem>
771 <listitem><para>
772 If you are using the buildhistory class, the check for the
773 package version going backwards is now controlled using a
774 standard QA check.
775 Thus, if you have customized your
776 <filename>ERROR_QA</filename> or
777 <filename>WARN_QA</filename> values and still wish to have
778 this check performed, you should add
779 "version-going-backwards" to your value for one or the
780 other variables depending on how you wish it to be handled.
781 See the documented QA checks in the
782 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
783 section.
784 </para></listitem>
785 </itemizedlist>
786 </para>
787 </section>
788
789 <section id='migration-1.5-directory-layout-changes'>
790 <title>Directory Layout Changes</title>
791
792 <para>
793 The following directory changes exist:
794 <itemizedlist>
795 <listitem><para>
796 Output SDK installer files are now named to include the
797 image name and tuning architecture through the
798 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
799 variable.</para></listitem>
800 <listitem><para>
801 Images and related files are now installed into a directory
802 that is specific to the machine, instead of a parent
803 directory containing output files for multiple machines.
804 The
805 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
806 variable continues to point to the directory containing
807 images for the current
808 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
809 and should be used anywhere there is a need to refer to
810 this directory.
811 The <filename>runqemu</filename> script now uses this
812 variable to find images and kernel binaries and will use
813 BitBake to determine the directory.
814 Alternatively, you can set the
815 <filename>DEPLOY_DIR_IMAGE</filename> variable in the
816 external environment.</para></listitem>
817 <listitem><para>
818 When buildhistory is enabled, its output is now written
819 under the
820 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
821 rather than
822 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>.
823 Doing so makes it easier to delete
824 <filename>TMPDIR</filename> and preserve the build history.
825 Additionally, data for produced SDKs is now split by
826 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>.
827 </para></listitem>
828 <listitem><para>
829 The <filename>pkgdata</filename> directory produced as
830 part of the packaging process has been collapsed into a
831 single machine-specific directory.
832 This directory is located under
833 <filename>sysroots</filename> and uses a machine-specific
834 name (i.e.
835 <filename>tmp/sysroots/&lt;machine&gt;/pkgdata</filename>).
836 </para></listitem>
837 </itemizedlist>
838 </para>
839 </section>
840
841 <section id='migration-1.5-shortened-git-srcrev-values'>
842 <title>Shortened Git <filename>SRCREV</filename> Values</title>
843
844 <para>
845 BitBake will now shorten revisions from Git repositories from the
846 normal 40 characters down to 10 characters within
847 <link linkend='var-SRCPV'><filename>SRCPV</filename></link>
848 for improved usability in path and file names.
849 This change should be safe within contexts where these revisions
850 are used because the chances of spatially close collisions
851 is very low.
852 Distant collisions are not a major issue in the way
853 the values are used.
854 </para>
855 </section>
856
857 <section id='migration-1.5-image-features'>
858 <title><filename>IMAGE_FEATURES</filename></title>
859
860 <para>
861 The following changes have been made that relate to
862 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
863 <itemizedlist>
864 <listitem><para>
865 The value of
866 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
867 is now validated to ensure invalid feature items are not
868 added.
869 Some users mistakenly add package names to this variable
870 instead of using
871 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
872 in order to have the package added to the image, which does
873 not work.
874 This change is intended to catch those kinds of situations.
875 Valid <filename>IMAGE_FEATURES</filename> are drawn from
876 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
877 definitions,
878 <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
879 and a new "validitems" varflag on
880 <filename>IMAGE_FEATURES</filename>.
881 The "validitems" varflag change allows additional features
882 to be added if they are not provided using the previous
883 two mechanisms.
884 </para></listitem>
885 <listitem><para>
886 The previously deprecated "apps-console-core"
887 <filename>IMAGE_FEATURES</filename> item is no longer
888 supported.
889 Add "splash" to <filename>IMAGE_FEATURES</filename> if you
890 wish to have the splash screen enabled, since this is
891 all that apps-console-core was doing.</para></listitem>
892 </itemizedlist>
893 </para>
894 </section>
895
896 <section id='migration-1.5-run'>
897 <title><filename>/run</filename></title>
898
899 <para>
900 The <filename>/run</filename> directory from the Filesystem
901 Hierarchy Standard 3.0 has been introduced.
902 You can find some of the implications for this change
903 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
904 The change also means that recipes that install files to
905 <filename>/var/run</filename> must be changed.
906 You can find a guide on how to make these changes
907 <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
908 </para>
909 </section>
910
911 <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
912 <title>Removal of Package Manager Database Within Image Recipes</title>
913
914 <para>
915 The image <filename>core-image-minimal</filename> no longer adds
916 <filename>remove_packaging_data_files</filename> to
917 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
918 This addition is now handled automatically when "package-management"
919 is not in
920 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
921 If you have custom image recipes that make this addition,
922 you should remove the lines, as they are not needed and might
923 interfere with correct operation of postinstall scripts.
924 </para>
925 </section>
926
927 <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
928 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
929
930 <para>
931 The
932 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
933 and other related image
934 construction tasks are no longer marked as "nostamp".
935 Consequently, they will only be re-executed when their inputs have
936 changed.
937 Previous versions of the OpenEmbedded build system always rebuilt
938 the image when requested rather when necessary.
939 </para>
940 </section>
941
942 <section id='migration-1.5-task-recipes'>
943 <title>Task Recipes</title>
944
945 <para>
946 The previously deprecated <filename>task.bbclass</filename> has
947 now been dropped.
948 For recipes that previously inherited from this class, you should
949 rename them from <filename>task-*</filename> to
950 <filename>packagegroup-*</filename> and inherit packagegroup
951 instead.
952 </para>
953
954 <para>
955 For more information, see the
956 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
957 section.
958 </para>
959 </section>
960
961 <section id='migration-1.5-busybox'>
962 <title>BusyBox</title>
963
964 <para>
965 By default, we now split BusyBox into two binaries:
966 one that is suid root for those components that need it, and
967 another for the rest of the components.
968 Splitting BusyBox allows for optimization that eliminates the
969 <filename>tinylogin</filename> recipe as recommended by upstream.
970 You can disable this split by setting
971 <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
972 to "0".
973 </para>
974 </section>
975
976 <section id='migration-1.5-automated-image-testing'>
977 <title>Automated Image Testing</title>
978
979 <para>
980 A new automated image testing framework has been added
981 through the
982 <link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link>
983 class.
984 This framework replaces the older
985 <filename>imagetest-qemu</filename> framework.
986 </para>
987
988 <para>
989 You can learn more about performing automated image tests in the
990 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
991 section.
992 </para>
993 </section>
994
995 <section id='migration-1.5-build-history'>
996 <title>Build History</title>
997
998 <para>
999 Following are changes to Build History:
1000 <itemizedlist>
1001 <listitem><para>
1002 Installed package sizes:
1003 <filename>installed-package-sizes.txt</filename> for an
1004 image now records the size of the files installed by each
1005 package instead of the size of each compressed package
1006 archive file.</para></listitem>
1007 <listitem><para>
1008 The dependency graphs (<filename>depends*.dot</filename>)
1009 now use the actual package names instead of replacing
1010 dashes, dots and plus signs with underscores.
1011 </para></listitem>
1012 <listitem><para>
1013 The <filename>buildhistory-diff</filename> and
1014 <filename>buildhistory-collect-srcrevs</filename>
1015 utilities have improved command-line handling.
1016 Use the <filename>&dash;&dash;help</filename> option for
1017 each utility for more information on the new syntax.
1018 </para></listitem>
1019 </itemizedlist>
1020 For more information on Build History, see the
1021 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
1022 section.
1023 </para>
1024 </section>
1025
1026 <section id='migration-1.5-udev'>
1027 <title><filename>udev</filename></title>
1028
1029 <para>
1030 Following are changes to <filename>udev</filename>:
1031 <itemizedlist>
1032 <listitem><para>
1033 <filename>udev</filename> no longer brings in
1034 <filename>udev-extraconf</filename> automatically
1035 through
1036 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1037 since this was originally intended to be optional.
1038 If you need the extra rules, then add
1039 <filename>udev-extraconf</filename> to your image.
1040 </para></listitem>
1041 <listitem><para>
1042 <filename>udev</filename> no longer brings in
1043 <filename>pciutils-ids</filename> or
1044 <filename>usbutils-ids</filename> through
1045 <filename>RRECOMMENDS</filename>.
1046 These are not needed by <filename>udev</filename> itself
1047 and removing them saves around 350KB.
1048 </para></listitem>
1049 </itemizedlist>
1050 </para>
1051 </section>
1052
1053 <section id='migration-1.5-removed-renamed-recipes'>
1054 <title>Removed and Renamed Recipes</title>
1055
1056 <itemizedlist>
1057 <listitem><para>
1058 The <filename>linux-yocto</filename> 3.2 kernel has been
1059 removed.</para></listitem>
1060 <listitem><para>
1061 <filename>libtool-nativesdk</filename> has been renamed to
1062 <filename>nativesdk-libtool</filename>.</para></listitem>
1063 <listitem><para>
1064 <filename>tinylogin</filename> has been removed.
1065 It has been replaced by a suid portion of Busybox.
1066 See the
1067 "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
1068 for more information.</para></listitem>
1069 <listitem><para>
1070 <filename>external-python-tarball</filename> has been renamed
1071 to <filename>buildtools-tarball</filename>.
1072 </para></listitem>
1073 <listitem><para>
1074 <filename>web-webkit</filename> has been removed.
1075 It has been functionally replaced by
1076 <filename>midori</filename>.</para></listitem>
1077 <listitem><para>
1078 <filename>imake</filename> has been removed.
1079 It is no longer needed by any other recipe.
1080 </para></listitem>
1081 <listitem><para>
1082 <filename>transfig-native</filename> has been removed.
1083 It is no longer needed by any other recipe.
1084 </para></listitem>
1085 <listitem><para>
1086 <filename>anjuta-remote-run</filename> has been removed.
1087 Anjuta IDE integration has not been officially supported for
1088 several releases.</para></listitem>
1089 </itemizedlist>
1090 </section>
1091
1092 <section id='migration-1.5-other-changes'>
1093 <title>Other Changes</title>
1094
1095 <para>
1096 Following is a list of short entries describing other changes:
1097 <itemizedlist>
1098 <listitem><para>
1099 <filename>run-postinsts</filename>: Make this generic.
1100 </para></listitem>
1101 <listitem><para>
1102 <filename>base-files</filename>: Remove the unnecessary
1103 <filename>media/xxx</filename> directories.
1104 </para></listitem>
1105 <listitem><para>
1106 <filename>alsa-state</filename>: Provide an empty
1107 <filename>asound.conf</filename> by default.
1108 </para></listitem>
1109 <listitem><para>
1110 <filename>classes/image</filename>: Ensure
1111 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1112 supports pre-renamed package names.</para></listitem>
1113 <listitem><para>
1114 <filename>classes/rootfs_rpm</filename>: Implement
1115 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1116 for RPM.</para></listitem>
1117 <listitem><para>
1118 <filename>systemd</filename>: Remove
1119 <filename>systemd_unitdir</filename> if
1120 <filename>systemd</filename> is not in
1121 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1122 </para></listitem>
1123 <listitem><para>
1124 <filename>systemd</filename>: Remove
1125 <filename>init.d</filename> dir if
1126 <filename>systemd</filename> unit file is present and
1127 <filename>sysvinit</filename> is not a distro feature.
1128 </para></listitem>
1129 <listitem><para>
1130 <filename>libpam</filename>: Deny all services for the
1131 <filename>OTHER</filename> entries.
1132 </para></listitem>
1133 <listitem><para>
1134 <filename>image.bbclass</filename>: Move
1135 <filename>runtime_mapping_rename</filename> to avoid
1136 conflict with <filename>multilib</filename>.
1137 See
1138 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
1139 in Bugzilla for more information.
1140 </para></listitem>
1141 <listitem><para>
1142 <filename>linux-dtb</filename>: Use kernel build system
1143 to generate the <filename>dtb</filename> files.
1144 </para></listitem>
1145 <listitem><para>
1146 <filename>kern-tools</filename>: Switch from guilt to
1147 new <filename>kgit-s2q</filename> tool.
1148 </para></listitem>
1149 </itemizedlist>
1150 </para>
1151 </section>
1152</section>
1153
1154<section id='moving-to-the-yocto-project-1.6-release'>
1155 <title>Moving to the Yocto Project 1.6 Release</title>
1156
1157 <para>
1158 This section provides migration information for moving to the
1159 Yocto Project 1.6 Release from the prior release.
1160 </para>
1161
1162
1163 <section id='migration-1.6-archiver-class'>
1164 <title><filename>archiver</filename> Class</title>
1165
1166 <para>
1167 The
1168 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
1169 class has been rewritten and its configuration has been simplified.
1170 For more details on the source archiver, see the
1171 "<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>"
1172 section in the Yocto Project Development Manual.
1173 </para>
1174 </section>
1175
1176 <section id='migration-1.6-packaging-changes'>
1177 <title>Packaging Changes</title>
1178
1179 <para>
1180 The following packaging changes have been made:
1181 <itemizedlist>
1182 <listitem><para>
1183 The <filename>binutils</filename> recipe no longer produces
1184 a <filename>binutils-symlinks</filename> package.
1185 <filename>update-alternatives</filename> is now used to
1186 handle the preferred <filename>binutils</filename>
1187 variant on the target instead.
1188 </para></listitem>
1189 <listitem><para>
1190 The tc (traffic control) utilities have been split out of
1191 the main <filename>iproute2</filename> package and put
1192 into the <filename>iproute2-tc</filename> package.
1193 </para></listitem>
1194 <listitem><para>
1195 The <filename>gtk-engines</filename> schemas have been
1196 moved to a dedicated
1197 <filename>gtk-engines-schemas</filename> package.
1198 </para></listitem>
1199 <listitem><para>
1200 The <filename>armv7a</filename> with thumb package
1201 architecture suffix has changed.
1202 The suffix for these packages with the thumb
1203 optimization enabled is "t2" as it should be.
1204 Use of this suffix was not the case in the 1.5 release.
1205 Architecture names will change within package feeds as a
1206 result.
1207 </para></listitem>
1208 </itemizedlist>
1209 </para>
1210 </section>
1211
1212 <section id='migration-1.6-bitbake'>
1213 <title>BitBake</title>
1214
1215 <para>
1216 The following changes have been made to
1217 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
1218 </para>
1219
1220 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
1221 <title>Matching Branch Requirement for Git Fetching</title>
1222
1223 <para>
1224 When fetching source from a Git repository using
1225 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
1226 BitBake will now validate the
1227 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
1228 value against the branch.
1229 You can specify the branch using the following form:
1230 <literallayout class='monospaced'>
1231 SRC_URI = "git://server.name/repository;branch=&lt;branchname&gt;"
1232 </literallayout>
1233 If you do not specify a branch, BitBake looks
1234 in the default "master" branch.
1235 </para>
1236
1237 <para>
1238 Alternatively, if you need to bypass this check (e.g.
1239 if you are fetching a revision corresponding to a tag that
1240 is not on any branch), you can add ";nobranch=1" to
1241 the end of the URL within <filename>SRC_URI</filename>.
1242 </para>
1243 </section>
1244
1245 <section id='migration-1.6-bitbake-deps'>
1246 <title>Python Definition substitutions</title>
1247
1248 <para>
1249 BitBake had some previously deprecated Python definitions
1250 within its <filename>bb</filename> module removed.
1251 You should use their sub-module counterparts instead:
1252 <itemizedlist>
1253 <listitem><para><filename>bb.MalformedUrl</filename>:
1254 Use <filename>bb.fetch.MalformedUrl</filename>.
1255 </para></listitem>
1256 <listitem><para><filename>bb.fetch.encodeurl</filename>:
1257 Use <filename>bb.fetch.encodeurl</filename>.
1258 </para></listitem>
1259 <listitem><para><filename>bb.decodeurl</filename>:
1260 Use <filename>bb.fetch.decodeurl</filename>
1261 </para></listitem>
1262 <listitem><para><filename>bb.mkdirhier</filename>:
1263 Use <filename>bb.utils.mkdirhier</filename>.
1264 </para></listitem>
1265 <listitem><para><filename>bb.movefile</filename>:
1266 Use <filename>bb.utils.movefile</filename>.
1267 </para></listitem>
1268 <listitem><para><filename>bb.copyfile</filename>:
1269 Use <filename>bb.utils.copyfile</filename>.
1270 </para></listitem>
1271 <listitem><para><filename>bb.which</filename>:
1272 Use <filename>bb.utils.which</filename>.
1273 </para></listitem>
1274 <listitem><para><filename>bb.vercmp_string</filename>:
1275 Use <filename>bb.utils.vercmp_string</filename>.
1276 </para></listitem>
1277 <listitem><para><filename>bb.vercmp</filename>:
1278 Use <filename>bb.utils.vercmp</filename>.
1279 </para></listitem>
1280 </itemizedlist>
1281 </para>
1282 </section>
1283
1284 <section id='migration-1.6-bitbake-fetcher'>
1285 <title>SVK Fetcher</title>
1286
1287 <para>
1288 The SVK fetcher has been removed from BitBake.
1289 </para>
1290 </section>
1291
1292 <section id='migration-1.6-bitbake-console-output'>
1293 <title>Console Output Error Redirection</title>
1294
1295 <para>
1296 The BitBake console UI will now output errors to
1297 <filename>stderr</filename> instead of
1298 <filename>stdout</filename>.
1299 Consequently, if you are piping or redirecting the output of
1300 <filename>bitbake</filename> to somewhere else, and you wish
1301 to retain the errors, you will need to add
1302 <filename>2>&amp;1</filename> (or something similar) to the
1303 end of your <filename>bitbake</filename> command line.
1304 </para>
1305 </section>
1306
1307 <section id='migration-1.6-task-taskname-overrides'>
1308 <title><filename>task-&lt;taskname&gt;</filename> Overrides</title>
1309
1310 <para>
1311 <filename>task-&lt;taskname&gt;</filename> overrides have been
1312 adjusted so that tasks whose names contain underscores have the
1313 underscores replaced by hyphens for the override so that they
1314 now function properly.
1315 For example, the task override for
1316 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1317 is <filename>task-populate-sdk</filename>.
1318 </para>
1319 </section>
1320 </section>
1321
1322 <section id='migration-1.6-variable-changes'>
1323 <title>Changes to Variables</title>
1324
1325 <para>
1326 The following variables have changed.
1327 For information on the OpenEmbedded build system variables, see the
1328 "<link linkend='ref-variables-glos'>Variables Glossary</link>" Chapter.
1329 </para>
1330
1331 <section id='migration-1.6-variable-changes-TMPDIR'>
1332 <title><filename>TMPDIR</filename></title>
1333
1334 <para>
1335 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1336 can no longer be on an NFS mount.
1337 NFS does not offer full POSIX locking and inode consistency
1338 and can cause unexpected issues if used to store
1339 <filename>TMPDIR</filename>.
1340 </para>
1341
1342 <para>
1343 The check for this occurs on startup.
1344 If <filename>TMPDIR</filename> is detected on an NFS mount,
1345 an error occurs.
1346 </para>
1347 </section>
1348
1349 <section id='migration-1.6-variable-changes-PRINC'>
1350 <title><filename>PRINC</filename></title>
1351
1352 <para>
1353 The
1354 <link linkend='var-PRINC'><filename>PRINC</filename></link>
1355 variable has been deprecated and triggers a warning if
1356 detected during a build.
1357 For
1358 <link linkend='var-PR'><filename>PR</filename></link>
1359 increments on changes, use the PR service instead.
1360 You can find out more about this service in the
1361 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
1362 section in the Yocto Project Development Manual.
1363 </para>
1364 </section>
1365
1366 <section id='migration-1.6-variable-changes-IMAGE_TYPES'>
1367 <title><filename>IMAGE_TYPES</filename></title>
1368
1369 <para>
1370 The "sum.jffs2" option for
1371 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>
1372 has been replaced by the "jffs2.sum" option, which fits the
1373 processing order.
1374 </para>
1375 </section>
1376
1377 <section id='migration-1.6-variable-changes-COPY_LIC_MANIFEST'>
1378 <title><filename>COPY_LIC_MANIFEST</filename></title>
1379
1380 <para>
1381 The
1382 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1383 variable must
1384 now be set to "1" rather than any value in order to enable
1385 it.
1386 </para>
1387 </section>
1388
1389 <section id='migration-1.6-variable-changes-COPY_LIC_DIRS'>
1390 <title><filename>COPY_LIC_DIRS</filename></title>
1391
1392 <para>
1393 The
1394 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
1395 variable must
1396 now be set to "1" rather than any value in order to enable
1397 it.
1398 </para>
1399 </section>
1400
1401 <section id='migration-1.6-variable-changes-PACKAGE_GROUP'>
1402 <title><filename>PACKAGE_GROUP</filename></title>
1403
1404 <para>
1405 The
1406 <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
1407 variable has been renamed to
1408 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>
1409 to more accurately reflect its purpose.
1410 You can still use <filename>PACKAGE_GROUP</filename> but
1411 the OpenEmbedded build system produces a warning message when
1412 it encounters the variable.
1413 </para>
1414 </section>
1415 </section>
1416
1417 <section id='migration-1.6-directory-layout-changes'>
1418 <title>Directory Layout Changes</title>
1419
1420 <para>
1421 The <filename>meta-hob</filename> layer has been removed from
1422 the top-level of the
1423 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1424 The contents of this layer are no longer needed by the Hob
1425 user interface for building images and toolchains.
1426 </para>
1427 </section>
1428
1429 <section id='migration-1.6-package-test-ptest'>
1430 <title>Package Test (ptest)</title>
1431
1432 <para>
1433 Package Tests (ptest) are built but not installed by default.
1434 For information on using Package Tests, see the
1435 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Setting up and running package test (ptest)</ulink>"
1436 section in the Yocto Project Development Manual.
1437 For information on the <filename>ptest</filename> class, see the
1438 "<link linkend='ref-classes-ptest'><filename>ptest.bbclass</filename></link>"
1439 section.
1440 </para>
1441 </section>
1442
1443 <section id='migration-1.6-build-changes'>
1444 <title>Build Changes</title>
1445
1446 <para>
1447 Separate build and source directories have been enabled
1448 by default for selected recipes where it is known to work
1449 (a whitelist) and for all recipes that inherit the
1450 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
1451 class.
1452 In future releases the
1453 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1454 class will enable a separate build directory by default as
1455 well.
1456 Recipes building Autotools-based
1457 software that fails to build with a separate build directory
1458 should be changed to inherit from the
1459 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
1460 class instead of the <filename>autotools</filename> class.
1461 </para>
1462 </section>
1463
1464 <section id='migration-1.6-building-qemu-native'>
1465 <title><filename>qemu-native</filename></title>
1466
1467 <para>
1468 <filename>qemu-native</filename> now builds without
1469 SDL-based graphical output support by default.
1470 The following additional lines are needed in your
1471 <filename>local.conf</filename> to enable it:
1472 <literallayout class='monospaced'>
1473 PACKAGECONFIG_pn-qemu-native = "sdl"
1474 ASSUME_PROVIDED += "libsdl-native"
1475 </literallayout>
1476 <note>
1477 The default <filename>local.conf</filename>
1478 contains these statements.
1479 Consequently, if you are building a headless system and using
1480 a default <filename>local.conf</filename> file, you will need
1481 comment these two lines out.
1482 </note>
1483 </para>
1484 </section>
1485
1486 <section id='migration-1.6-core-image-basic'>
1487 <title><filename>core-image-basic</filename></title>
1488
1489 <para>
1490 <filename>core-image-basic</filename> has been renamed to
1491 <filename>core-image-full-cmdline</filename>.
1492 </para>
1493
1494 <para>
1495 In addition to <filename>core-image-basic</filename> being renamed,
1496 <filename>packagegroup-core-basic</filename> has been renamed to
1497 <filename>packagegroup-core-full-cmdline</filename> to match.
1498 </para>
1499 </section>
1500
1501 <section id='migration-1.6-licensing'>
1502 <title>Licensing</title>
1503
1504 <para>
1505 The top-level <filename>LICENSE</filename> file has been changed
1506 to better describe the license of the various components of
1507 OE-Core.
1508 However, the licensing itself remains unchanged.
1509 </para>
1510
1511 <para>
1512 Normally, this change would not cause any side-effects.
1513 However, some recipes point to this file within
1514 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
1515 (as <filename>${COREBASE}/LICENSE</filename>) and thus the
1516 accompanying checksum must be changed from
1517 3f40d7994397109285ec7b81fdeb3b58 to
1518 4d92cd373abda3937c2bc47fbc49d690.
1519 A better alternative is to have
1520 <filename>LIC_FILES_CHKSUM</filename> point to a file
1521 describing the license that is distributed with the source
1522 that the recipe is building, if possible, rather than pointing
1523 to <filename>${COREBASE}/LICENSE</filename>.
1524 </para>
1525 </section>
1526
1527 <section id='migration-1.6-cflags-options'>
1528 <title><filename>CFLAGS</filename> Options</title>
1529
1530 <para>
1531 The "-fpermissive" option has been removed from the default
1532 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1533 value.
1534 You need to take action on individual recipes that fail when
1535 building with this option.
1536 You need to either patch the recipes to fix the issues reported by
1537 the compiler, or you need to add "-fpermissive" to
1538 <filename>CFLAGS</filename> in the recipes.
1539 </para>
1540 </section>
1541
1542 <section id='migration-1.6-custom-images'>
1543 <title>Custom Image Output Types</title>
1544
1545 <para>
1546 Custom image output types, as selected using
1547 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
1548 must declare their dependencies on other image types (if any) using
1549 a new
1550 <link linkend='var-IMAGE_TYPEDEP'><filename>IMAGE_TYPEDEP</filename></link>
1551 variable.
1552 </para>
1553 </section>
1554
1555 <section id='migration-1.6-do-package-write-task'>
1556 <title>Tasks</title>
1557
1558 <para>
1559 The <filename>do_package_write</filename> task has been removed.
1560 The task is no longer needed.
1561 </para>
1562 </section>
1563
1564 <section id='migration-1.6-update-alternatives-provider'>
1565 <title><filename>update-alternative</filename> Provider</title>
1566
1567 <para>
1568 The default <filename>update-alternatives</filename> provider has
1569 been changed from <filename>opkg</filename> to
1570 <filename>opkg-utils</filename>.
1571 This change resolves some troublesome circular dependencies.
1572 The runtime package has also been renamed from
1573 <filename>update-alternatives-cworth</filename>
1574 to <filename>update-alternatives-opkg</filename>.
1575 </para>
1576 </section>
1577
1578 <section id='migration-1.6-virtclass-overrides'>
1579 <title><filename>virtclass</filename> Overrides</title>
1580
1581 <para>
1582 The <filename>virtclass</filename> overrides are now deprecated.
1583 Use the equivalent class overrides instead (e.g.
1584 <filename>virtclass-native</filename> becomes
1585 <filename>class-native</filename>.)
1586 </para>
1587 </section>
1588
1589 <section id='migration-1.6-removed-renamed-recipes'>
1590 <title>Removed and Renamed Recipes</title>
1591
1592 <para>
1593 The following recipes have been removed:
1594 <itemizedlist>
1595 <listitem><para><filename>packagegroup-toolset-native</filename> -
1596 This recipe is largely unused.
1597 </para></listitem>
1598 <listitem><para><filename>linux-yocto-3.8</filename> -
1599 Support for the Linux yocto 3.8 kernel has been dropped.
1600 Support for the 3.10 and 3.14 kernels have been added
1601 with the <filename>linux-yocto-3.10</filename> and
1602 <filename>linux-yocto-3.14</filename> recipes.
1603 </para></listitem>
1604 <listitem><para><filename>ocf-linux</filename> -
1605 This recipe has been functionally replaced using
1606 <filename>cryptodev-linux</filename>.
1607 </para></listitem>
1608 <listitem><para><filename>genext2fs</filename> -
1609 <filename>genext2fs</filename> is no longer used by the
1610 build system and is unmaintained upstream.
1611 </para></listitem>
1612 <listitem><para><filename>js</filename> -
1613 This provided an ancient version of Mozilla's javascript
1614 engine that is no longer needed.
1615 </para></listitem>
1616 <listitem><para><filename>zaurusd</filename> -
1617 The recipe has been moved to the
1618 <filename>meta-handheld</filename> layer.
1619 </para></listitem>
1620 <listitem><para><filename>eglibc 2.17</filename> -
1621 Replaced by the <filename>eglibc 2.19</filename>
1622 recipe.
1623 </para></listitem>
1624 <listitem><para><filename>gcc 4.7.2</filename> -
1625 Replaced by the now stable
1626 <filename>gcc 4.8.2</filename>.
1627 </para></listitem>
1628 <listitem><para><filename>external-sourcery-toolchain</filename> -
1629 this recipe is now maintained in the
1630 <filename>meta-sourcery</filename> layer.
1631 </para></listitem>
1632 <listitem><para><filename>linux-libc-headers-yocto 3.4+git</filename> -
1633 Now using version 3.10 of the
1634 <filename>linux-libc-headers</filename> by default.
1635 </para></listitem>
1636 <listitem><para><filename>meta-toolchain-gmae</filename> -
1637 This recipe is obsolete.
1638 </para></listitem>
1639 <listitem><para><filename>packagegroup-core-sdk-gmae</filename> -
1640 This recipe is obsolete.
1641 </para></listitem>
1642 <listitem><para><filename>packagegroup-core-standalone-gmae-sdk-target</filename> -
1643 This recipe is obsolete.
1644 </para></listitem>
1645 </itemizedlist>
1646 </para>
1647 </section>
1648
1649 <section id='migration-1.6-removed-classes'>
1650 <title>Removed Classes</title>
1651
1652 <para>
1653 The following classes have become obsolete and have been removed:
1654 <itemizedlist>
1655 <listitem><para><filename>module_strip</filename>
1656 </para></listitem>
1657 <listitem><para><filename>pkg_metainfo</filename>
1658 </para></listitem>
1659 <listitem><para><filename>pkg_distribute</filename>
1660 </para></listitem>
1661 <listitem><para><filename>image-empty</filename>
1662 </para></listitem>
1663 </itemizedlist>
1664 </para>
1665 </section>
1666
1667 <section id='migration-1.6-reference-bsps'>
1668 <title>Reference Board Support Packages (BSPs)</title>
1669
1670 <para>
1671 The following reference BSPs changes occurred:
1672 <itemizedlist>
1673 <listitem><para>The BeagleBoard
1674 (<filename>beagleboard</filename>) ARM reference hardware
1675 has been replaced by the BeagleBone
1676 (<filename>beaglebone</filename>) hardware.
1677 </para></listitem>
1678 <listitem><para>The RouterStation Pro
1679 (<filename>routerstationpro</filename>) MIPS reference
1680 hardware has been replaced by the EdgeRouter Lite
1681 (<filename>edgerouter</filename>) hardware.
1682 </para></listitem>
1683 </itemizedlist>
1684 The previous reference BSPs for the
1685 <filename>beagleboard</filename> and
1686 <filename>routerstationpro</filename> machines are still available
1687 in a new <filename>meta-yocto-bsp-old</filename> layer in the
1688 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1689 at
1690 <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>.
1691 </para>
1692 </section>
1693</section>
1694</chapter>
1695<!--
1696vim: expandtab tw=80 ts=4
1697-->
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..e7e9942
--- /dev/null
+++ b/documentation/ref-manual/ref-classes.xml
@@ -0,0 +1,3300 @@
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><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> &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><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> &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><link linkend='ref-tasks-install'><filename>do_install</filename></link> &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 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
554 function to copy the files to be 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
558 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
559 or
560 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
561 The class then takes care of staging the files from
562 <filename>DEPLOYDIR</filename> to
563 <filename>DEPLOY_DIR_IMAGE</filename>.
564 </para>
565</section>
566
567<section id='ref-classes-devshell'>
568 <title><filename>devshell.bbclass</filename></title>
569
570 <para>
571 The <filename>devshell</filename> class adds the
572 <filename>do_devshell</filename> task.
573 Distribution policy dictates whether to include this class.
574 See the
575 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
576 in the Yocto Project Development Manual for more information about
577 using <filename>devshell</filename>.
578 </para>
579</section>
580
581<section id='ref-classes-distro_features_check'>
582 <title><filename>distro_features_check.bbclass</filename></title>
583
584 <para>
585 The <filename>distro_features_check</filename> class
586 allows individual recipes to check for required and conflicting
587 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
588 </para>
589
590 <para>
591 This class provides support for the
592 <link linkend='var-REQUIRED_DISTRO_FEATURES'><filename>REQUIRED_DISTRO_FEATURES</filename></link>
593 and
594 <link linkend='var-CONFLICT_DISTRO_FEATURES'><filename>CONFLICT_DISTRO_FEATURES</filename></link>
595 variables.
596 If any conditions specified in the recipe using the above variables are
597 not met, the recipe will be skipped.
598 </para>
599</section>
600
601<section id='ref-classes-distrodata'>
602 <title><filename>distrodata.bbclass</filename></title>
603
604 <para>
605 The <filename>distrodata</filename> class
606 provides for automatic checking for upstream recipe updates.
607 The class creates a comma-separated value (CSV) spreadsheet that
608 contains information about the recipes.
609 The information provides the <filename>do_distrodata</filename> and
610 <filename>do_distro_check</filename> tasks, which do upstream checking
611 and also verify if a package is used in multiple major distributions.
612 </para>
613
614 <para>
615 The class is not included by default.
616 To use it, you must include the following files and set the
617 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
618 variable:
619 <literallayout class='monospaced'>
620 include conf/distro/include/distro_alias.inc
621 include conf/distro/include/recipe_color.inc
622 include conf/distro/include/maintainers.inc
623 include conf/distro/include/upstream_tracking.inc
624 include conf/distro/include/package_regex.inc
625 INHERIT+= "distrodata"
626 </literallayout>
627 </para>
628</section>
629
630<section id='ref-classes-distutils'>
631 <title><filename>distutils.bbclass</filename></title>
632
633 <para>
634 The <filename>distutils</filename> class supports recipes for Python
635 version 2.x extensions, which are simple.
636 These recipes usually only need to point to the source's archive and
637 then inherit the proper class.
638 Building is split into two methods depending on which method the
639 module authors used.
640 <itemizedlist>
641 <listitem><para>Extensions that use an Autotools-based build system
642 require Autotools and
643 <filename>distutils</filename>-based classes in their recipes.
644 </para></listitem>
645 <listitem><para>Extensions that use build systems based on
646 <filename>distutils</filename> require
647 the <filename>distutils</filename> class in their recipes.
648 </para></listitem>
649 <listitem><para>Extensions that use build systems based on
650 <filename>setuptools</filename> require the
651 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
652 class in their recipes.
653 </para></listitem>
654 </itemizedlist>
655 </para>
656</section>
657
658<section id='ref-classes-distutils3'>
659 <title><filename>distutils3.bbclass</filename></title>
660
661 <para>
662 The <filename>distutils3</filename> class supports recipes for Python
663 version 3.x extensions, which are simple.
664 These recipes usually only need to point to the source's archive and
665 then inherit the proper class.
666 Building is split into two methods depending on which method the
667 module authors used.
668 <itemizedlist>
669 <listitem><para>Extensions that use an Autotools-based build system
670 require Autotools and
671 <filename>distutils</filename>-based classes in their recipes.
672 </para></listitem>
673 <listitem><para>Extensions that use
674 <filename>distutils</filename>-based build systems require
675 the <filename>distutils</filename> class in their recipes.
676 </para></listitem>
677 <listitem><para>Extensions that use build systems based on
678 <filename>setuptools3</filename> require the
679 <link linkend='ref-classes-setuptools'><filename>setuptools3</filename></link>
680 class in their recipes.
681 </para></listitem>
682 </itemizedlist>
683 </para>
684</section>
685
686<section id='ref-classes-externalsrc'>
687 <title><filename>externalsrc.bbclass</filename></title>
688
689 <para>
690 The <filename>externalsrc</filename> class supports building software
691 from source code that is external to the OpenEmbedded build system.
692 Building software from an external source tree means that the build
693 system's normal fetch, unpack, and patch process is not used.
694 </para>
695
696 <para>
697 By default, the OpenEmbedded build system uses the
698 <link linkend='var-S'><filename>S</filename></link> and
699 <link linkend='var-B'><filename>B</filename></link> variables to
700 locate unpacked recipe source code and to build it, respectively.
701 When your recipe inherits the <filename>externalsrc</filename> class,
702 you use the
703 <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
704 and
705 <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
706 variables to ultimately define <filename>S</filename> and
707 <filename>B</filename>.
708 </para>
709
710 <para>
711 By default, this class expects the source code to support recipe builds
712 that use the <link linkend='var-B'><filename>B</filename></link>
713 variable to point to the directory in which the OpenEmbedded build
714 system places the generated objects built from the recipes.
715 By default, the <filename>B</filename> directory is set to the
716 following, which is separate from the source directory
717 (<filename>S</filename>):
718 <literallayout class='monospaced'>
719 ${WORKDIR}/${BPN}/{PV}/
720 </literallayout>
721 See these variables for more information:
722 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
723 <link linkend='var-BPN'><filename>BPN</filename></link>, and
724 <link linkend='var-PV'><filename>PV</filename></link>,
725 </para>
726
727 <para>
728 For more information on the
729 <filename>externalsrc</filename> class, see the comments in
730 <filename>meta/classes/externalsrc.bbclass</filename> in the
731 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
732 For information on how to use the <filename>externalsrc</filename>
733 class, see the
734 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
735 section in the Yocto Project Development Manual.
736 </para>
737</section>
738
739<section id='ref-classes-extrausers'>
740 <title><filename>extrausers.bbclass</filename></title>
741
742 <para>
743 The <filename>extrausers</filename> class allows
744 additional user and group configuration to be applied at the image
745 level.
746 Inheriting this class either globally or from an image recipe allows
747 additional user and group operations to be performed using the
748 <link linkend='var-EXTRA_USERS_PARAMS'><filename>EXTRA_USERS_PARAMS</filename></link>
749 variable.
750 <note>
751 The user and group operations added using the
752 <filename>extrausers</filename> class are not tied to a specific
753 recipe outside of the recipe for the image.
754 Thus, the operations can be performed across the image as a whole.
755 Use the
756 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
757 class to add user and group configuration to a specific recipe.
758 </note>
759 Here is an example that uses this class in an image recipe:
760 <literallayout class='monospaced'>
761 inherit extrausers
762 EXTRA_USERS_PARAMS = "\
763 useradd -p '' tester; \
764 groupadd developers; \
765 userdel nobody; \
766 groupdel -g video; \
767 groupmod -g 1020 developers; \
768 usermod -s /bin/sh tester; \
769 "
770 </literallayout>
771 Here is an example that adds two users named "tester-jim" and
772 "tester-sue" and assigns passwords:
773 <literallayout class='monospaced'>
774 inherit extrausers
775 EXTRA_USERS_PARAMS = "\
776 useradd -P tester01 tester-jim; \
777 useradd -P tester01 tester-sue; \
778 "
779 </literallayout>
780 Finally, here is an example that sets the root password to
781 "1876*18":
782 <literallayout class='monospaced'>
783 inherit extrausers
784 EXTRA_USERS_PARAMS = "\
785 useradd -P 1876*18 root; \
786 "
787 </literallayout>
788 </para>
789</section>
790
791<section id='ref-classes-fontcache'>
792 <title><filename>fontcache.bbclass</filename></title>
793
794 <para>
795 The <filename>fontcache</filename> class generates the
796 proper post-install and post-remove (postinst and postrm)
797 scriptlets for font packages.
798 These scriptlets call <filename>fc-cache</filename> (part of
799 <filename>Fontconfig</filename>) to add the fonts to the font
800 information cache.
801 Since the cache files are architecture-specific,
802 <filename>fc-cache</filename> runs using QEMU if the postinst
803 scriptlets need to be run on the build host during image creation.
804 </para>
805
806 <para>
807 If the fonts being installed are in packages other than the main
808 package, set
809 <link linkend='var-FONT_PACKAGES'><filename>FONT_PACKAGES</filename></link>
810 to specify the packages containing the fonts.
811 </para>
812</section>
813
814<section id='ref-classes-gconf'>
815 <title><filename>gconf.bbclass</filename></title>
816
817 <para>
818 The <filename>gconf</filename> class provides common
819 functionality for recipes that need to install GConf schemas.
820 The schemas will be put into a separate package
821 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-gconf</filename>)
822 that is created automatically when this class is inherited.
823 This package uses the appropriate post-install and post-remove
824 (postinst/postrm) scriptlets to register and unregister the schemas
825 in the target image.
826 </para>
827</section>
828
829<section id='ref-classes-gettext'>
830 <title><filename>gettext.bbclass</filename></title>
831
832 <para>
833 The <filename>gettext</filename> class provides support for
834 building software that uses the GNU <filename>gettext</filename>
835 internationalization and localization system.
836 All recipes building software that use
837 <filename>gettext</filename> should inherit this class.
838 </para>
839</section>
840
841<section id='ref-classes-gnome'>
842 <title><filename>gnome.bbclass</filename></title>
843
844 <para>
845 The <filename>gnome</filename> class supports recipes that
846 build software from the GNOME stack.
847 This class inherits the
848 <link linkend='ref-classes-gnomebase'><filename>gnomebase</filename></link>,
849 <link linkend='ref-classes-gtk-icon-cache'><filename>gtk-icon-cache</filename></link>,
850 <link linkend='ref-classes-gconf'><filename>gconf</filename></link> and
851 <link linkend='ref-classes-mime'><filename>mime</filename></link> classes.
852 The class also disables GObject introspection where applicable.
853 </para>
854</section>
855
856<section id='ref-classes-gnomebase'>
857 <title><filename>gnomebase.bbclass</filename></title>
858
859 <para>
860 The <filename>gnomebase</filename> class is the base
861 class for recipes that build software from the GNOME stack.
862 This class sets
863 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> to
864 download the source from the GNOME mirrors as well as extending
865 <link linkend='var-FILES'><filename>FILES</filename></link>
866 with the typical GNOME installation paths.
867 </para>
868</section>
869
870<section id='ref-classes-grub-efi'>
871 <title><filename>grub-efi.bbclass</filename></title>
872
873 <para>
874 The <filename>grub-efi</filename>
875 class provides <filename>grub-efi</filename>-specific functions for
876 building bootable images.
877 </para>
878
879 <para>
880 This class supports several variables:
881 <itemizedlist>
882 <listitem><para>
883 <link linkend='var-INITRD'><filename>INITRD</filename></link>:
884 Indicates a filesystem image to use as an initrd (optional).
885 </para></listitem>
886 <listitem><para>
887 <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
888 Indicates a filesystem image to include as the root filesystem
889 (optional).</para></listitem>
890 <listitem><para>
891 <link linkend='var-GRUB_GFXSERIAL'><filename>GRUB_GFXSERIAL</filename></link>:
892 Set this to "1" to have graphics and serial in the boot menu.
893 </para></listitem>
894 <listitem><para>
895 <link linkend='var-LABELS'><filename>LABELS</filename></link>:
896 A list of targets for the automatic configuration.
897 </para></listitem>
898 <listitem><para>
899 <link linkend='var-APPEND'><filename>APPEND</filename></link>:
900 An override list of append strings for each
901 <filename>LABEL</filename>.
902 </para></listitem>
903 <listitem><para>
904 <link linkend='var-GRUB_OPTS'><filename>GRUB_OPTS</filename></link>:
905 Additional options to add to the configuration (optional).
906 Options are delimited using semi-colon characters
907 (<filename>;</filename>).</para></listitem>
908 <listitem><para>
909 <link linkend='var-GRUB_TIMEOUT'><filename>GRUB_TIMEOUT</filename></link>:
910 Timeout before executing the default <filename>LABEL</filename>
911 (optional).
912 </para></listitem>
913 </itemizedlist>
914 </para>
915</section>
916
917<section id='ref-classes-gsettings'>
918 <title><filename>gsettings.bbclass</filename></title>
919
920 <para>
921 The <filename>gsettings</filename> class
922 provides common functionality for recipes that need to install
923 GSettings (glib) schemas.
924 The schemas are assumed to be part of the main package.
925 Appropriate post-install and post-remove (postinst/postrm)
926 scriptlets are added to register and unregister the schemas in the
927 target image.
928 </para>
929</section>
930
931<section id='ref-classes-gtk-doc'>
932 <title><filename>gtk-doc.bbclass</filename></title>
933
934 <para>
935 The <filename>gtk-doc</filename> class
936 is a helper class to pull in the appropriate
937 <filename>gtk-doc</filename> dependencies and disable
938 <filename>gtk-doc</filename>.
939 </para>
940</section>
941
942<section id='ref-classes-gtk-icon-cache'>
943 <title><filename>gtk-icon-cache.bbclass</filename></title>
944
945 <para>
946 The <filename>gtk-icon-cache</filename> class
947 generates the proper post-install and post-remove (postinst/postrm)
948 scriptlets for packages that use GTK+ and install icons.
949 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
950 the fonts to GTK+'s icon cache.
951 Since the cache files are architecture-specific,
952 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
953 postinst scriptlets need to be run on the build host during image
954 creation.
955 </para>
956</section>
957
958<section id='ref-classes-gtk-immodules-cache'>
959 <title><filename>gtk-immodules-cache.bbclass</filename></title>
960
961 <para>
962 The <filename>gtk-immodules-cache</filename> class
963 generates the proper post-install and post-remove (postinst/postrm)
964 scriptlets for packages that install GTK+ input method modules for
965 virtual keyboards.
966 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
967 the input method modules to the cache.
968 Since the cache files are architecture-specific,
969 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
970 postinst scriptlets need to be run on the build host during image
971 creation.
972 </para>
973
974 <para>
975 If the input method modules being installed are in packages other than
976 the main package, set
977 <link linkend='var-GTKIMMODULES_PACKAGES'><filename>GTKIMMODULES_PACKAGES</filename></link>
978 to specify the packages containing the modules.
979 </para>
980</section>
981
982<section id='ref-classes-gzipnative'>
983 <title><filename>gzipnative.bbclass</filename></title>
984
985 <para>
986 The <filename>gzipnative</filename>
987 class enables the use of native versions of <filename>gzip</filename>
988 and <filename>pigz</filename> rather than the versions of these tools
989 from the build host.
990 </para>
991</section>
992
993<section id='ref-classes-icecc'>
994 <title><filename>icecc.bbclass</filename></title>
995
996 <para>
997 The <filename>icecc</filename> class supports
998 <ulink url='https://github.com/icecc/icecream'>Icecream</ulink>, which
999 facilitates taking compile jobs and distributing them among remote
1000 machines.
1001 </para>
1002
1003 <para>
1004 The class stages directories with symlinks from <filename>gcc</filename>
1005 and <filename>g++</filename> to <filename>icecc</filename>, for both
1006 native and cross compilers.
1007 Depending on each configure or compile, the OpenEmbedded build system
1008 adds the directories at the head of the <filename>PATH</filename> list
1009 and then sets the <filename>ICECC_CXX</filename> and
1010 <filename>ICEC_CC</filename> variables, which are the paths to the
1011 <filename>g++</filename> and <filename>gcc</filename> compilers,
1012 respectively.
1013 </para>
1014
1015 <para>
1016 For the cross compiler, the class creates a <filename>tar.gz</filename>
1017 file that contains the Yocto Project toolchain and sets
1018 <filename>ICECC_VERSION</filename>, which is the version of the
1019 cross-compiler used in the cross-development toolchain, accordingly.
1020 </para>
1021
1022 <para>
1023 The class handles all three different compile stages
1024 (i.e native ,cross-kernel and target) and creates the necessary
1025 environment <filename>tar.gz</filename> file to be used by the remote
1026 machines.
1027 The class also supports SDK generation.
1028 </para>
1029
1030 <para>
1031 If <link linkend='var-ICECC_PATH'><filename>ICECC_PATH</filename></link>
1032 is not set in your <filename>local.conf</filename> file, then the
1033 class tries to locate the <filename>icecc</filename> binary
1034 using <filename>which</filename>.
1035
1036 If
1037 <link linkend='var-ICECC_ENV_EXEC'><filename>ICECC_ENV_EXEC</filename></link>
1038 is set in your <filename>local.conf</filename> file, the variable should
1039 point to the <filename>icecc-create-env</filename> script
1040 provided by the user.
1041 If you do not point to a user-provided script, the build system
1042 uses the default script provided by the recipe
1043 <filename>icecc-create-env-native.bb</filename>.
1044 <note>
1045 This script is a modified version and not the one that comes with
1046 <filename>icecc</filename>.
1047 </note>
1048 </para>
1049
1050 <para>
1051 If you do not want the Icecream distributed compile support to apply
1052 to specific recipes or classes, you can effectively "blacklist" them
1053 by listing the recipes and classes using the
1054 <link linkend='var-ICECC_USER_PACKAGE_BL'><filename>ICECC_USER_PACKAGE_BL</filename></link>
1055 and
1056 <link linkend='var-ICECC_USER_CLASS_BL'><filename>ICECC_USER_CLASS_BL</filename></link>,
1057 variables, respectively, in your <filename>local.conf</filename> file.
1058 Doing so causes the OpenEmbedded build system to handle these
1059 compilations locally.
1060 </para>
1061
1062 <para>
1063 Additionally, you can list recipes using the
1064 <link linkend='var-ICECC_USER_PACKAGE_WL'><filename>ICECC_USER_PACKAGE_WL</filename></link>
1065 variable in your <filename>local.conf</filename> file to force
1066 <filename>icecc</filename> to be enabled for recipes using an empty
1067 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
1068 variable.
1069 </para>
1070
1071 <para>
1072 Inheriting the <filename>icecc</filename> class changes all sstate
1073 signatures.
1074 Consequently, if a development team has a dedicated build system
1075 that populates
1076 <link linkend='var-SSTATE_MIRRORS'><filename>STATE_MIRRORS</filename></link>
1077 and they want to reuse sstate from
1078 <filename>STATE_MIRRORS</filename>, then all developers and the
1079 build system need to either inherit the <filename>icecc</filename>
1080 class or nobody should.
1081 </para>
1082
1083 <para>
1084 At the distribution level, you can inherit the
1085 <filename>icecc</filename> class to be sure that all builders start
1086 with the same sstate signatures.
1087 After inheriting the class, you can then disable the feature by setting
1088 the
1089 <link linkend='var-ICECC_DISABLED'><filename>ICECC_DISABLED</filename></link>
1090 variable to "1" as follows:
1091 <literallayout class='monospaced'>
1092 INHERIT_DISTRO += "icecc"
1093 ICECC_DISABLED ??= "1"
1094 </literallayout>
1095 This practice makes sure everyone is using the same signatures but also
1096 requires individuals that do want to use Icecream to enable the feature
1097 individually as follows in your <filename>local.conf</filename> file:
1098 <literallayout class='monospaced'>
1099 ICECC_DISABLED = ""
1100 </literallayout>
1101 </para>
1102</section>
1103
1104<section id='ref-classes-image'>
1105 <title><filename>image.bbclass</filename></title>
1106
1107 <para>
1108 The <filename>image</filename> class helps support creating images
1109 in different formats.
1110 First, the root filesystem is created from packages using
1111 one of the <filename>rootfs*.bbclass</filename>
1112 files (depending on the package format used) and then one or more image
1113 files are created.
1114 <itemizedlist>
1115 <listitem><para>The
1116 <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
1117 variable controls the types of images to generate.
1118 </para></listitem>
1119 <listitem><para>The
1120 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
1121 variable controls the list of packages to install into the
1122 image.</para></listitem>
1123 </itemizedlist>
1124 For information on customizing images, see the
1125 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>"
1126 section in the Yocto Project Development Manual.
1127 For information on how images are created, see the
1128 "<link linkend='images-dev-environment'>Images</link>" section elsewhere
1129 in this manual.
1130 </para>
1131</section>
1132
1133<section id='ref-classes-image_types'>
1134 <title><filename>image_types.bbclass</filename></title>
1135
1136 <para>
1137 The <filename>image_types</filename> class defines all of
1138 the standard image output types that you can enable through the
1139 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1140 variable.
1141 You can use this class as a reference on how to add support for custom
1142 image output types.
1143 </para>
1144
1145 <para>
1146 By default, this class is enabled through the
1147 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
1148 variable in
1149 <link linkend='ref-classes-image'><filename>image.bbclass</filename></link>.
1150 If you define your own image types using a custom BitBake class and
1151 then use <filename>IMAGE_CLASSES</filename> to enable it, the custom
1152 class must either inherit <filename>image_types</filename> or
1153 <filename>image_types</filename> must also appear in
1154 <filename>IMAGE_CLASSES</filename>.
1155 </para>
1156</section>
1157
1158<section id='ref-classes-image_types_uboot'>
1159 <title><filename>image_types_uboot.bbclass</filename></title>
1160
1161 <para>
1162 The <filename>image_types_uboot</filename> class
1163 defines additional image types specifically for the U-Boot bootloader.
1164 </para>
1165</section>
1166
1167<section id='ref-classes-image-live'>
1168 <title><filename>image-live.bbclass</filename></title>
1169
1170 <para>
1171 The <filename>image-live</filename> class supports building "live"
1172 images.
1173 </para>
1174
1175 <para>
1176 Normally, you do not use this class directly.
1177 Instead, you add "live" to
1178 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
1179 For example, if you were building an ISO image, you would add "live"
1180 to <filename>IMAGE_FSTYPES</filename>, set the
1181 <link linkend='var-NOISO'><filename>NOISO</filename></link> variable to
1182 "0" and the build system would use the <filename>image-live</filename>
1183 class to build the ISO image.
1184 </para>
1185</section>
1186
1187<section id='ref-classes-image-mklibs'>
1188 <title><filename>image-mklibs.bbclass</filename></title>
1189
1190 <para>
1191 The <filename>image-mklibs</filename> class
1192 enables the use of the <filename>mklibs</filename> utility during the
1193 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1194 task, which optimizes the size of
1195 libraries contained in the image.
1196 </para>
1197
1198 <para>
1199 By default, the class is enabled in the
1200 <filename>local.conf.template</filename> using the
1201 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1202 variable as follows:
1203 <literallayout class='monospaced'>
1204 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1205 </literallayout>
1206 </para>
1207</section>
1208
1209<section id='ref-classes-image-prelink'>
1210 <title><filename>image-prelink.bbclass</filename></title>
1211
1212 <para>
1213 The <filename>image-prelink</filename> class
1214 enables the use of the <filename>prelink</filename> utility during
1215 the
1216 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1217 task, which optimizes the dynamic
1218 linking of shared libraries to reduce executable startup time.
1219 </para>
1220
1221 <para>
1222 By default, the class is enabled in the
1223 <filename>local.conf.template</filename> using the
1224 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1225 variable as follows:
1226 <literallayout class='monospaced'>
1227 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1228 </literallayout>
1229 </para>
1230</section>
1231
1232<section id='ref-classes-image-swab'>
1233 <title><filename>image-swab.bbclass</filename></title>
1234
1235 <para>
1236 The <filename>image-swab</filename> class enables the
1237 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/swabber'>Swabber</ulink>
1238 tool in order to detect and log accesses to the host system during
1239 the OpenEmbedded build process.
1240 <note>
1241 This class is currently unmaintained.
1242 </note>
1243 </para>
1244</section>
1245
1246<section id='ref-classes-image-vmdk'>
1247 <title><filename>image-vmdk.bbclass</filename></title>
1248
1249 <para>
1250 The <filename>image-vmdk</filename> class supports building VMware
1251 VMDK images.
1252 Normally, you do not use this class directly.
1253 Instead, you add "vmdk" to
1254 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
1255 </para>
1256</section>
1257
1258<section id='ref-classes-insane'>
1259 <title><filename>insane.bbclass</filename></title>
1260
1261 <para>
1262 The <filename>insane</filename> class adds a step to the package
1263 generation process so that output quality assurance checks are
1264 generated by the OpenEmbedded build system.
1265 A range of checks are performed that check the build's output
1266 for common problems that show up during runtime.
1267 Distribution policy usually dictates whether to include this class.
1268 </para>
1269
1270 <para>
1271 You can configure the sanity checks so that specific test failures
1272 either raise a warning or an error message.
1273 Typically, failures for new tests generate a warning.
1274 Subsequent failures for the same test would then generate an error
1275 message once the metadata is in a known and good condition.
1276 See the
1277 "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
1278 Chapter for a list of all the warning and error messages
1279 you might encounter using a default configuration.
1280 </para>
1281
1282 <para>
1283 Use the
1284 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
1285 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
1286 variables to control the behavior of
1287 these checks at the global level (i.e. in your custom distro
1288 configuration).
1289 However, to skip one or more checks in recipes, you should use
1290 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
1291 For example, to skip the check for symbolic link
1292 <filename>.so</filename> files in the main package of a recipe,
1293 add the following to the recipe.
1294 You need to realize that the package name override, in this example
1295 <filename>${PN}</filename>, must be used:
1296 <literallayout class='monospaced'>
1297 INSANE_SKIP_${PN} += "dev-so"
1298 </literallayout>
1299 Please keep in mind that the QA checks exist in order to detect real
1300 or potential problems in the packaged output.
1301 So exercise caution when disabling these checks.
1302 </para>
1303
1304 <para>
1305 The following list shows the tests you can list with the
1306 <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
1307 variables:
1308 <itemizedlist>
1309 <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
1310 Checks that produced binaries have not already been
1311 stripped prior to the build system extracting debug symbols.
1312 It is common for upstream software projects to default to
1313 stripping debug symbols for output binaries.
1314 In order for debugging to work on the target using
1315 <filename>-dbg</filename> packages, this stripping must be
1316 disabled.
1317 </para></listitem>
1318 <listitem><para><emphasis><filename>arch:</filename></emphasis>
1319 Checks the Executable and Linkable Format (ELF) type, bit size,
1320 and endianness of any binaries to ensure they match the target
1321 architecture.
1322 This test fails if any binaries do not match the type since
1323 there would be an incompatibility.
1324 The test could indicate that the
1325 wrong compiler or compiler options have been used.
1326 Sometimes software, like bootloaders, might need to bypass
1327 this check.
1328 </para></listitem>
1329 <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
1330 Checks for paths to locations on the build host inside the
1331 output files.
1332 Currently, this test triggers too many false positives and
1333 thus is not normally enabled.
1334 </para></listitem>
1335 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
1336 Checks the
1337 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
1338 log for indications
1339 that paths to locations on the build host were used.
1340 Using such paths might result in host contamination of the
1341 build output.
1342 </para></listitem>
1343 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
1344 Checks that all packages except <filename>-dbg</filename>
1345 packages do not depend on <filename>-dbg</filename>
1346 packages, which would cause a packaging bug.
1347 </para></listitem>
1348 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
1349 Checks for <filename>.debug</filename> directories in anything but the
1350 <filename>-dbg</filename> package.
1351 The debug files should all be in the <filename>-dbg</filename> package.
1352 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
1353 <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
1354 Checks for invalid version comparison statements in runtime
1355 dependency relationships between packages (i.e. in
1356 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1357 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1358 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1359 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1360 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1361 and
1362 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
1363 variable values).
1364 Any invalid comparisons might trigger failures or undesirable
1365 behavior when passed to the package manager.
1366 </para></listitem>
1367 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
1368 Runs the <filename>desktop-file-validate</filename> program
1369 against any <filename>.desktop</filename> files to validate
1370 their contents against the specification for
1371 <filename>.desktop</filename> files.</para></listitem>
1372 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
1373 Checks that all packages except <filename>-dev</filename>
1374 or <filename>-staticdev</filename> packages do not depend on
1375 <filename>-dev</filename> packages, which would be a
1376 packaging bug.</para></listitem>
1377 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
1378 Checks that the <filename>.so</filename> symbolic links are in the
1379 <filename>-dev</filename> package and not in any of the other packages.
1380 In general, these symlinks are only useful for development purposes.
1381 Thus, the <filename>-dev</filename> package is the correct location for
1382 them.
1383 Some very rare cases do exist for dynamically loaded modules where
1384 these symlinks are needed instead in the main package.
1385 </para></listitem>
1386 <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
1387 Checks for
1388 <link linkend='var-FILES'><filename>FILES</filename></link>
1389 variable values that contain "//", which is invalid.
1390 </para></listitem>
1391 <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
1392 Report when packages are excluded from being created due to
1393 being marked with a license that is in
1394 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
1395 </para></listitem>
1396 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
1397 Checks the
1398 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1399 log for indications
1400 that paths to locations on the build host were used.
1401 Using such paths might result in host contamination of the
1402 build output.
1403 </para></listitem>
1404 <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
1405 Reports when files have been installed within
1406 <filename>do_install</filename> but have not been included in
1407 any package by way of the
1408 <link linkend='var-FILES'><filename>FILES</filename></link>
1409 variable.
1410 Files that do not appear in any package cannot be present in
1411 an image later on in the build process.
1412 Ideally, all installed files should be packaged or not
1413 installed at all.
1414 These files can be deleted at the end of
1415 <filename>do_install</filename> if the files are not
1416 needed in any package.
1417 </para></listitem>
1418 <listitem><para><emphasis><filename>la:</filename></emphasis>
1419 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
1420 paths.
1421 Any <filename>.la</filename> file containing these paths is incorrect since
1422 <filename>libtool</filename> adds the correct sysroot prefix when using the
1423 files automatically itself.</para></listitem>
1424 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
1425 Ensures that the binaries were linked with the
1426 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1427 options provided by the build system.
1428 If this test fails, check that the <filename>LDFLAGS</filename> variable
1429 is being passed to the linker command.</para></listitem>
1430 <listitem><para><emphasis><filename>libdir:</filename></emphasis>
1431 Checks for libraries being installed into incorrect
1432 (possibly hardcoded) installation paths.
1433 For example, this test will catch recipes that install
1434 <filename>/lib/bar.so</filename> when
1435 <filename>${base_libdir}</filename> is "lib32".
1436 Another example is when recipes install
1437 <filename>/usr/lib64/foo.so</filename> when
1438 <filename>${libdir}</filename> is "/usr/lib".
1439 </para></listitem>
1440 <listitem><para><emphasis><filename>libexec:</filename></emphasis>
1441 Checks if a package contains files in
1442 <filename>/usr/libexec</filename>.
1443 This check is not performed if the
1444 <filename>libexecdir</filename> variable has been set
1445 explicitly to <filename>/usr/libexec</filename>.
1446 </para></listitem>
1447 <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
1448 Checks for the same package being listed multiple times through
1449 the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1450 variable value.
1451 Installing the package in this manner can cause errors during
1452 packaging.
1453 </para></listitem>
1454 <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
1455 Reports lines in <filename>fs-perms.txt</filename> that have
1456 an invalid format.
1457 </para></listitem>
1458 <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
1459 Reports lines in <filename>fs-perms.txt</filename> that have
1460 an invalid format.
1461 </para></listitem>
1462 <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
1463 Reports lines in <filename>fs-perms.txt</filename> that
1464 specify 'link' where the specified target already exists.
1465 </para></listitem>
1466 <listitem><para><emphasis><filename>perms:</filename></emphasis>
1467 Currently, this check is unused but reserved.
1468 </para></listitem>
1469 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
1470 Checks <filename>.pc</filename> files for any
1471 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
1472 paths.
1473 Any <filename>.pc</filename> file containing these paths is incorrect
1474 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
1475 when the files are accessed.</para></listitem>
1476 <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
1477 Checks that all packages in
1478 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1479 have names that do not contain invalid characters (i.e.
1480 characters other than 0-9, a-z, ., +, and -).
1481 </para></listitem>
1482 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
1483 Checks to see if the <filename>PKGV</filename> variable
1484 is undefined during
1485 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1486 </para></listitem>
1487 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
1488 Checks through the variables
1489 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1490 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1491 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1492 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
1493 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1494 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1495 <link linkend='var-FILES'><filename>FILES</filename></link>,
1496 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
1497 <filename>pkg_preinst</filename>,
1498 <filename>pkg_postinst</filename>,
1499 <filename>pkg_prerm</filename>
1500 and <filename>pkg_postrm</filename>, and reports if there are
1501 variable sets that are not package-specific.
1502 Using these variables without a package suffix is bad practice,
1503 and might unnecessarily complicate dependencies of other packages
1504 within the same recipe or have other unintended consequences.
1505 </para></listitem>
1506 <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
1507 Checks that a recipe does not have a name
1508 (<link linkend='var-PN'><filename>PN</filename></link>) value
1509 that appears in
1510 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
1511 If a recipe is named such that its <filename>PN</filename>
1512 value matches something already in
1513 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
1514 happens to be the same as
1515 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
1516 or
1517 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
1518 it can have unexpected consequences.
1519 For example, assignments such as
1520 <filename>FILES_${PN} = "xyz"</filename> effectively turn into
1521 <filename>FILES = "xyz"</filename>.
1522 </para></listitem>
1523 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
1524 Checks for rpaths in the binaries that contain build system paths such
1525 as <filename>TMPDIR</filename>.
1526 If this test fails, bad <filename>-rpath</filename> options are being
1527 passed to the linker commands and your binaries have potential security
1528 issues.</para></listitem>
1529 <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
1530 Reports that splitting or stripping debug symbols from binaries
1531 has failed.
1532 </para></listitem>
1533 <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
1534 Checks for static library files (<filename>*.a</filename>) in
1535 non-<filename>staticdev</filename> packages.
1536 </para></listitem>
1537 <listitem><para><emphasis><filename>symlink-to-sysroot:</filename></emphasis>
1538 Checks for symlinks in packages that point into
1539 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1540 on the host.
1541 Such symlinks will work on the host, but are clearly invalid
1542 when running on the target.
1543 </para></listitem>
1544 <listitem><para><emphasis><filename>textrel:</filename></emphasis>
1545 Checks for ELF binaries that contain relocations in their
1546 <filename>.text</filename> sections, which can result in a
1547 performance impact at runtime.</para></listitem>
1548 <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
1549 Reports when a binary installed in
1550 <filename>${base_libdir}</filename>,
1551 <filename>${base_bindir}</filename>, or
1552 <filename>${base_sbindir}</filename>, depends on another
1553 binary installed under <filename>${exec_prefix}</filename>.
1554 This dependency is a concern if you want the system to remain
1555 basically operable if <filename>/usr</filename> is mounted
1556 separately and is not mounted.
1557 <note>
1558 Defaults for binaries installed in
1559 <filename>${base_libdir}</filename>,
1560 <filename>${base_bindir}</filename>, and
1561 <filename>${base_sbindir}</filename> are
1562 <filename>/lib</filename>, <filename>/bin</filename>, and
1563 <filename>/sbin</filename>, respectively.
1564 The default for a binary installed
1565 under <filename>${exec_prefix}</filename> is
1566 <filename>/usr</filename>.
1567 </note>
1568 </para></listitem>
1569 <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis>
1570 Reports when a script file installed in
1571 <filename>${base_libdir}</filename>,
1572 <filename>${base_bindir}</filename>, or
1573 <filename>${base_sbindir}</filename>, depends on files
1574 installed under <filename>${exec_prefix}</filename>.
1575 This dependency is a concern if you want the system to remain
1576 basically operable if <filename>/usr</filename> is mounted
1577 separately and is not mounted.
1578 <note>
1579 Defaults for binaries installed in
1580 <filename>${base_libdir}</filename>,
1581 <filename>${base_bindir}</filename>, and
1582 <filename>${base_sbindir}</filename> are
1583 <filename>/lib</filename>, <filename>/bin</filename>, and
1584 <filename>/sbin</filename>, respectively.
1585 The default for a binary installed
1586 under <filename>${exec_prefix}</filename> is
1587 <filename>/usr</filename>.
1588 </note>
1589 </para></listitem>
1590 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
1591 Checks for dynamic library load paths (rpaths) in the binaries that
1592 by default on a standard system are searched by the linker (e.g.
1593 <filename>/lib</filename> and <filename>/usr/lib</filename>).
1594 While these paths will not cause any breakage, they do waste space and
1595 are unnecessary.</para></listitem>
1596 <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
1597 Reports when variables fundamental to packaging (i.e.
1598 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
1599 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
1600 <link linkend='var-D'><filename>D</filename></link>,
1601 <link linkend='var-PN'><filename>PN</filename></link>, and
1602 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
1603 undefined during
1604 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1605 </para></listitem>
1606 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
1607 If Build History is enabled, reports when a package
1608 being written out has a lower version than the previously
1609 written package under the same name.
1610 If you are placing output packages into a feed and
1611 upgrading packages on a target system using that feed, the
1612 version of a package going backwards can result in the target
1613 system not correctly upgrading to the "new" version of the
1614 package.
1615 <note>
1616 If you are not using runtime package management on your
1617 target system, then you do not need to worry about
1618 this situation.
1619 </note>
1620 </para></listitem>
1621 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
1622 Checks that all packages containing Xorg drivers have ABI
1623 dependencies.
1624 The <filename>xserver-xorg</filename> recipe provides driver
1625 ABI names.
1626 All drivers should depend on the ABI versions that they have
1627 been built against.
1628 Driver recipes that include
1629 <filename>xorg-driver-input.inc</filename>
1630 or <filename>xorg-driver-video.inc</filename> will
1631 automatically get these versions.
1632 Consequently, you should only need to explicitly add
1633 dependencies to binary driver recipes.
1634 </para></listitem>
1635 </itemizedlist>
1636 </para>
1637</section>
1638
1639<section id='ref-classes-insserv'>
1640 <title><filename>insserv.bbclass</filename></title>
1641
1642 <para>
1643 The <filename>insserv</filename> class
1644 uses the <filename>insserv</filename> utility to update the order of
1645 symbolic links in <filename>/etc/rc?.d/</filename> within an image
1646 based on dependencies specified by LSB headers in the
1647 <filename>init.d</filename> scripts themselves.
1648 </para>
1649</section>
1650
1651<section id='ref-classes-kernel'>
1652 <title><filename>kernel.bbclass</filename></title>
1653
1654 <para>
1655 The <filename>kernel</filename> class handles building Linux kernels.
1656 The class contains code to build all kernel trees.
1657 All needed headers are staged into the
1658 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
1659 directory to allow out-of-tree module builds using
1660 the
1661 <link linkend='ref-classes-module'><filename>module</filename></link>
1662 class.
1663 </para>
1664
1665 <para>
1666 This means that each built kernel module is packaged separately and inter-module
1667 dependencies are created by parsing the <filename>modinfo</filename> output.
1668 If all modules are required, then installing the <filename>kernel-modules</filename>
1669 package installs all packages with modules and various other kernel packages
1670 such as <filename>kernel-vmlinux</filename>.
1671 </para>
1672
1673 <para>
1674 Various other classes are used by the <filename>kernel</filename>
1675 and <filename>module</filename> classes internally including the
1676 <link linkend='ref-classes-kernel-arch'><filename>kernel-arch</filename></link>,
1677 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>,
1678 and
1679 <link linkend='ref-classes-linux-kernel-base'><filename>linux-kernel-base</filename></link>
1680 classes.
1681 </para>
1682</section>
1683
1684<section id='ref-classes-kernel-arch'>
1685 <title><filename>kernel-arch.bbclass</filename></title>
1686
1687 <para>
1688 The <filename>kernel-arch</filename> class
1689 sets the <filename>ARCH</filename> environment variable for Linux
1690 kernel compilation (including modules).
1691 </para>
1692</section>
1693
1694<section id='ref-classes-kernel-module-split'>
1695 <title><filename>kernel-module-split.bbclass</filename></title>
1696
1697 <para>
1698 The <filename>kernel-module-split</filename> class
1699 provides common functionality for splitting Linux kernel modules into
1700 separate packages.
1701 </para>
1702</section>
1703
1704<section id='ref-classes-kernel-yocto'>
1705 <title><filename>kernel-yocto.bbclass</filename></title>
1706
1707 <para>
1708 The <filename>kernel-yocto</filename> class
1709 provides common functionality for building from linux-yocto style
1710 kernel source repositories.
1711 </para>
1712</section>
1713
1714<section id='ref-classes-lib_package'>
1715 <title><filename>lib_package.bbclass</filename></title>
1716
1717 <para>
1718 The <filename>lib_package</filename> class
1719 supports recipes that build libraries and produce executable
1720 binaries, where those binaries should not be installed by default
1721 along with the library.
1722 Instead, the binaries are added to a separate
1723 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-bin</filename>
1724 package to make their installation optional.
1725 </para>
1726</section>
1727
1728<section id='ref-classes-license'>
1729 <title><filename>license.bbclass</filename></title>
1730
1731 <para>
1732 The <filename>license</filename> class provides license
1733 manifest creation and license exclusion.
1734 This class is enabled by default using the default value for the
1735 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
1736 variable.
1737 </para>
1738</section>
1739
1740<section id='ref-classes-linux-kernel-base'>
1741 <title><filename>linux-kernel-base.bbclass</filename></title>
1742
1743 <para>
1744 The <filename>linux-kernel-base</filename> class
1745 provides common functionality for recipes that build out of the Linux
1746 kernel source tree.
1747 These builds goes beyond the kernel itself.
1748 For example, the Perf recipe also inherits this class.
1749 </para>
1750</section>
1751
1752<section id='ref-classes-logging'>
1753 <title><filename>logging.bbclass</filename></title>
1754
1755 <para>
1756 The <filename>logging</filename> class provides the standard
1757 shell functions used to log messages for various BitBake severity levels
1758 (i.e. <filename>bbplain</filename>, <filename>bbnote</filename>,
1759 <filename>bbwarn</filename>, <filename>bberror</filename>,
1760 <filename>bbfatal</filename>, and <filename>bbdebug</filename>).
1761 </para>
1762
1763 <para>
1764 This class is enabled by default since it is inherited by
1765 the <filename>base</filename> class.
1766 </para>
1767</section>
1768
1769<section id='ref-classes-meta'>
1770 <title><filename>meta.bbclass</filename></title>
1771
1772 <para>
1773 The <filename>meta</filename> class is inherited by recipes
1774 that do not build any output packages themselves, but act as a "meta"
1775 target for building other recipes.
1776 </para>
1777</section>
1778
1779<section id='ref-classes-metadata_scm'>
1780 <title><filename>metadata_scm.bbclass</filename></title>
1781
1782 <para>
1783 The <filename>metadata_scm</filename> class provides functionality for
1784 querying the branch and revision of a Source Code Manager (SCM)
1785 repository.
1786 </para>
1787
1788 <para>
1789 The <link linkend='ref-classes-base'><filename>base</filename></link>
1790 class uses this class to print the revisions of each layer before
1791 starting every build.
1792 The <filename>metadata_scm</filename> class is enabled by default
1793 because it is inherited by the <filename>base</filename> class.
1794 </para>
1795</section>
1796
1797<section id='ref-classes-mime'>
1798 <title><filename>mime.bbclass</filename></title>
1799
1800 <para>
1801 The <filename>mime</filename> class generates the proper
1802 post-install and post-remove (postinst/postrm) scriptlets for packages
1803 that install MIME type files.
1804 These scriptlets call <filename>update-mime-database</filename> to add
1805 the MIME types to the shared database.
1806 </para>
1807</section>
1808
1809<section id='ref-classes-mirrors'>
1810 <title><filename>mirrors.bbclass</filename></title>
1811
1812 <para>
1813 The <filename>mirrors</filename> class sets up some standard
1814 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> entries
1815 for source code mirrors.
1816 These mirrors provide a fall-back path in case the upstream source
1817 specified in
1818 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
1819 within recipes is unavailable.
1820 </para>
1821
1822 <para>
1823 This class is enabled by default since it is inherited by the
1824 <link linkend='ref-classes-base'><filename>base</filename></link> class.
1825 </para>
1826</section>
1827
1828<section id='ref-classes-module'>
1829 <title><filename>module.bbclass</filename></title>
1830
1831 <para>
1832 The <filename>module</filename> class provides support for building
1833 out-of-tree Linux kernel modules.
1834 The class inherits the
1835 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>
1836 and
1837 <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link>
1838 classes, and implements the
1839 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
1840 and
1841 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1842 tasks.
1843 The class provides everything needed to build and package a kernel
1844 module.
1845 </para>
1846
1847 <para>
1848 For general information on out-of-tree Linux kernel modules, see the
1849 "<ulink url='&YOCTO_DOCS_KERNEL_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
1850 section in the Yocto Project Linux Kernel Development Manual.
1851 </para>
1852</section>
1853
1854<section id='ref-classes-module-base'>
1855 <title><filename>module-base.bbclass</filename></title>
1856
1857 <para>
1858 The <filename>module-base</filename> class provides the base
1859 functionality for building Linux kernel modules.
1860 Typically, a recipe that builds software that includes one or
1861 more kernel modules and has its own means of building
1862 the module inherits this class as opposed to inheriting the
1863 <link linkend='ref-classes-module'><filename>module</filename></link>
1864 class.
1865 </para>
1866</section>
1867
1868<section id='ref-classes-multilib*'>
1869 <title><filename>multilib*.bbclass</filename></title>
1870
1871 <para>
1872 The <filename>multilib*</filename> classes provide support
1873 for building libraries with different target optimizations or target
1874 architectures and installing them side-by-side in the same image.
1875 </para>
1876
1877 <para>
1878 For more information on using the Multilib feature, see the
1879 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
1880 section in the Yocto Project Development Manual.
1881 </para>
1882</section>
1883
1884<section id='ref-classes-native'>
1885 <title><filename>native.bbclass</filename></title>
1886
1887 <para>
1888 The <filename>native</filename> class provides common
1889 functionality for recipes that wish to build tools to run on the build
1890 host (i.e. tools that use the compiler or other tools from the
1891 build host).
1892 </para>
1893
1894 <para>
1895 You can create a recipe that builds tools that run natively on the
1896 host a couple different ways:
1897 <itemizedlist>
1898 <listitem><para>Create a <filename>myrecipe-native.bb</filename>
1899 that inherits the <filename>native</filename> class.
1900 If you use this method, you must order the inherit statement
1901 in the recipe after all other inherit statements so that the
1902 <filename>native</filename> class is inherited last.
1903 </para></listitem>
1904 <listitem><para>Create or modify a target recipe that has adds
1905 the following:
1906 <literallayout class='monospaced'>
1907 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "native"
1908 </literallayout>
1909 Inside the recipe, use <filename>_class-native</filename> and
1910 <filename>_class-target</filename> overrides to specify any
1911 functionality specific to the respective native or target
1912 case.</para></listitem>
1913 </itemizedlist>
1914 </para>
1915
1916 <para>
1917 Although applied differently, the <filename>native</filename> class is
1918 used with both methods.
1919 The advantage of the second method is that you do not need to have two
1920 separate recipes (assuming you need both) for native and target.
1921 All common parts of the recipe are automatically shared.
1922 </para>
1923</section>
1924
1925<section id='ref-classes-nativesdk'>
1926 <title><filename>nativesdk.bbclass</filename></title>
1927
1928 <para>
1929 The <filename>nativesdk</filename> class provides common
1930 functionality for recipes that wish to build tools to run as part of
1931 an SDK (i.e. tools that run on
1932 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>).
1933 </para>
1934
1935 <para>
1936 You can create a recipe that builds tools that run on the SDK machine
1937 a couple different ways:
1938 <itemizedlist>
1939 <listitem><para>Create a <filename>myrecipe-nativesdk.bb</filename>
1940 recipe that inherits the <filename>nativesdk</filename> class.
1941 If you use this method, you must order the inherit statement
1942 in the recipe after all other inherit statements so that the
1943 <filename>nativesdk</filename> class is inherited last.
1944 </para></listitem>
1945 <listitem><para>Create a <filename>nativesdk</filename> variant
1946 of any recipe by adding the following:
1947 <literallayout class='monospaced'>
1948 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "nativesdk"
1949 </literallayout>
1950 Inside the recipe, use <filename>_class-nativesdk</filename> and
1951 <filename>_class-target</filename> overrides to specify any
1952 functionality specific to the respective SDK machine or target
1953 case.</para></listitem>
1954 </itemizedlist>
1955 </para>
1956
1957 <para>
1958 Although applied differently, the <filename>nativesdk</filename> class
1959 is used with both methods.
1960 The advantage of the second method is that you do not need to have two
1961 separate recipes (assuming you need both) for the SDK machine and the
1962 target.
1963 All common parts of the recipe are automatically shared.
1964 </para>
1965</section>
1966
1967<section id='ref-classes-oelint'>
1968 <title><filename>oelint.bbclass</filename></title>
1969
1970 <para>
1971 The <filename>oelint</filename> class is an
1972 obsolete lint checking tool that exists in
1973 <filename>meta/classes</filename> in the
1974 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1975 </para>
1976
1977 <para>
1978 A number of classes exist that are could be generally useful in
1979 OE-Core but are never actually used within OE-Core itself.
1980 The <filename>oelint</filename> class is one such example.
1981 However, being aware of this class can reduce the proliferation of
1982 different versions of similar classes across multiple layers.
1983 </para>
1984</section>
1985
1986<section id='ref-classes-own-mirrors'>
1987 <title><filename>own-mirrors.bbclass</filename></title>
1988
1989 <para>
1990 The <filename>own-mirrors</filename> class makes it
1991 easier to set up your own
1992 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
1993 from which to first fetch source before attempting to fetch it from the
1994 upstream specified in
1995 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
1996 within each recipe.
1997 </para>
1998
1999 <para>
2000 To use this class, inherit it globally and specify
2001 <link linkend='var-SOURCE_MIRROR_URL'><filename>SOURCE_MIRROR_URL</filename></link>.
2002 Here is an example:
2003 <literallayout class='monospaced'>
2004 INHERIT += "own-mirrors"
2005 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
2006 </literallayout>
2007 You can specify only a single URL in
2008 <filename>SOURCE_MIRROR_URL</filename>.
2009 </para>
2010</section>
2011
2012<section id='ref-classes-package'>
2013 <title><filename>package.bbclass</filename></title>
2014
2015 <para>
2016 The <filename>package</filename> class supports generating
2017 packages from a build's output.
2018 The core generic functionality is in
2019 <filename>package.bbclass</filename>.
2020 The code specific to particular package types resides in these
2021 package-specific classes:
2022 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
2023 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
2024 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
2025 and
2026 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>.
2027 </para>
2028
2029 <para>
2030 You can control the list of resulting package formats by using the
2031 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
2032 variable defined in your <filename>conf/local.conf</filename>
2033 configuration file, which is located in the
2034 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2035 When defining the variable, you can specify one or more package types.
2036 Since images are generated from packages, a packaging class is
2037 needed to enable image generation.
2038 The first class listed in this variable is used for image generation.
2039 </para>
2040
2041 <para>
2042 If you take the optional step to set up a repository (package feed)
2043 on the development host that can be used by Smart, you can
2044 install packages from the feed while you are running the image
2045 on the target (i.e. runtime installation of packages).
2046 For more information, see the
2047 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
2048 section in the Yocto Project Development Manual.
2049 </para>
2050
2051 <para>
2052 The package-specific class you choose can affect build-time performance
2053 and has space ramifications.
2054 In general, building a package with IPK takes about thirty percent less
2055 time as compared to using RPM to build the same or similar package.
2056 This comparison takes into account a complete build of the package with
2057 all dependencies previously built.
2058 The reason for this discrepancy is because the RPM package manager
2059 creates and processes more
2060 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the
2061 IPK package manager.
2062 Consequently, you might consider setting
2063 <filename>PACKAGE_CLASSES</filename> to "package_ipk" if you are
2064 building smaller systems.
2065 </para>
2066
2067 <para>
2068 Before making your package manager decision, however, you should
2069 consider some further things about using RPM:
2070 <itemizedlist>
2071 <listitem><para>
2072 RPM starts to provide more abilities than IPK due to
2073 the fact that it processes more Metadata.
2074 For example, this information includes individual file types,
2075 file checksum generation and evaluation on install, sparse file
2076 support, conflict detection and resolution for Multilib systems,
2077 ACID style upgrade, and repackaging abilities for rollbacks.
2078 </para></listitem>
2079 <listitem><para>
2080 For smaller systems, the extra space used for the Berkeley
2081 Database and the amount of metadata when using RPM can affect
2082 your ability to perform on-device upgrades.
2083 </para></listitem>
2084 </itemizedlist>
2085 </para>
2086
2087 <para>
2088 You can find additional information on the effects of the package
2089 class at these two Yocto Project mailing list links:
2090 <itemizedlist>
2091 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
2092 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
2093 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
2094 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
2095 </itemizedlist>
2096 </para>
2097</section>
2098
2099<section id='ref-classes-package_deb'>
2100 <title><filename>package_deb.bbclass</filename></title>
2101
2102 <para>
2103 The <filename>package_deb</filename> class
2104 provides support for creating packages that use the
2105 <filename>.deb</filename> file format.
2106 The class ensures the packages are written out to the
2107 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/deb</filename>
2108 directory in a <filename>.deb</filename> file format.
2109 </para>
2110
2111 <para>
2112 This class inherits the
2113 <link linkend='ref-classes-package'><filename>package</filename></link>
2114 class and is enabled through the
2115 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2116 variable in the <filename>local.conf</filename> file.
2117 </para>
2118</section>
2119
2120<section id='ref-classes-package_ipk'>
2121 <title><filename>package_ipk.bbclass</filename></title>
2122
2123 <para>
2124 The <filename>package_ipk</filename> class
2125 provides support for creating packages that use the
2126 <filename>.ipk</filename> file format.
2127 The class ensures the packages are written out to the
2128 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/ipk</filename>
2129 directory in a <filename>.ipk</filename> file format.
2130 </para>
2131
2132 <para>
2133 This class inherits the
2134 <link linkend='ref-classes-package'><filename>package</filename></link>
2135 class and is enabled through the
2136 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2137 variable in the <filename>local.conf</filename> file.
2138 </para>
2139</section>
2140
2141<section id='ref-classes-package_rpm'>
2142 <title><filename>package_rpm.bbclass</filename></title>
2143
2144 <para>
2145 The <filename>package_deb</filename> class
2146 provides support for creating packages that use the
2147 <filename>.rpm</filename> file format.
2148 The class ensures the packages are written out to the
2149 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/rpm</filename>
2150 directory in a <filename>.rpm</filename> file format.
2151 </para>
2152
2153 <para>
2154 This class inherits the
2155 <link linkend='ref-classes-package'><filename>package</filename></link>
2156 class and is enabled through the
2157 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2158 variable in the <filename>local.conf</filename> file.
2159 </para>
2160</section>
2161
2162<section id='ref-classes-package_tar'>
2163 <title><filename>package_tar.bbclass</filename></title>
2164
2165 <para>
2166 The <filename>package_tar</filename>
2167 class provides support for creating packages that use the
2168 <filename>.tar</filename> file format.
2169 The class ensures the packages are written out to the
2170 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/tar</filename>
2171 directory in a <filename>.tar</filename> file format.
2172 </para>
2173
2174 <para>
2175 This class inherits the
2176 <link linkend='ref-classes-package'><filename>package</filename></link>
2177 class and is enabled through the
2178 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2179 variable in the <filename>local.conf</filename> file.
2180 <note>
2181 You cannot specify the <filename>package_tar</filename> class
2182 first using the <filename>PACKAGE_CLASSES</filename> variable.
2183 You must use <filename>.deb</filename>,
2184 <filename>.ipk</filename>, or <filename>.rpm</filename> file
2185 formats for your image or SDK.
2186 </note>
2187 </para>
2188</section>
2189
2190<section id='ref-classes-packagedata'>
2191 <title><filename>packagedata.bbclass</filename></title>
2192
2193 <para>
2194 The <filename>packagedata</filename> class provides
2195 common functionality for reading <filename>pkgdata</filename> files
2196 found in
2197 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
2198 These files contain information about each output package produced by
2199 the OpenEmbedded build system.
2200 </para>
2201
2202 <para>
2203 This class is enabled by default because it is inherited by the
2204 <link linkend='ref-classes-package'><filename>package</filename></link>
2205 class.
2206 </para>
2207</section>
2208
2209<section id='ref-classes-packagegroup'>
2210 <title><filename>packagegroup.bbclass</filename></title>
2211
2212 <para>
2213 The <filename>packagegroup</filename> class sets default values
2214 appropriate for package group recipes (e.g.
2215 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
2216 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
2217 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
2218 and so forth).
2219 It is highly recommended that all package group recipes inherit this class.
2220 </para>
2221
2222 <para>
2223 For information on how to use this class, see the
2224 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
2225 section in the Yocto Project Development Manual.
2226 </para>
2227
2228 <para>
2229 Previously, this class was called the <filename>task</filename> class.
2230 </para>
2231</section>
2232
2233<section id='ref-classes-packageinfo'>
2234 <title><filename>packageinfo.bbclass</filename></title>
2235
2236 <para>
2237 The <filename>packageinfo</filename> class
2238 gives a BitBake user interface the ability to retrieve information
2239 about output packages from the <filename>pkgdata</filename> files.
2240 </para>
2241
2242 <para>
2243 This class is enabled automatically when using the
2244 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>
2245 user interface.
2246 </para>
2247</section>
2248
2249<section id='ref-classes-patch'>
2250 <title><filename>patch.bbclass</filename></title>
2251
2252 <para>
2253 The <filename>patch</filename> class provides all functionality for
2254 applying patches during the
2255 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
2256 task.
2257 </para>
2258
2259 <para>
2260 This class is enabled by default because it is inherited by the
2261 <link linkend='ref-classes-base'><filename>base</filename></link>
2262 class.
2263 </para>
2264</section>
2265
2266<section id='ref-classes-perlnative'>
2267 <title><filename>perlnative.bbclass</filename></title>
2268
2269 <para>
2270 When inherited by a recipe, the <filename>perlnative</filename> class
2271 supports using the native version of Perl built by the build system
2272 rather than using the version provided by the build host.
2273 </para>
2274</section>
2275
2276<section id='ref-classes-pixbufcache'>
2277 <title><filename>pixbufcache.bbclass</filename></title>
2278
2279 <para>
2280 The <filename>pixbufcache</filename> class generates the proper
2281 post-install and post-remove (postinst/postrm) scriptlets for packages
2282 that install pixbuf loaders, which are used with
2283 <filename>gdk-pixbuf</filename>.
2284 These scriptlets call <filename>update_pixbuf_cache</filename>
2285 to add the pixbuf loaders to the cache.
2286 Since the cache files are architecture-specific,
2287 <filename>update_pixbuf_cache</filename> is run using QEMU if the
2288 postinst scriptlets need to be run on the build host during image
2289 creation.
2290 </para>
2291
2292 <para>
2293 If the pixbuf loaders being installed are in packages other
2294 than the recipe's main package, set
2295 <link linkend='var-PIXBUF_PACKAGES'><filename>PIXBUF_PACKAGES</filename></link>
2296 to specify the packages containing the loaders.
2297 </para>
2298</section>
2299
2300<section id='ref-classes-pkgconfig'>
2301 <title><filename>pkgconfig.bbclass</filename></title>
2302
2303 <para>
2304 The <filename>pkg-config</filename> class provides a standard way to get
2305 header and library information.
2306 This class aims to smooth integration of
2307 <filename>pkg-config</filename> into libraries that use it.
2308 </para>
2309
2310 <para>
2311 During staging, BitBake installs <filename>pkg-config</filename> data into the
2312 <filename>sysroots/</filename> directory.
2313 By making use of sysroot functionality within <filename>pkg-config</filename>,
2314 this class no longer has to manipulate the files.
2315 </para>
2316</section>
2317
2318<section id='ref-classes-populate-sdk'>
2319 <title><filename>populate_sdk.bbclass</filename></title>
2320
2321 <para>
2322 The <filename>populate_sdk</filename> class provides support for
2323 SDK-only recipes.
2324 For information on advantages gained when building a cross-development
2325 toolchain using the
2326 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2327 task, see the
2328 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
2329 section in the Yocto Project Application Developer's Guide.
2330 </para>
2331</section>
2332
2333<section id='ref-classes-populate-sdk-*'>
2334 <title><filename>populate_sdk_*.bbclass</filename></title>
2335
2336 <para>
2337 The <filename>populate_sdk_*</filename> classes support SDK creation
2338 and consist of the following classes:
2339 <itemizedlist>
2340 <listitem><para><emphasis><filename>populate_sdk_base</filename>:</emphasis>
2341 The base class supporting SDK creation under all package
2342 managers (i.e. DEB, RPM, and IPK).</para></listitem>
2343 <listitem><para><emphasis><filename>populate_sdk_deb</filename>:</emphasis>
2344 Supports creation of the SDK given the Debian package manager.
2345 </para></listitem>
2346 <listitem><para><emphasis><filename>populate_sdk_rpm</filename>:</emphasis>
2347 Supports creation of the SDK given the RPM package manager.
2348 </para></listitem>
2349 <listitem><para><emphasis><filename>populate_sdk_ipk</filename>:</emphasis>
2350 Supports creation of the SDK given the IPK package manager.
2351 </para></listitem>
2352 </itemizedlist>
2353 </para>
2354
2355 <para>
2356 The <filename>populate_sdk_base</filename> package inherits the
2357 appropriate <filename>populate_sdk_*</filename> (i.e.
2358 <filename>deb</filename>, <filename>rpm</filename>, and
2359 <filename>ipk</filename>) based on
2360 <link linkend='var-IMAGE_PKGTYPE'><filename>IMAGE_PKGTYPE</filename></link>.
2361 </para>
2362
2363 <para>
2364 The base class ensures all source and destination directories are
2365 established and then populates the SDK.
2366 After populating the SDK, the <filename>populate_sdk_base</filename>
2367 class constructs two images:
2368 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>-nativesdk</filename>,
2369 which contains the cross-compiler and associated tooling, and the
2370 target, which contains a target root filesystem that is configured for
2371 the SDK usage.
2372 These two images reside in
2373 <link linkend='var-SDK_OUTPUT'><filename>SDK_OUTPUT</filename></link>,
2374 which consists of the following:
2375 <literallayout class='monospaced'>
2376 ${SDK_OUTPUT}/&lt;sdk_arch-nativesdk pkgs&gt;
2377 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/&lt;target pkgs&gt;
2378 </literallayout>
2379 </para>
2380
2381 <para>
2382 Finally, the base populate SDK class creates the toolchain
2383 environment setup script, the tarball of the SDK, and the installer.
2384 </para>
2385
2386 <para>
2387 The respective <filename>populate_sdk_deb</filename>,
2388 <filename>populate_sdk_rpm</filename>, and
2389 <filename>populate_sdk_ipk</filename> classes each support the
2390 specific type of SDK.
2391 These classes are inherited by and used with the
2392 <filename>populate_sdk_base</filename> class.
2393 </para>
2394
2395 <para>
2396 For more information on the cross-development toolchain
2397 generation, see the
2398 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
2399 section.
2400 For information on advantages gained when building a
2401 cross-development toolchain using the
2402 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2403 task, see the
2404 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
2405 section in the Yocto Project Application Developer's Guide.
2406 </para>
2407</section>
2408
2409<section id='ref-classes-prexport'>
2410 <title><filename>prexport.bbclass</filename></title>
2411
2412 <para>
2413 The <filename>prexport</filename> class provides functionality for
2414 exporting
2415 <link linkend='var-PR'><filename>PR</filename></link> values.
2416 <note>
2417 This class is not intended to be used directly.
2418 Rather, it is enabled when using
2419 "<filename>bitbake-prserv-tool export</filename>".
2420 </note>
2421 </para>
2422</section>
2423
2424<section id='ref-classes-primport'>
2425 <title><filename>primport.bbclass</filename></title>
2426
2427 <para>
2428 The <filename>primport</filename> class provides functionality for
2429 importing
2430 <link linkend='var-PR'><filename>PR</filename></link> values.
2431 <note>
2432 This class is not intended to be used directly.
2433 Rather, it is enabled when using
2434 "<filename>bitbake-prserv-tool import</filename>".
2435 </note>
2436 </para>
2437</section>
2438
2439<section id='ref-classes-prserv'>
2440 <title><filename>prserv.bbclass</filename></title>
2441
2442 <para>
2443 The <filename>prserv</filename> class provides functionality for
2444 using a
2445 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>
2446 in order to automatically manage the incrementing of the
2447 <link linkend='var-PR'><filename>PR</filename></link> variable for
2448 each recipe.
2449 </para>
2450
2451 <para>
2452 This class is enabled by default because it is inherited by the
2453 <link linkend='ref-classes-package'><filename>package</filename></link>
2454 class.
2455 However, the OpenEmbedded build system will not enable the
2456 functionality of this class unless
2457 <link linkend='var-PRSERV_HOST'><filename>PRSERV_HOST</filename></link>
2458 has been set.
2459 </para>
2460</section>
2461
2462<section id='ref-classes-ptest'>
2463 <title><filename>ptest.bbclass</filename></title>
2464
2465 <para>
2466 The <filename>ptest</filename> class provides functionality for
2467 packaging and installing runtime tests for recipes that build software
2468 that provides these tests.
2469 </para>
2470
2471 <para>
2472 This class is intended to be inherited by individual recipes.
2473 However, the class' functionality is largely disabled unless "ptest"
2474 appears in
2475 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2476 See the
2477 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
2478 section in the Yocto Project Development Manual for more information
2479 on ptest.
2480 </para>
2481</section>
2482
2483<section id='ref-classes-python-dir'>
2484 <title><filename>python-dir.bbclass</filename></title>
2485
2486 <para>
2487 The <filename>python-dir</filename> class provides the base version,
2488 location, and site package location for Python.
2489 </para>
2490</section>
2491
2492<section id='ref-classes-pythonnative'>
2493 <title><filename>pythonnative.bbclass</filename></title>
2494
2495 <para>
2496 When inherited by a recipe, the <filename>pythonnative</filename> class
2497 supports using the native version of Python built by the build system
2498 rather than using the version provided by the build host.
2499 </para>
2500</section>
2501
2502<section id='ref-classes-qemu'>
2503 <title><filename>qemu.bbclass</filename></title>
2504
2505 <para>
2506 The <filename>qemu</filename> class provides functionality for recipes
2507 that either need QEMU or test for the existence of QEMU.
2508 Typically, this class is used to run programs for a target system on
2509 the build host using QEMU's application emulation mode.
2510 </para>
2511</section>
2512
2513<section id='ref-classes-qmake*'>
2514 <title><filename>qmake*.bbclass</filename></title>
2515
2516 <para>
2517 The <filename>qmake*</filename> classes support recipes that
2518 need to build software that uses Qt's <filename>qmake</filename>
2519 build system and are comprised of the following:
2520 <itemizedlist>
2521 <listitem><para><emphasis><filename>qmake_base</filename>:</emphasis>
2522 Provides base functionality for all versions of
2523 <filename>qmake</filename>.</para></listitem>
2524 <listitem><para><emphasis><filename>qmake2</filename>:</emphasis>
2525 Extends base functionality for <filename>qmake</filename> 2.x as
2526 used by Qt 4.x.</para></listitem>
2527 </itemizedlist>
2528 </para>
2529
2530 <para>
2531 If you need to set any configuration variables or pass any options to
2532 <filename>qmake</filename>, you can add these to the
2533 <link linkend='var-EXTRA_QMAKEVARS_PRE'><filename>EXTRA_QMAKEVARS_PRE</filename></link>
2534 or
2535 <link linkend='var-EXTRA_QMAKEVARS_POST'><filename>EXTRA_QMAKEVARS_POST</filename></link>
2536 variables, depending on whether the arguments need to be before or
2537 after the <filename>.pro</filename> file list on the command line,
2538 respectively.
2539 </para>
2540
2541 <para>
2542 By default, all <filename>.pro</filename> files are built.
2543 If you want to specify your own subset of <filename>.pro</filename>
2544 files to be built, specify them in the
2545 <link linkend='var-QMAKE_PROFILES'><filename>QMAKE_PROFILES</filename></link>
2546 variable.
2547 </para>
2548</section>
2549
2550<section id='ref-classes-qt4*'>
2551 <title><filename>qt4*.bbclass</filename></title>
2552
2553 <para>
2554 The <filename>qt4*</filename> classes support recipes that need to
2555 build software that uses the Qt development framework version 4.x
2556 and consist of the following:
2557 <itemizedlist>
2558 <listitem><para><emphasis><filename>qt4e</filename>:</emphasis>
2559 Supports building against Qt/Embedded, which uses the
2560 framebuffer for graphical output.</para></listitem>
2561 <listitem><para><emphasis><filename>qt4x11</filename>:</emphasis>
2562 Supports building against Qt/X11.</para></listitem>
2563 </itemizedlist>
2564 </para>
2565
2566 <para>
2567 The classes inherit the
2568 <link linkend='ref-classes-qmake*'><filename>qmake2</filename></link>
2569 class.
2570 </para>
2571</section>
2572
2573<section id='ref-classes-relocatable'>
2574 <title><filename>relocatable.bbclass</filename></title>
2575
2576 <para>
2577 The <filename>relocatable</filename> class enables relocation of
2578 binaries when they are installed into the sysroot.
2579 </para>
2580
2581 <para>
2582 This class makes use of the
2583 <link linkend='ref-classes-chrpath'><filename>chrpath</filename></link>
2584 class and is used by both the
2585 <link linkend='ref-classes-cross'><filename>cross</filename></link>
2586 and
2587 <link linkend='ref-classes-native'><filename>native</filename></link>
2588 classes.
2589 </para>
2590</section>
2591
2592<section id='ref-classes-report-error'>
2593 <title><filename>report-error.bbclass</filename></title>
2594
2595 <para>
2596 The <filename>report-error</filename> class supports enabling the
2597 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
2598 which allows you to submit build error information to a central
2599 database.
2600 </para>
2601
2602 <para>
2603 The class collects debug information for recipe, recipe version, task,
2604 machine, distro, build system, target system, host distro, branch,
2605 commit, and log.
2606 From the information, report files using a JSON format are created and
2607 stored in
2608 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
2609 </para>
2610</section>
2611
2612<section id='ref-classes-rm-work'>
2613 <title><filename>rm_work.bbclass</filename></title>
2614
2615 <para>
2616 The <filename>rm_work</filename> class supports deletion of temporary
2617 workspace, which can ease your hard drive demands during builds.
2618 </para>
2619
2620 <para>
2621 The OpenEmbedded build system can use a substantial amount of disk
2622 space during the build process.
2623 A portion of this space is the work files under the
2624 <filename>${TMPDIR}/work</filename> directory for each recipe.
2625 Once the build system generates the packages for a recipe, the work
2626 files for that recipe are no longer needed.
2627 However, by default, the build system preserves these files
2628 for inspection and possible debugging purposes.
2629 If you would rather have these files deleted to save disk space
2630 as the build progresses, you can enable <filename>rm_work</filename>
2631 by adding the following to your <filename>local.conf</filename> file,
2632 which is found in the
2633 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2634 <literallayout class='monospaced'>
2635 INHERIT += "rm_work"
2636 </literallayout>
2637 If you are modifying and building source code out of the work directory
2638 for a recipe, enabling <filename>rm_work</filename> will potentially
2639 result in your changes to the source being lost.
2640 To exclude some recipes from having their work directories deleted by
2641 <filename>rm_work</filename>, you can add the names of the recipe or
2642 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
2643 variable, which can also be set in your <filename>local.conf</filename>
2644 file.
2645 Here is an example:
2646 <literallayout class='monospaced'>
2647 RM_WORK_EXCLUDE += "busybox eglibc"
2648 </literallayout>
2649 </para>
2650</section>
2651
2652<section id='ref-classes-rootfs*'>
2653 <title><filename>rootfs*.bbclass</filename></title>
2654
2655 <para>
2656 The <filename>rootfs*</filename> classes support creating
2657 the root filesystem for an image and consist of the following classes:
2658 <itemizedlist>
2659 <listitem><para>
2660 The <filename>rootfs_deb</filename> class, which supports
2661 creation of root filesystems for images built using
2662 <filename>.deb</filename> packages.</para></listitem>
2663 <listitem><para>
2664 The <filename>rootfs_rpm</filename> class, which supports
2665 creation of root filesystems for images built using
2666 <filename>.rpm</filename> packages.</para></listitem>
2667 <listitem><para>
2668 The <filename>rootfs_ipk</filename> class, which supports
2669 creation of root filesystems for images built using
2670 <filename>.ipk</filename> packages.</para></listitem>
2671 </itemizedlist>
2672 </para>
2673
2674 <para>
2675 The root filesystem is created from packages using one of the
2676 <filename>rootfs*.bbclass</filename> files as determined by the
2677 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2678 variable.
2679 </para>
2680
2681 <para>
2682 For information on how root filesystem images are created, see the
2683 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
2684 section.
2685 </para>
2686</section>
2687
2688<section id='ref-classes-sanity'>
2689 <title><filename>sanity.bbclass</filename></title>
2690
2691 <para>
2692 The <filename>sanity</filename> class checks to see if prerequisite
2693 software is present on the host system so that users can be notified
2694 of potential problems that might affect their build.
2695 The class also performs basic user configuration checks from
2696 the <filename>local.conf</filename> configuration file to
2697 prevent common mistakes that cause build failures.
2698 Distribution policy usually determines whether to include this class.
2699 </para>
2700</section>
2701
2702<section id='ref-classes-scons'>
2703 <title><filename>scons.bbclass</filename></title>
2704
2705 <para>
2706 The <filename>scons</filename> class supports recipes that need to
2707 build software that uses the SCons build system.
2708 You can use the
2709 <link linkend='var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></link>
2710 variable to specify additional configuration options you want to pass
2711 SCons command line.
2712 </para>
2713</section>
2714
2715<section id='ref-classes-sdl'>
2716 <title><filename>sdl.bbclass</filename></title>
2717
2718 <para>
2719 The <filename>sdl</filename> class supports recipes that need to build
2720 software that uses the Simple DirectMedia Layer (SDL) library.
2721 </para>
2722</section>
2723
2724<section id='ref-classes-setuptools'>
2725 <title><filename>setuptools.bbclass</filename></title>
2726
2727 <para>
2728 The <filename>setuptools</filename> class supports Python
2729 version 2.x extensions that use build systems based on
2730 <filename>setuptools</filename>.
2731 If your recipe uses these build systems, the recipe needs to
2732 inherit the <filename>setuptools</filename> class.
2733 </para>
2734</section>
2735
2736<section id='ref-classes-setuptools3'>
2737 <title><filename>setuptools3.bbclass</filename></title>
2738
2739 <para>
2740 The <filename>setuptools3</filename> class supports Python
2741 version 3.x extensions that use build systems based on
2742 <filename>setuptools3</filename>.
2743 If your recipe uses these build systems, the recipe needs to
2744 inherit the <filename>setuptools3</filename> class.
2745 </para>
2746</section>
2747
2748<section id='ref-classes-sip'>
2749 <title><filename>sip.bbclass</filename></title>
2750
2751 <para>
2752 The <filename>sip</filename> class
2753 supports recipes that build or package SIP-based Python bindings.
2754 </para>
2755</section>
2756
2757<section id='ref-classes-siteconfig'>
2758 <title><filename>siteconfig.bbclass</filename></title>
2759
2760 <para>
2761 The <filename>siteconfig</filename> class
2762 provides functionality for handling site configuration.
2763 The class is used by the
2764 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2765 class to accelerate the
2766 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2767 task.
2768 </para>
2769</section>
2770
2771<section id='ref-classes-siteinfo'>
2772 <title><filename>siteinfo.bbclass</filename></title>
2773
2774 <para>
2775 The <filename>siteinfo</filename> class provides information about
2776 the targets that might be needed by other classes or recipes.
2777 </para>
2778
2779 <para>
2780 As an example, consider Autotools, which can require tests that must
2781 execute on the target hardware.
2782 Since this is not possible in general when cross compiling, site
2783 information is used to provide cached test results so these tests can
2784 be skipped over but still make the correct values available.
2785 The
2786 <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
2787 contains test results sorted into different categories such as
2788 architecture, endianness, and the <filename>libc</filename> used.
2789 Site information provides a list of files containing data relevant to
2790 the current build in the
2791 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
2792 that Autotools automatically picks up.
2793 </para>
2794
2795 <para>
2796 The class also provides variables like
2797 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
2798 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
2799 that can be used elsewhere in the metadata.
2800 </para>
2801
2802 <para>
2803 Because the
2804 <link linkend='ref-classes-base'><filename>base</filename></link> class
2805 includes the <filename>siteinfo</filename> class, it is always active.
2806 </para>
2807</section>
2808
2809<section id='ref-classes-spdx'>
2810 <title><filename>spdx.bbclass</filename></title>
2811
2812 <para>
2813 The <filename>spdx</filename> class integrates real-time license
2814 scanning, generation of SPDX standard output, and verification
2815 of license information during the build.
2816 <note>
2817 This class is currently at the prototype stage in the 1.6
2818 release.
2819 </note>
2820 </para>
2821</section>
2822
2823<section id='ref-classes-sstate'>
2824 <title><filename>sstate.bbclass</filename></title>
2825
2826 <para>
2827 The <filename>sstate</filename> class provides support for Shared
2828 State (sstate).
2829 By default, the class is enabled through the
2830 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
2831 variable's default value.
2832 </para>
2833
2834 <para>
2835 For more information on sstate, see the
2836 "<link linkend='shared-state-cache'>Shared State Cache</link>"
2837 section.
2838 </para>
2839</section>
2840
2841<section id='ref-classes-staging'>
2842 <title><filename>staging.bbclass</filename></title>
2843
2844 <para>
2845 The <filename>staging</filename> class provides support for staging
2846 files into the sysroot during the
2847 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
2848 task.
2849 The class is enabled by default because it is inherited by the
2850 <link linkend='ref-classes-base'><filename>base</filename></link>
2851 class.
2852 </para>
2853</section>
2854
2855<section id='ref-classes-syslinux'>
2856 <title><filename>syslinux.bbclass</filename></title>
2857
2858 <para>
2859 The <filename>syslinux</filename> class provides syslinux-specific
2860 functions for building bootable images.
2861 </para>
2862
2863 <para>
2864 The class supports the following variables:
2865 <itemizedlist>
2866 <listitem><para><emphasis><link linkend='var-INITRD'><filename>INITRD</filename></link>:</emphasis>
2867 Indicates a filesystem image to use as an initial RAM disk
2868 (initrd).
2869 This variable is optional.</para></listitem>
2870 <listitem><para><emphasis><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:</emphasis>
2871 Indicates a filesystem image to include as the root filesystem.
2872 This variable is optional.</para></listitem>
2873 <listitem><para><emphasis><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>:</emphasis>
2874 Enables creating an automatic menu when set to "1".
2875 </para></listitem>
2876 <listitem><para><emphasis><link linkend='var-LABELS'><filename>LABELS</filename></link>:</emphasis>
2877 Lists targets for automatic configuration.
2878 </para></listitem>
2879 <listitem><para><emphasis><link linkend='var-APPEND'><filename>APPEND</filename></link>:</emphasis>
2880 Lists append string overrides for each label.
2881 </para></listitem>
2882 <listitem><para><emphasis><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>:</emphasis>
2883 Lists additional options to add to the syslinux file.
2884 Semicolon characters separate multiple options.
2885 </para></listitem>
2886 <listitem><para><emphasis><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>:</emphasis>
2887 Lists a background for the VGA boot menu when you are using the
2888 boot menu.</para></listitem>
2889 <listitem><para><emphasis><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>:</emphasis>
2890 Set to "console=ttyX" to change kernel boot default console.
2891 </para></listitem>
2892 <listitem><para><emphasis><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>:</emphasis>
2893 Sets an alternate serial port.
2894 Or, turns off serial when the variable is set with an
2895 empty string.</para></listitem>
2896 <listitem><para><emphasis><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>:</emphasis>
2897 Sets an alternate "console=tty..." kernel boot argument.
2898 </para></listitem>
2899 </itemizedlist>
2900 </para>
2901</section>
2902
2903<section id='ref-classes-systemd'>
2904 <title><filename>systemd.bbclass</filename></title>
2905
2906 <para>
2907 The <filename>systemd</filename> class provides support for recipes
2908 that install systemd unit files.
2909 </para>
2910
2911 <para>
2912 The functionality for this class is disabled unless you have "systemd"
2913 in
2914 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2915 </para>
2916
2917 <para>
2918 Under this class, the recipe or Makefile (i.e. whatever the recipe is
2919 calling during the
2920 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2921 task) installs unit files into
2922 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>.
2923 If the unit files being installed go into packages other than the
2924 main package, you need to set
2925 <link linkend='var-SYSTEMD_PACKAGES'><filename>SYSTEMD_PACKAGES</filename></link>
2926 in your recipe to identify the packages in which the files will be
2927 installed.
2928 </para>
2929
2930 <para>
2931 You should set
2932 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
2933 to the name of the service file.
2934 You should also use a package name override to indicate the package
2935 to which the value applies.
2936 If the value applies to the recipe's main package, use
2937 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>.
2938 Here is an example from the connman recipe:
2939 <literallayout class='monospaced'>
2940 SYSTEMD_SERVICE_${PN} = "connman.service"
2941 </literallayout>
2942 Services are set up to start on boot automatically unless
2943 you have set
2944 <link linkend='var-SYSTEMD_AUTO_ENABLE'><filename>SYSTEMD_AUTO_ENABLE</filename></link>
2945 to "disable".
2946 </para>
2947
2948 <para>
2949 For more information on <filename>systemd</filename>, see the
2950 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager'>Selecting an Initialization Manager</ulink>"
2951 section in the Yocto Project Development Manual.
2952 </para>
2953</section>
2954
2955<section id='ref-classes-terminal'>
2956 <title><filename>terminal.bbclass</filename></title>
2957
2958 <para>
2959 The <filename>terminal</filename> class provides support for starting
2960 a terminal session.
2961 The
2962 <link linkend='var-OE_TERMINAL'><filename>OE_TERMINAL</filename></link>
2963 variable controls which terminal emulator is used for the session.
2964 </para>
2965
2966 <para>
2967 Other classes use the <filename>terminal</filename> class anywhere a
2968 separate terminal session needs to be started.
2969 For example, the
2970 <link linkend='ref-classes-patch'><filename>patch</filename></link>
2971 class assuming
2972 <link linkend='var-PATCHRESOLVE'><filename>PATCHRESOLVE</filename></link>
2973 is set to "user", the
2974 <link linkend='ref-classes-cml1'><filename>cml1</filename></link>
2975 class, and the
2976 <link linkend='ref-classes-devshell'><filename>devshell</filename></link>
2977 class all use the <filename>terminal</filename> class.
2978 </para>
2979</section>
2980
2981<section id='ref-classes-testimage'>
2982 <title><filename>testimage.bbclass</filename></title>
2983
2984 <para>
2985 The <filename>testimage</filename> class supports running automated
2986 tests against images using QEMU and on actual hardware.
2987 The class handles loading the tests and starting the image.
2988 </para>
2989
2990 <para>
2991 To use the class, you need to perform steps to set up the
2992 environment.
2993 The tests are commands that run on the target system over
2994 <filename>ssh</filename>.
2995 they are written in Python and make use of the
2996 <filename>unittest</filename> module.
2997 </para>
2998
2999 <para>
3000 For information on how to enable, run, and create new tests, see the
3001 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
3002 section.
3003 </para>
3004</section>
3005
3006<section id='ref-classes-tinderclient'>
3007 <title><filename>tinderclient.bbclass</filename></title>
3008
3009 <para>
3010 The <filename>tinderclient</filename> class submits build results to
3011 an external Tinderbox instance.
3012 <note>
3013 This class is currently unmaintained.
3014 </note>
3015 </para>
3016</section>
3017
3018<section id='ref-classes-toaster'>
3019 <title><filename>toaster.bbclass</filename></title>
3020
3021 <para>
3022 The <filename>toaster</filename> class collects information about
3023 packages and images and sends them as events that the BitBake
3024 user interface can receive.
3025 The class is enabled when the Toaster user interface is running.
3026 </para>
3027
3028 <para>
3029 This class is not intended to be used directly.
3030 </para>
3031</section>
3032
3033<section id='ref-classes-toolchain-scripts'>
3034 <title><filename>toolchain-scripts.bbclass</filename></title>
3035
3036 <para>
3037 The <filename>toolchain-scripts</filename> class provides the scripts
3038 used for setting up the environment for installed SDKs.
3039 </para>
3040</section>
3041
3042<section id='ref-classes-typecheck'>
3043 <title><filename>typecheck.bbclass</filename></title>
3044
3045 <para>
3046 The <filename>typecheck</filename> class provides support for
3047 validating the values of variables set at the configuration level
3048 against their defined types.
3049 The OpenEmbedded build system allows you to define the type of a
3050 variable using the "type" varflag.
3051 Here is an example:
3052 <literallayout class='monospaced'>
3053 IMAGE_FEATURES[type] = "list"
3054 </literallayout>
3055 </para>
3056</section>
3057
3058<section id='ref-classes-uboot-config'>
3059 <title><filename>uboot-config.bbclass</filename></title>
3060
3061 <para>
3062 The <filename>uboot-config</filename> class provides support for
3063 U-Boot configuration for a machine.
3064 Specify the machine in your recipe as follows:
3065 <literallayout class='monospaced'>
3066 UBOOT_CONFIG ??= &lt;default&gt;
3067 UBOOT_CONFIG[foo] = "config,images"
3068 </literallayout>
3069 You can also specify the machine using this method:
3070 <literallayout class='monospaced'>
3071 UBOOT_MACHINE = "config"
3072 </literallayout>
3073 See the
3074 <link linkend='var-UBOOT_CONFIG'><filename>UBOOT_CONFIG</filename></link>
3075 and
3076 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
3077 variables for additional information.
3078 </para>
3079</section>
3080
3081<section id='ref-classes-update-alternatives'>
3082 <title><filename>update-alternatives.bbclass</filename></title>
3083
3084 <para>
3085 The <filename>update-alternatives</filename> class helps the
3086 alternatives system when multiple sources provide the same command.
3087 This situation occurs when several programs that have the same or
3088 similar function are installed with the same name.
3089 For example, the <filename>ar</filename> command is available from the
3090 <filename>busybox</filename>, <filename>binutils</filename> and
3091 <filename>elfutils</filename> packages.
3092 The <filename>update-alternatives</filename> class handles
3093 renaming the binaries so that multiple packages can be installed
3094 without conflicts.
3095 The <filename>ar</filename> command still works regardless of which
3096 packages are installed or subsequently removed.
3097 The class renames the conflicting binary in each package and symlinks
3098 the highest priority binary during installation or removal of packages.
3099 </para>
3100
3101 <para>
3102 To use this class, you need to define a number of variables:
3103 <itemizedlist>
3104 <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
3105 </para></listitem>
3106 <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
3107 </para></listitem>
3108 <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
3109 </para></listitem>
3110 <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
3111 </para></listitem>
3112 </itemizedlist>
3113 These variables list alternative commands needed by a package,
3114 provide pathnames for links, default links for targets, and
3115 so forth.
3116 For details on how to use this class, see the comments in the
3117 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>.
3118 </para>
3119
3120 <note>
3121 You can use the <filename>update-alternatives</filename> command
3122 directly in your recipes.
3123 However, this class simplifies things in most cases.
3124 </note>
3125</section>
3126
3127<section id='ref-classes-update-rc.d'>
3128 <title><filename>update-rc.d.bbclass</filename></title>
3129
3130 <para>
3131 The <filename>update-rc.d</filename> class uses
3132 <filename>update-rc.d</filename> to safely install an
3133 initialization script on behalf of the package.
3134 The OpenEmbedded build system takes care of details such as making
3135 sure the script is stopped before a package is removed and started when
3136 the package is installed.
3137 </para>
3138
3139 <para>
3140 Three variables control this class:
3141 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
3142 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
3143 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
3144 See the variable links for details.
3145 </para>
3146</section>
3147
3148<section id='ref-classes-useradd'>
3149 <title><filename>useradd.bbclass</filename></title>
3150
3151 <para>
3152 The <filename>useradd</filename> class supports the addition of users
3153 or groups for usage by the package on the target.
3154 For example, if you have packages that contain system services that
3155 should be run under their own user or group, you can use this class to
3156 enable creation of the user or group.
3157 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
3158 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3159 provides a simple example that shows how to add three
3160 users and groups to two packages.
3161 See the <filename>useradd-example.bb</filename> recipe for more
3162 information on how to use this class.
3163 </para>
3164
3165 <para>
3166 The <filename>useradd</filename> class supports the
3167 <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>,
3168 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
3169 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
3170 and
3171 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
3172 variables.
3173 </para>
3174</section>
3175
3176<section id='ref-classes-useradd-staticids'>
3177 <title><filename>useradd-staticids.bbclass</filename></title>
3178
3179 <para>
3180 The <filename>useradd-staticids</filename> class supports the addition
3181 of users or groups that have static user identification
3182 (<filename>uid</filename>) and group identification
3183 (<filename>gid</filename>) values.
3184 </para>
3185
3186 <para>
3187 The default behavior of the OpenEmbedded build system for assigning
3188 <filename>uid</filename> and <filename>gid</filename> values when
3189 packages add users and groups during package install time is to
3190 add them dynamically.
3191 This works fine for programs that do not care what the values of the
3192 resulting users and groups become.
3193 In these cases, the order of the installation determines the final
3194 <filename>uid</filename> and <filename>gid</filename> values.
3195 However, if non-deterministic
3196 <filename>uid</filename> and <filename>gid</filename> values are a
3197 problem, you can override the default, dynamic application of these
3198 values by setting static values.
3199 When you set static values, the OpenEmbedded build system looks in
3200 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
3201 <filename>files/passwd</filename> and <filename>files/group</filename>
3202 files for the values.
3203 </para>
3204
3205 <para>
3206 To use static <filename>uid</filename> and <filename>gid</filename>
3207 values, you need to set some variables.
3208 See the
3209 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
3210 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
3211 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>,
3212 and
3213 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
3214 variables.
3215 You can also see the
3216 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
3217 class for additional information.
3218 </para>
3219
3220 <note><title>Notes</title>
3221 You do not use this class directly.
3222 You either enable or disable the class by setting the
3223 <filename>USERADDEXTENSION</filename> variable.
3224 If you enable or disable the class in a configured system,
3225 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
3226 might contain incorrect <filename>uid</filename> and
3227 <filename>gid</filename> values.
3228 Deleting the <filename>TMPDIR</filename> directory
3229 will correct this condition.
3230 </note>
3231</section>
3232
3233<section id='ref-classes-utility-tasks'>
3234 <title><filename>utility-tasks.bbclass</filename></title>
3235
3236 <para>
3237 The <filename>utility-tasks</filename> class provides support for
3238 various "utility" type tasks that are applicable to all recipes,
3239 such as
3240 <link linkend='ref-tasks-clean'><filename>do_clean</filename></link> and
3241 <link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>.
3242 </para>
3243
3244 <para>
3245 This class is enabled by default because it is inherited by
3246 the
3247 <link linkend='ref-classes-base'><filename>base</filename></link>
3248 class.
3249 </para>
3250</section>
3251
3252<section id='ref-classes-utils'>
3253 <title><filename>utils.bbclass</filename></title>
3254
3255 <para>
3256 The <filename>utils</filename> class provides some useful Python
3257 functions that are typically used in inline Python expressions
3258 (e.g. <filename>${@...}</filename>).
3259 One example use is for <filename>bb.utils.contains()</filename>.
3260 </para>
3261
3262 <para>
3263 This class is enabled by default because it is inherited by the
3264 <link linkend='ref-classes-base'><filename>base</filename></link>
3265 class.
3266 </para>
3267</section>
3268
3269<section id='ref-classes-vala'>
3270 <title><filename>vala.bbclass</filename></title>
3271
3272 <para>
3273 The <filename>vala</filename> class supports recipes that need to
3274 build software written using the Vala programming language.
3275 </para>
3276</section>
3277
3278<section id='ref-classes-waf'>
3279 <title><filename>waf.bbclass</filename></title>
3280
3281 <para>
3282 The <filename>waf</filename> class supports recipes that need to build
3283 software that uses the Waf build system.
3284 You can use the
3285 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
3286 variable to specify additional configuration options to be passed on
3287 the Waf command line.
3288 </para>
3289</section>
3290
3291<!-- Undocumented classes are:
3292 image-empty.bbclass (possibly being dropped)
3293 migrate_localcount.bbclass (still need a description)
3294-->
3295
3296
3297</chapter>
3298<!--
3299vim: expandtab tw=80 ts=4
3300-->
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
new file mode 100644
index 0000000..4aafaea
--- /dev/null
+++ b/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,346 @@
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 the
57 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
58 task for a particular recipe.
59 </para>
60
61 <para>
62 This feature list only represents features as shipped with the Yocto Project metadata:
63 <itemizedlist>
64 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
65 </para></listitem>
66 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
67 </para></listitem>
68 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
69 </para></listitem>
70 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
71 </para></listitem>
72 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
73 </para></listitem>
74 <listitem><para><emphasis>irda:</emphasis> Hardware has IrDA support
75 </para></listitem>
76 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
77 </para></listitem>
78 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
79 </para></listitem>
80 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
81 </para></listitem>
82 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
83 </para></listitem>
84 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
85 </para></listitem>
86 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
87 </para></listitem>
88 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
89 </para></listitem>
90 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
91 </para></listitem>
92 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
93 </para></listitem>
94 </itemizedlist>
95 </para>
96 </section>
97
98 <section id='ref-features-distro'>
99 <title>Distro Features</title>
100
101 <para>
102 The items below are features you can use with
103 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
104 to enable features across your distribution.
105 Features do not have a one-to-one correspondence to packages,
106 and they can go beyond simply controlling the installation of a
107 package or packages.
108 In most cases, the presence or absence of a feature translates to
109 the appropriate option supplied to the configure script during the
110 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
111 task for the recipes that optionally
112 support the feature.
113 </para>
114
115 <para>
116 Some distro features are also machine features.
117 These select features make sense to be controlled both at
118 the machine and distribution configuration level.
119 See the
120 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></ulink>
121 variable for more information.
122 </para>
123
124 <para>
125 This list only represents features as shipped with the Yocto Project metadata:
126 <itemizedlist>
127 <listitem><para><emphasis>alsa:</emphasis> Include ALSA support
128 (OSS compatibility kernel modules installed if available).
129 </para></listitem>
130 <listitem><para><emphasis>bluetooth:</emphasis> Include
131 bluetooth support (integrated BT only).</para></listitem>
132 <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
133 support.</para></listitem>
134 <listitem><para><emphasis>directfb:</emphasis>
135 Include DirectFB support.
136 </para></listitem>
137 <listitem><para><emphasis>ext2:</emphasis> Include tools for
138 supporting for devices with internal HDD/Microdrive for
139 storing files (instead of Flash only devices).
140 </para></listitem>
141 <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
142 support.</para></listitem>
143 <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
144 </para></listitem>
145 <listitem><para><emphasis>irda:</emphasis> Include IrDA support.
146 </para></listitem>
147 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
148 support (e.g. keymaps will be loaded during boot).
149 </para></listitem>
150 <listitem><para><emphasis>nfs:</emphasis> Include NFS client
151 support (for mounting NFS exports on device).
152 </para></listitem>
153 <listitem><para><emphasis>opengl:</emphasis>
154 Include the Open Graphics Library, which is a
155 cross-language, multi-platform application programming
156 interface used for rendering two and three-dimensional
157 graphics.</para></listitem>
158 <listitem><para><emphasis>pci:</emphasis> Include PCI bus
159 support.</para></listitem>
160 <listitem><para><emphasis>pcmcia:</emphasis> Include
161 PCMCIA/CompactFlash support.</para></listitem>
162 <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
163 support.</para></listitem>
164 <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
165 client support (for mounting Samba/Microsoft Windows shares
166 on device).</para></listitem>
167 <listitem><para><emphasis>systemd:</emphasis> Include support
168 for this <filename>init</filename> manager, which is a full
169 replacement of for <filename>init</filename> with parallel
170 starting of services, reduced shell overhead, and other
171 features.
172 This <filename>init</filename> manager is used by many
173 distributions.</para></listitem>
174 <listitem><para><emphasis>usbgadget:</emphasis> Include USB
175 Gadget Device support (for USB networking/serial/storage).
176 </para></listitem>
177 <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
178 support (allows to connect external keyboard, mouse,
179 storage, network etc).</para></listitem>
180 <listitem><para><emphasis>wayland:</emphasis> Include the
181 Wayland display server protocol and the library that
182 supports it.</para></listitem>
183 <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
184 (integrated only).</para></listitem>
185 <listitem><para><emphasis>x11:</emphasis> Include the X server
186 and libraries.</para></listitem>
187 </itemizedlist>
188 </para>
189 </section>
190
191 <section id='ref-features-image'>
192 <title>Image Features</title>
193
194 <para>
195 The contents of images generated by the OpenEmbedded build system can be controlled by the
196 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
197 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
198 variables that you typically configure in your image recipes.
199 Through these variables, you can add several different
200 predefined packages such as development utilities or packages with debug
201 information needed to investigate application problems or profile applications.
202 </para>
203
204 <para>
205 Current list of
206 <filename>IMAGE_FEATURES</filename> contains the following:
207 <itemizedlist>
208 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages
209 installed in a given image.</para></listitem>
210 <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and
211 extra library links) for all packages installed in a given image.</para></listitem>
212 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages
213 installed in a given image.</para></listitem>
214 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem>
215 <listitem><para><emphasis>read-only-rootfs:</emphasis> Creates
216 an image whose root filesystem is read-only.
217 See the
218 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
219 section in the Yocto Project Development Manual for more
220 information.</para></listitem>
221 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot.
222 By default, this screen is provided by <filename>psplash</filename>, which does
223 allow customization.
224 If you prefer to use an alternative splash screen package, you can do so by
225 setting the <filename>SPLASH</filename> variable
226 to a different package name (or names) within the image recipe or at the distro
227 configuration level.</para></listitem>
228 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
229 SSH server.
230 </para></listitem>
231 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
232 which is more full-featured than Dropbear.
233 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
234 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
235 precedence and Dropbear will not be installed.</para></listitem>
236 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
237 packages (i.e. static libraries containing <filename>*.a</filename> files) for all
238 packages installed in a given image.</para></listitem>
239 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
240 <filename>strace</filename> and <filename>gdb</filename>.
241 For information on GDB, see the
242 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
243 section in the Yocto Project Development Manual.
244 For information on tracing and profiling, see the
245 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
246 </para></listitem>
247 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
248 <filename>oprofile</filename>, <filename>exmap</filename>, and
249 <filename>LTTng</filename>.
250 For general information on user-space tools, see the
251 "<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>"
252 section in the Yocto Project Application Developer's Guide.</para></listitem>
253 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
254 </para></listitem>
255 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
256 touchscreen debugging).</para></listitem>
257 <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem>
258 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
259 minimal environment.</para></listitem>
260 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
261 </para></listitem>
262 </itemizedlist>
263 </para>
264 </section>
265
266 <section id='ref-features-backfill'>
267 <title>Feature Backfilling</title>
268
269 <para>
270 Sometimes it is necessary in the OpenEmbedded build system to extend
271 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
272 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
273 to control functionality that was previously enabled and not able
274 to be disabled.
275 For these cases, we need to add an
276 additional feature item to appear in one of these variables,
277 but we do not want to force developers who have existing values
278 of the variables in their configuration to add the new feature
279 in order to retain the same overall level of functionality.
280 Thus, the OpenEmbedded build system has a mechanism to
281 automatically "backfill" these added features into existing
282 distro or machine configurations.
283 You can see the list of features for which this is done by
284 finding the
285 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
286 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
287 variables in the <filename>meta/conf/bitbake.conf</filename> file.
288 </para>
289
290 <para>
291 Because such features are backfilled by default into all
292 configurations as described in the previous paragraph, developers
293 who wish to disable the new features need to be able to selectively
294 prevent the backfilling from occurring.
295 They can do this by adding the undesired feature or features to the
296 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
297 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
298 variables for distro features and machine features respectively.
299 </para>
300
301 <para>
302 Here are two examples to help illustrate feature backfilling:
303 <itemizedlist>
304 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
305 Previously, PulseAudio support was enabled within the Qt and
306 GStreamer frameworks.
307 Because of this, the feature is backfilled and thus
308 enabled for all distros through the
309 <filename>DISTRO_FEATURES_BACKFILL</filename>
310 variable in the <filename>meta/conf/bitbake.conf</filename> file.
311 However, your distro needs to disable the feature.
312 You can disable the feature without affecting
313 other existing distro configurations that need PulseAudio support
314 by adding "pulseaudio" to
315 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
316 in your distro's <filename>.conf</filename> file.
317 Adding the feature to this variable when it also
318 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
319 variable prevents the build system from adding the feature to
320 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
321 the feature for that particular distro.</para></listitem>
322 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
323 Previously, real time clock (RTC) support was enabled for all
324 target devices.
325 Because of this, the feature is backfilled and thus enabled
326 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
327 variable in the <filename>meta/conf/bitbake.conf</filename> file.
328 However, your target device does not have this capability.
329 You can disable RTC support for your device without
330 affecting other machines that need RTC support
331 by adding the feature to your machine's
332 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
333 list in the machine's <filename>.conf</filename> file.
334 Adding the feature to this variable when it also
335 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
336 variable prevents the build system from adding the feature to
337 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
338 disabling RTC support for that particular machine.</para></listitem>
339 </itemizedlist>
340 </para>
341 </section>
342</chapter>
343
344<!--
345vim: expandtab tw=80 ts=4 spell spelllang=en_gb
346-->
diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml
new file mode 100644
index 0000000..7727e0a
--- /dev/null
+++ b/documentation/ref-manual/ref-images.xml
@@ -0,0 +1,166 @@
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)
83 specification.
84 This image requires a distribution configuration that
85 enables LSB compliance (e.g. <filename>poky-lsb</filename>).
86 If you build <filename>core-image-lsb</filename> without that
87 configuration, the image will not be LSB-compliant.
88 </para></listitem>
89 <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis>
90 A <filename>core-image-lsb</filename> image that is suitable for development work
91 using the host.
92 The image includes headers and libraries you can use in a host development
93 environment.
94 This image requires a distribution configuration that
95 enables LSB compliance (e.g. <filename>poky-lsb</filename>).
96 If you build <filename>core-image-lsb-dev</filename> without that
97 configuration, the image will not be LSB-compliant.
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
101 meta-toolchain but also includes development headers and libraries
102 to form a complete standalone SDK.
103 This image requires a distribution configuration that
104 enables LSB compliance (e.g. <filename>poky-lsb</filename>).
105 If you build <filename>core-image-lsb-sdk</filename> without that
106 configuration, the image will not be LSB-compliant.
107 This image is suitable for development using the target.</para></listitem>
108 <listitem><para><emphasis><filename>core-image-testmaster</filename>:</emphasis>
109 A "master" image designed to be used for automated runtime testing.
110 Provides a "known good" image that is deployed to a separate
111 partition so that you can boot into it and use it to deploy a
112 second image to be tested.
113 You can find more information about runtime testing in the
114 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
115 section in the Yocto Project Development Manual.
116 </para></listitem>
117 <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis>
118 An image with support for the Open GL-based toolkit Clutter, which enables development of
119 rich and animated graphical user interfaces.</para></listitem>
120 <listitem><para><emphasis><filename>core-image-directfb</filename>:</emphasis>
121 An image that uses <filename>directfb</filename> instead of X11.
122 </para></listitem>
123 <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis>
124 A very basic X11 image with a terminal.
125 </para></listitem>
126 <listitem><para><emphasis><filename>core-image-weston</filename>:</emphasis>
127 A very basic Wayland image with a terminal.
128 This image provides the Wayland protocol libraries and the
129 reference Weston compositor.
130 For more information, see the
131 "<link linkend='wayland'>Wayland</link>" section.
132 </para></listitem>
133 <listitem><para><emphasis><filename>qt4e-demo-image</filename>:</emphasis>
134 An image that launches into the demo application for the embedded
135 (not based on X11) version of Qt.</para></listitem>
136 <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis>
137 A <filename>core-image-minimal</filename> image plus a real-time test suite and
138 tools appropriate for real-time use.</para></listitem>
139 <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis>
140 A <filename>core-image-rt</filename> image that includes everything in
141 <filename>meta-toolchain</filename>.
142 The image also includes development headers and libraries to form a complete
143 stand-alone SDK and is suitable for development using the target.
144 </para></listitem>
145 <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis>
146 An image with Sato support, a mobile environment and visual style that works well
147 with mobile devices.
148 The image supports X11 with a Sato theme and applications such as
149 a terminal, editor, file manager, media player, and so forth.
150 </para></listitem>
151 <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis>
152 A <filename>core-image-sato</filename> image suitable for development
153 using the host.
154 The image includes libraries needed to build applications on the device itself,
155 testing and profiling tools, and debug symbols.
156 This image was formerly <filename>core-image-sdk</filename>.
157 </para></listitem>
158 <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis>
159 A <filename>core-image-sato</filename> image that includes everything in meta-toolchain.
160 The image also includes development headers and libraries to form a complete standalone SDK
161 and is suitable for development using the target.</para></listitem>
162 </itemizedlist>
163</chapter>
164<!--
165vim: expandtab tw=80 ts=4
166-->
diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl
new file mode 100644
index 0000000..05c9b97
--- /dev/null
+++ b/documentation/ref-manual/ref-manual-customization.xsl
@@ -0,0 +1,20 @@
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:include href="../template/permalinks.xsl"/>
7 <xsl:include href="../template/section.title.xsl"/>
8 <xsl:include href="../template/component.title.xsl"/>
9 <xsl:include href="../template/division.title.xsl"/>
10 <xsl:include href="../template/formal.object.heading.xsl"/>
11 <xsl:include href="../template/gloss-permalinks.xsl"/>
12
13 <xsl:param name="html.stylesheet" select="'ref-style.css'" />
14 <xsl:param name="chapter.autolabel" select="1" />
15 <xsl:param name="appendix.autolabel" select="A" />
16 <xsl:param name="section.autolabel" select="1" />
17 <xsl:param name="section.label.includes.component.label" select="1" />
18 <xsl:param name="generate.id.attributes" select="1" />
19
20</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..3eff7de
--- /dev/null
+++ b/documentation/ref-manual/ref-manual.xml
@@ -0,0 +1,150 @@
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.7</revnumber>
87 <date>Fall of 2014</date>
88 <revremark>Released with the Yocto Project 1.7 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-tasks.xml"/>
127
128 <xi:include href="ref-qa-checks.xml"/>
129
130 <xi:include href="ref-images.xml"/>
131
132 <xi:include href="ref-features.xml"/>
133
134 <xi:include href="ref-variables.xml"/>
135
136 <xi:include href="ref-varlocality.xml"/>
137
138 <xi:include href="faq.xml"/>
139
140 <xi:include href="resources.xml"/>
141
142<!-- <index id='index'>
143 <title>Index</title>
144 </index>
145-->
146
147</book>
148<!--
149vim: expandtab tw=80 ts=4
150-->
diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml
new file mode 100644
index 0000000..43a0bd0
--- /dev/null
+++ b/documentation/ref-manual/ref-qa-checks.xml
@@ -0,0 +1,1151 @@
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-qa-checks'>
6<title>QA Error and Warning Messages</title>
7
8<section id='qa-introduction'>
9 <title>Introduction</title>
10
11 <para>
12 When building a recipe, the OpenEmbedded build system performs
13 various QA checks on the output to ensure that common issues are
14 detected and reported.
15 Sometimes when you create a new recipe to build new software,
16 it will build with no problems.
17 When this is not the case, or when you have QA issues building any
18 software, it could take a little time to resolve them.
19 </para>
20
21 <para>
22 While it is tempting to ignore a QA message or even to
23 disable QA checks, it is best to try and resolve any
24 reported QA issues.
25 This chapter provides a list of the QA messages and brief explanations
26 of the issues you could encounter so that you can properly resolve
27 problems.
28 </para>
29
30 <para>
31 The next section provides a list of all QA error and warning
32 messages based on a default configuration.
33 Each entry provides the message or error form along with an
34 explanation.
35 <note>
36 <title>Notes</title>
37 <itemizedlist>
38 <listitem><para>
39 At the end of each message, the name of the associated
40 QA test (as listed in the
41 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
42 section) appears within square brackets.
43 </para></listitem>
44 <listitem><para>
45 As mentioned, this list of error and warning messages is for
46 QA checks only.
47 The list does not cover all possible build errors or
48 warnings you could encounter.
49 </para></listitem>
50 <listitem><para>
51 Because some QA checks are disabled by default, this list
52 does not include all possible QA check errors and warnings.
53 </para></listitem>
54 </itemizedlist>
55 </note>
56 </para>
57</section>
58
59<section id='qa-errors-and-warnings'>
60 <title>Errors and Warnings</title>
61
62 <para>
63 <itemizedlist>
64 <listitem>
65 <para>
66 <code>
67 &lt;packagename&gt;: &lt;path&gt; is using libexec please relocate to &lt;libexecdir&gt; [libexec]
68 </code>
69 </para>
70
71 <para>
72 The specified package contains files in
73 <filename>/usr/libexec</filename>.
74 By default, <filename>libexecdir</filename> is set to
75 "${libdir}/${BPN}" rather than to "/usr/libexec".
76 Thus, installing to <filename>/usr/libexec</filename>
77 is likely not desirable.
78 </para>
79
80 <para>
81 &nbsp;
82 </para>
83 </listitem>
84 </itemizedlist>
85 </para>
86
87 <para>
88 <itemizedlist>
89 <listitem>
90 <para>
91 <code>
92 package &lt;packagename&gt; contains bad RPATH &lt;rpath&gt; in file &lt;file&gt; [rpaths]
93 </code>
94 </para>
95
96 <para>
97 The specified binary produced by the recipe contains dynamic
98 library load paths (rpaths) that contain build system paths
99 such as
100 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
101 which are incorrect for the target and could potentially
102 be a security issue.
103 Check for bad <filename>-rpath</filename> options being
104 passed to the linker in your
105 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
106 log.
107 Depending on the build system used by the software being
108 built, there might be a configure option to disable rpath
109 usage completely within the build of the software.
110 </para>
111
112 <para>
113 &nbsp;
114 </para>
115 </listitem>
116 </itemizedlist>
117 </para>
118
119 <para>
120 <itemizedlist>
121 <listitem>
122 <para>
123 <code>
124 &lt;packagename&gt;: &lt;file&gt; contains probably-redundant RPATH &lt;rpath&gt; [useless-rpaths]
125 </code>
126 </para>
127
128 <para>
129 The specified binary produced by the recipe contains dynamic
130 library load paths (rpaths) that on a standard system are
131 searched by default by the linker (e.g.
132 <filename>/lib</filename> and <filename>/usr/lib</filename>).
133 While these paths will not cause any breakage, they do waste
134 space and are unnecessary.
135 Depending on the build system used by the software being
136 built, there might be a configure option to disable rpath
137 usage completely within the build of the software.
138 </para>
139
140 <para>
141 &nbsp;
142 </para>
143 </listitem>
144 </itemizedlist>
145 </para>
146
147 <para>
148 <itemizedlist>
149 <listitem>
150 <para>
151 <code>
152 non -dev/-dbg/-nativesdk package contains symlink .so: &lt;packagename&gt; path '&lt;path&gt;' [dev-so]
153 </code>
154 </para>
155
156 <para>
157 Symlink <filename>.so</filename> files are for development
158 only, and should therefore go into the
159 <filename>-dev</filename> package.
160 This situation might occur if you add
161 <filename>*.so*</filename> rather than
162 <filename>*.so.*</filename> to a non-dev package.
163 Change
164 <link linkend='var-FILES'><filename>FILES</filename></link>
165 (and possibly
166 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
167 such that the specified <filename>.so</filename> file goes
168 into an appropriate <filename>-dev</filename> package.
169 </para>
170
171 <para>
172 &nbsp;
173 </para>
174 </listitem>
175 </itemizedlist>
176 </para>
177
178 <para>
179 <itemizedlist>
180 <listitem>
181 <para>
182 <code>
183 non -staticdev package contains static .a library: &lt;packagename&gt; path '&lt;path&gt;' [staticdev]
184 </code>
185 </para>
186
187 <para>
188 Static <filename>.a</filename> library files should go into
189 a <filename>-staticdev</filename> package.
190 Change
191 <link linkend='var-FILES'><filename>FILES</filename></link>
192 (and possibly
193 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
194 such that the specified <filename>.a</filename> file goes
195 into an appropriate <filename>-staticdev</filename> package.
196 </para>
197
198 <para>
199 &nbsp;
200 </para>
201 </listitem>
202 </itemizedlist>
203 </para>
204
205 <para>
206 <itemizedlist>
207 <listitem>
208 <para>
209 <code>
210 &lt;packagename&gt;: found library in wrong location [libdir]
211 </code>
212 </para>
213
214 <para>
215 The specified file may have been installed into an incorrect
216 (possibly hardcoded) installation path.
217 For example, this test will catch recipes that install
218 <filename>/lib/bar.so</filename> when
219 <filename>${base_libdir}</filename> is "lib32".
220 Another example is when recipes install
221 <filename>/usr/lib64/foo.so</filename> when
222 <filename>${libdir}</filename> is "/usr/lib".
223 False positives occasionally exist.
224 For these cases add "libdir" to
225 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
226 for the package.
227 </para>
228
229 <para>
230 &nbsp;
231 </para>
232 </listitem>
233 </itemizedlist>
234 </para>
235
236 <para>
237 <itemizedlist>
238 <listitem>
239 <para>
240 <code>
241 non debug package contains .debug directory: &lt;packagename&gt; path &lt;path&gt; [debug-files]
242 </code>
243 </para>
244
245 <para>
246 The specified package contains a
247 <filename>.debug</filename> directory, which should not
248 appear in anything but the <filename>-dbg</filename>
249 package.
250 This situation might occur if you add a path which contains
251 a <filename>.debug</filename> directory and do not
252 explicitly add the <filename>.debug</filename> directory
253 to the <filename>-dbg</filename> package.
254 If this is the case, add the <filename>.debug</filename>
255 directory explicitly to
256 <filename>FILES_${PN}-dbg</filename>.
257 See
258 <link linkend='var-FILES'><filename>FILES</filename></link>
259 for additional information on <filename>FILES</filename>.
260 </para>
261
262 <para>
263 &nbsp;
264 </para>
265 </listitem>
266 </itemizedlist>
267 </para>
268
269 <para>
270 <itemizedlist>
271 <listitem>
272 <para>
273 <code>
274 Architecture did not match (&lt;machine_arch&gt; to &lt;file_arch&gt;) on &lt;file&gt;
275 </code>
276 </para>
277
278 <para>
279 By default, the OpenEmbedded build system checks the
280 Executable and Linkable Format (ELF) type, bit size, and
281 endianness of any binaries to ensure they match the
282 target architecture.
283 This test fails if any binaries do not match the type since
284 there would be an incompatibility.
285 The test could indicate that the wrong compiler or compiler
286 options have been used.
287 Sometimes software, like bootloaders, might need to
288 bypass this check.
289 If the file you receive the error for is firmware
290 that is not intended to be executed within the target
291 operating system or is intended to run on a separate
292 processor within the device, you can add "arch" to
293 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
294 for the package.
295 Another option is to check the
296 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
297 log and verify that the compiler options being used
298 are correct.
299 </para>
300
301 <para>
302 &nbsp;
303 </para>
304 </listitem>
305 </itemizedlist>
306 </para>
307
308 <para>
309 <itemizedlist>
310 <listitem>
311 <para>
312 <code>
313 Bit size did not match (&lt;machine_bits&gt; to &lt;file_bits&gt;) &lt;recipe&gt; on &lt;file&gt;
314 </code>
315 </para>
316
317 <para>
318 By default, the OpenEmbedded build system checks
319 the Executable and Linkable Format (ELF) type,
320 bit size, and endianness of any binaries to ensure
321 they match the target architecture.
322 This test fails if any binaries do not match the type since
323 there would be an incompatibility.
324 The test could indicate that the wrong compiler or compiler
325 options have been used.
326 Sometimes software, like bootloaders, might need to
327 bypass this check.
328 If the file you receive the error for is firmware that
329 is not intended to be executed within the target
330 operating system or is intended to run on a separate
331 processor within the device, you can add "arch" to
332 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
333 for the package.
334 Another option is to check the
335 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
336 log and verify that the compiler options being used are
337 correct.
338 </para>
339
340 <para>
341 &nbsp;
342 </para>
343 </listitem>
344 </itemizedlist>
345 </para>
346
347 <para>
348 <itemizedlist>
349 <listitem>
350 <para>
351 <code>
352 Endianness did not match (&lt;machine_endianness&gt; to &lt;file_endianness&gt;) on &lt;file&gt; [arch]
353 </code>
354 </para>
355
356 <para>
357 By default, the OpenEmbedded build system checks
358 the Executable and Linkable Format (ELF) type, bit
359 size, and endianness of any binaries to ensure they
360 match the target architecture.
361 This test fails if any binaries do not match the type since
362 there would be an incompatibility.
363 The test could indicate that the wrong compiler or compiler
364 options have been used.
365 Sometimes software, like bootloaders, might need to
366 bypass this check.
367 If the file you receive the error for is firmware
368 that is not intended to be executed within the target
369 operating system or is intended to run on a separate
370 processor within the device, you can add "arch" to
371 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
372 for the package.
373 Another option is to check the
374 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
375 log and verify that the compiler options being used
376 are correct.
377 </para>
378
379 <para>
380 &nbsp;
381 </para>
382 </listitem>
383 </itemizedlist>
384 </para>
385
386 <para>
387 <itemizedlist>
388 <listitem>
389 <para>
390 <code>
391 ELF binary '&lt;file&gt;' has relocations in .text [textrel]
392 </code>
393 </para>
394
395 <para>
396 The specified ELF binary contains relocations in its
397 <filename>.text</filename> sections.
398 This situation can result in a performance impact
399 at runtime.
400 <note>
401 A bug currently exists that causes this
402 warning to appear erroneously.
403 See
404 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=6104'></ulink>
405 for more information.
406 </note>
407 </para>
408
409 <para>
410 &nbsp;
411 </para>
412 </listitem>
413 </itemizedlist>
414 </para>
415
416 <para>
417 <itemizedlist>
418 <listitem>
419 <para>
420 <code>
421 No GNU_HASH in the elf binary: '&lt;file&gt;' [ldflags]
422 </code>
423 </para>
424
425 <para>
426 This indicates that binaries produced when building the
427 recipe have not been linked with the
428 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
429 options provided by the build system.
430 Check to be sure that the <filename>LDFLAGS</filename>
431 variable is being passed to the linker command.
432 A common workaround for this situation is to pass in
433 <filename>LDFLAGS</filename> using
434 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
435 within the recipe as follows:
436 <literallayout class='monospaced'>
437 TARGET_CC_ARCH += "${LDFLAGS}"
438 </literallayout>
439 </para>
440
441 <para>
442 &nbsp;
443 </para>
444 </listitem>
445 </itemizedlist>
446 </para>
447
448 <para>
449 <itemizedlist>
450 <listitem>
451 <para>
452 <code>
453 Package &lt;packagename&gt; contains Xorg driver (&lt;driver&gt;) but no xorg-abi- dependencies [xorg-driver-abi]
454 </code>
455 </para>
456
457 <para>
458 The specified package contains an Xorg driver, but does not
459 have a corresponding ABI package dependency.
460 The xserver-xorg recipe provides driver ABI names.
461 All drivers should depend on the ABI versions that they have
462 been built against.
463 Driver recipes that include
464 <filename>xorg-driver-input.inc</filename> or
465 <filename>xorg-driver-video.inc</filename> will
466 automatically get these versions.
467 Consequently, you should only need to explicitly add
468 dependencies to binary driver recipes.
469 </para>
470
471 <para>
472 &nbsp;
473 </para>
474 </listitem>
475 </itemizedlist>
476 </para>
477
478 <para>
479 <itemizedlist>
480 <listitem>
481 <para>
482 <code>
483 The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]
484 </code>
485 </para>
486
487 <para>
488 The <filename>/usr/share/info/dir</filename> should not be
489 packaged.
490 Add the following line to your
491 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
492 task or to your <filename>do_install_append</filename>
493 within the recipe as follows:
494 <literallayout class='monospaced'>
495 rm ${D}${infodir}/dir
496 </literallayout>
497 </para>
498
499 <para>
500 &nbsp;
501 </para>
502 </listitem>
503 </itemizedlist>
504 </para>
505
506 <para>
507 <itemizedlist>
508 <listitem>
509 <para>
510 <code>
511 Symlink &lt;path&gt; in &lt;packagename&gt; points to TMPDIR [symlink-to-sysroot]
512 </code>
513 </para>
514
515 <para>
516 The specified symlink points into
517 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
518 on the host.
519 Such symlinks will work on the host.
520 However, they are clearly invalid when running on
521 the target.
522 You should either correct the symlink to use a relative
523 path or remove the symlink.
524 </para>
525
526 <para>
527 &nbsp;
528 </para>
529 </listitem>
530 </itemizedlist>
531 </para>
532
533 <para>
534 <itemizedlist>
535 <listitem>
536 <para>
537 <code>
538 &lt;file&gt; failed sanity test (workdir) in path &lt;path&gt; [la]
539 </code>
540 </para>
541
542 <para>
543 The specified <filename>.la</filename> file contains
544 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
545 paths.
546 Any <filename>.la</filename> file containing these paths
547 is incorrect since <filename>libtool</filename> adds the
548 correct sysroot prefix when using the files automatically
549 itself.
550 </para>
551
552 <para>
553 &nbsp;
554 </para>
555 </listitem>
556 </itemizedlist>
557 </para>
558
559 <para>
560 <itemizedlist>
561 <listitem>
562 <para>
563 <code>
564 &lt;file&gt; failed sanity test (tmpdir) in path &lt;path&gt; [pkgconfig]
565 </code>
566 </para>
567
568 <para>
569 The specified <filename>.pc</filename> file contains
570 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>/</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
571 paths.
572 Any <filename>.pc</filename> file containing these paths is
573 incorrect since <filename>pkg-config</filename> itself adds
574 the correct sysroot prefix when the files are accessed.
575 </para>
576
577 <para>
578 &nbsp;
579 </para>
580 </listitem>
581 </itemizedlist>
582 </para>
583
584 <para>
585 <itemizedlist>
586 <listitem>
587 <para>
588 <code>
589 &lt;packagename&gt; rdepends on &lt;debug_packagename&gt; [debug-deps]
590 </code>
591 </para>
592
593 <para>
594 A dependency exists between the specified non-dbg package
595 (i.e. a package whose name does not end in
596 <filename>-dbg</filename>) and a package that is a
597 <filename>dbg</filename> package.
598 The <filename>dbg</filename> packages contain
599 debug symbols and are brought in using several
600 different methods:
601 <itemizedlist>
602 <listitem><para>
603 Using the <filename>dbg-pkgs</filename>
604 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
605 value.
606 </para></listitem>
607 <listitem><para>
608 Using
609 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
610 </para></listitem>
611 <listitem><para>
612 As a dependency of another
613 <filename>dbg</filename> package that was brought
614 in using one of the above methods.
615 </para></listitem>
616 </itemizedlist>
617 The dependency might have been automatically added
618 because the <filename>dbg</filename> package erroneously
619 contains files that it should not contain (e.g. a
620 non-symlink <filename>.so</filename> file) or it might
621 have been added manually (e.g. by adding to
622 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
623 </para>
624
625 <para>
626 &nbsp;
627 </para>
628 </listitem>
629 </itemizedlist>
630 </para>
631
632 <para>
633 <itemizedlist>
634 <listitem>
635 <para>
636 <code>
637 &lt;packagename&gt; rdepends on &lt;dev_packagename&gt; [dev-deps]
638 </code>
639 </para>
640
641 <para>
642 A dependency exists between the specified non-dev package
643 (a package whose name does not end in
644 <filename>-dev</filename>) and a package that is a
645 <filename>dev</filename> package.
646 The <filename>dev</filename> packages contain development
647 headers and are usually brought in using several different
648 methods:
649 <itemizedlist>
650 <listitem><para>
651 Using the <filename>dev-pkgs</filename>
652 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
653 value.
654 </para></listitem>
655 <listitem><para>
656 Using
657 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
658 </para></listitem>
659 <listitem><para>
660 As a dependency of another
661 <filename>dev</filename> package that was brought
662 in using one of the above methods.
663 </para></listitem>
664 </itemizedlist>
665 The dependency might have been automatically added (because
666 the <filename>dev</filename> package erroneously contains
667 files that it should not have (e.g. a non-symlink
668 <filename>.so</filename> file) or it might have been added
669 manually (e.g. by adding to
670 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
671 </para>
672
673 <para>
674 &nbsp;
675 </para>
676 </listitem>
677 </itemizedlist>
678 </para>
679
680 <para>
681 <itemizedlist>
682 <listitem>
683 <para>
684 <code>
685 &lt;var&gt;_&lt;packagename&gt; is invalid: &lt;comparison&gt; (&lt;value&gt;) only comparisons &lt;, =, &gt;, &lt;=, and &gt;= are allowed [dep-cmp]
686 </code>
687 </para>
688
689 <para>
690 If you are adding a versioned dependency relationship to one
691 of the dependency variables
692 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
693 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
694 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
695 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
696 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
697 or
698 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>),
699 you must only use the named comparison operators.
700 Change the versioned dependency values you are adding
701 to match those listed in the message.
702 </para>
703
704 <para>
705 &nbsp;
706 </para>
707 </listitem>
708 </itemizedlist>
709 </para>
710
711 <para>
712 <itemizedlist>
713 <listitem>
714 <para>
715 <code>
716 &lt;recipename&gt;: The compile log indicates that host include and/or library paths were used. Please check the log '&lt;logfile&gt;' for more information. [compile-host-path]
717 </code>
718 </para>
719
720 <para>
721 The log for the
722 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
723 task indicates that paths on the host were searched
724 for files, which is not appropriate when cross-compiling.
725 Look for "is unsafe for cross-compilation" or "CROSS COMPILE
726 Badness" in the specified log file.
727 </para>
728
729 <para>
730 &nbsp;
731 </para>
732 </listitem>
733 </itemizedlist>
734 </para>
735
736 <para>
737 <itemizedlist>
738 <listitem>
739 <para>
740 <code>
741 &lt;recipename&gt;: The install log indicates that host include and/or library paths were used. Please check the log '&lt;logfile&gt;' for more information. [install-host-path]
742 </code>
743 </para>
744
745 <para>
746 The log for the
747 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
748 task indicates that paths on the host were searched
749 for files, which is not appropriate when cross-compiling.
750 Look for "is unsafe for cross-compilation"
751 or "CROSS COMPILE Badness" in the specified log file.
752 </para>
753
754 <para>
755 &nbsp;
756 </para>
757 </listitem>
758 </itemizedlist>
759 </para>
760
761 <para>
762 <itemizedlist>
763 <listitem>
764 <para>
765 <code>
766 This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '&lt;path&gt;'
767 </code>
768 </para>
769
770 <para>
771 The log for the
772 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
773 task indicates that paths on the host were searched
774 for files, which is not appropriate when cross-compiling.
775 Look for "is unsafe for cross-compilation" or
776 "CROSS COMPILE Badness" in the specified log file.
777 </para>
778
779 <para>
780 &nbsp;
781 </para>
782 </listitem>
783 </itemizedlist>
784 </para>
785
786 <para>
787 <itemizedlist>
788 <listitem>
789 <para>
790 <code>
791 &lt;packagename&gt; doesn't match the [a-z0-9.+-]+ regex [pkgname]
792 </code>
793 </para>
794
795 <para>
796 The convention within the OpenEmbedded build system
797 (sometimes enforced by the package manager itself) is to
798 require that package names are all lower case
799 and to allow a restricted set of characters.
800 If your recipe name does not match this, or you add
801 packages to
802 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
803 that do not conform to the convention, then you
804 will receive this error.
805 Rename your recipe.
806 Or, if you have added a non-conforming package name to
807 <filename>PACKAGES</filename>, change the package name
808 appropriately.
809 </para>
810
811 <para>
812 &nbsp;
813 </para>
814 </listitem>
815 </itemizedlist>
816 </para>
817
818 <para>
819 <itemizedlist>
820 <listitem>
821 <para>
822 <code>
823 &lt;recipe&gt;: configure was passed unrecognized options: &lt;options&gt; [unknown-configure-option]
824 </code>
825 </para>
826
827 <para>
828 The configure script is reporting that the specified
829 options are unrecognized.
830 This situation could be because the options
831 were previously valid but have been removed from the
832 configure script.
833 Or, there was a mistake when the options were added
834 and there is another option that should be used instead.
835 If you are unsure, consult the upstream build
836 documentation, the
837 <filename>./configure &dash;&dash;help</filename> output,
838 and the upstream change log or release notes.
839 Once you have worked out what the appropriate
840 change is, you can update
841 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
842 or the individual
843 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
844 option values accordingly.
845 </para>
846
847 <para>
848 &nbsp;
849 </para>
850 </listitem>
851 </itemizedlist>
852 </para>
853
854 <para>
855 <itemizedlist>
856 <listitem>
857 <para>
858 <code>
859 Recipe &lt;recipefile&gt; has PN of "&lt;recipename&gt;" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]
860 </code>
861 </para>
862
863 <para>
864 The specified recipe has a name
865 (<link linkend='var-PN'><filename>PN</filename></link>)
866 value that appears in
867 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
868 If a recipe is named such that its <filename>PN</filename>
869 value matches something already in
870 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
871 happens to be the same as
872 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
873 or
874 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
875 it can have unexpected consequences.
876 For example, assignments such as
877 <filename>FILES_${PN} = "xyz"</filename> effectively
878 turn into <filename>FILES = "xyz"</filename>.
879 Rename your recipe (or if <filename>PN</filename> is being
880 set explicitly, change the <filename>PN</filename> value) so
881 that the conflict does not occur.
882 See
883 <link linkend='var-FILES'><filename>FILES</filename></link>
884 for additional information.
885 </para>
886
887 <para>
888 &nbsp;
889 </para>
890 </listitem>
891 </itemizedlist>
892 </para>
893
894 <para>
895 <itemizedlist>
896 <listitem>
897 <para>
898 <code>
899 &lt;recipefile&gt;: Variable &lt;variable&gt; is set as not being package specific, please fix this. [pkgvarcheck]
900 </code>
901 </para>
902
903 <para>
904 Certain variables
905 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
906 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
907 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
908 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
909 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
910 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
911 <link linkend='var-FILES'><filename>FILES</filename></link>,
912 <filename>pkg_preinst</filename>,
913 <filename>pkg_postinst</filename>,
914 <filename>pkg_prerm</filename>,
915 <filename>pkg_postrm</filename>, and
916 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>)
917 should always be set specific to a package (i.e. they
918 should be set with a package name override such as
919 <filename>RDEPENDS_${PN} = "value"</filename> rather than
920 <filename>RDEPENDS = "value"</filename>).
921 If you receive this error, correct any assignments to these
922 variables within your recipe.
923 </para>
924
925 <para>
926 &nbsp;
927 </para>
928 </listitem>
929 </itemizedlist>
930 </para>
931
932 <para>
933 <itemizedlist>
934 <listitem>
935 <para>
936 <code>
937 File '&lt;file&gt;' from &lt;recipename&gt; was already stripped, this will prevent future debugging! [already-stripped]
938 </code>
939 </para>
940
941 <para>
942 Produced binaries have already been stripped prior to the
943 build system extracting debug symbols.
944 It is common for upstream software projects to default to
945 stripping debug symbols for output binaries.
946 In order for debugging to work on the target using
947 <filename>-dbg</filename> packages, this stripping must be
948 disabled.
949 Depending on the build system used by the software being
950 built, disabling this stripping could be as easy as
951 specifying an additional configure option.
952 If not, disabling stripping might involve patching
953 the build scripts.
954 <note>
955 Disabling stripping here does not mean that the final
956 packaged binaries will be unstripped.
957 Once the OpenEmbedded build system splits out debug
958 symbols to the <filename>-dbg</filename> package,
959 it will then strip the symbols from the binaries.
960 </note>
961 </para>
962
963 <para>
964 &nbsp;
965 </para>
966 </listitem>
967 </itemizedlist>
968 </para>
969
970 <para>
971 <itemizedlist>
972 <listitem>
973 <para>
974 <code>
975 &lt;packagename&gt; is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]
976 </code>
977 </para>
978
979 <para>
980 Package names must appear only once in the
981 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
982 variable.
983 You might receive this error if you are attempting to add a
984 package to <filename>PACKAGES</filename> that is
985 already in the variable's value.
986 </para>
987
988 <para>
989 &nbsp;
990 </para>
991 </listitem>
992 </itemizedlist>
993 </para>
994
995 <para>
996 <itemizedlist>
997 <listitem>
998 <para>
999 <code>
1000 FILES variable for package &lt;packagename&gt; contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]
1001 </code>
1002 </para>
1003
1004 <para>
1005 The string "//" is invalid in a Unix path.
1006 Correct all occurrences where this string appears in a
1007 <link linkend='var-FILES'><filename>FILES</filename></link>
1008 variable so that there is only a single "/".
1009 </para>
1010
1011 <para>
1012 &nbsp;
1013 </para>
1014 </listitem>
1015 </itemizedlist>
1016 </para>
1017
1018 <para>
1019 <itemizedlist>
1020 <listitem>
1021 <para>
1022 <code>
1023 &lt;recipename&gt;: Files/directories were installed but not shipped [installed-vs-shipped]
1024 </code>
1025 </para>
1026
1027 <para>
1028 Files have been installed within the
1029 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1030 task but have not been included in any package by way of the
1031 <link linkend='var-FILES'><filename>FILES</filename></link>
1032 variable.
1033 Files that do not appear in any package cannot be present in
1034 an image later on in the build process.
1035 You need to do one of the following:
1036 <itemizedlist>
1037 <listitem><para>
1038 Add the files to <filename>FILES</filename> for the
1039 package you want them to appear in (e.g.
1040 <filename>FILES_${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename> for the main
1041 package).
1042 </para></listitem>
1043 <listitem><para>
1044 Delete the files at the end of the
1045 <filename>do_install</filename> task if the files
1046 are not needed in any package.
1047 </para></listitem>
1048 </itemizedlist>
1049 </para>
1050
1051 <para>
1052 &nbsp;
1053 </para>
1054 </listitem>
1055 </itemizedlist>
1056 </para>
1057
1058 <para>
1059 <itemizedlist>
1060 <listitem>
1061 <para>
1062 <code>
1063 &lt;oldpackage&gt;-&lt;oldpkgversion&gt; was registered as shlib provider for &lt;library&gt;, changing it to &lt;newpackage&gt;-&lt;newpkgversion&gt; because it was built later
1064 </code>
1065 </para>
1066
1067 <para>
1068 This message means that both
1069 <filename>&lt;oldpackage&gt;</filename> and
1070 <filename>&lt;newpackage&gt;</filename> provide the specified
1071 shared library.
1072 You can expect this message when a recipe has been renamed.
1073 However, if that is not the case, the message might indicate
1074 that a private version of a library is being erroneously
1075 picked up as the provider for a common library.
1076 If that is the case, you should add the library's
1077 <filename>.so</filename> file name to
1078 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
1079 in the recipe that provides
1080 the private version of the library.
1081 </para>
1082 </listitem>
1083 </itemizedlist>
1084 </para>
1085
1086<!--
1087Here are some messages that might be documented in the future.
1088Right now we are not documenting them because the QA checks are not
1089enabled by default:
1090
1091 <para>
1092 <itemizedlist>
1093 <listitem><para>
1094 <literallayout class='monospaced'>
1095 Desktop file issue: &lt;error&gt; [desktop]
1096 </literallayout>
1097 NEED A DESCRIPTION AND SOLUTION
1098 </para></listitem>
1099 </itemizedlist>
1100 </para>
1101
1102 <para>
1103 <itemizedlist>
1104 <listitem><para>
1105 <literallayout class='monospaced'>
1106 &lt;packagename&gt;: &lt;file&gt;, installed in the base_prefix, requires a shared library under exec_prefix (&lt;exec_prefix&t;g) [unsafe-references-in-binaries]
1107 </literallayout>
1108 NEED A DESCRIPTION AND SOLUTION
1109 </para></listitem>
1110 </itemizedlist>
1111 </para>
1112
1113 <para>
1114 <itemizedlist>
1115 <listitem><para>
1116 <literallayout class='monospaced'>
1117 &lt;packagename&gt;: Found a reference to &lt;exec_prefix&gt;/ in &lt;path&gt; - Shell scripts in base_bindir and base_sbindir should not reference anything in exec_prefix [unsafe-references-in-scripts]
1118 </literallayout>
1119 NEED A DESCRIPTION AND SOLUTION
1120 </para></listitem>
1121 </itemizedlist>
1122 </para>
1123-->
1124</section>
1125
1126<section id='configuring-and-disabling-qa-checks'>
1127 <title>Configuring and Disabling QA Checks</title>
1128
1129 <para>
1130 You can configure the QA checks globally so that specific check
1131 failures either raise a warning or an error message, using the
1132 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
1133 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
1134 variables, respectively.
1135 You can also disable checks within a particular recipe using
1136 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
1137 For information on how to work with the QA checks, see the
1138 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1139 section.
1140 <note><title>Tip</title>
1141 Please keep in mind that the QA checks exist in order to
1142 detect real or potential problems in the packaged output.
1143 So exercise caution when disabling these checks.
1144 </note>
1145 </para>
1146</section>
1147
1148</chapter>
1149<!--
1150vim: expandtab tw=80 ts=4
1151-->
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
new file mode 100644
index 0000000..389e75a
--- /dev/null
+++ b/documentation/ref-manual/ref-structure.xml
@@ -0,0 +1,1130 @@
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 When you run this script, your Yocto Project environment is set
215 up, a
216 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
217 is created, your working directory becomes the Build Directory,
218 and you are presented with a list of common BitBake targets.
219 Here is an example:
220 <literallayout class='monospaced'>
221 $ source oe-init-build-env
222
223 ### Shell environment set up for builds. ###
224
225 You can now run 'bitbake &lt;target&gt;'
226
227 Common targets are:
228 core-image-minimal
229 core-image-sato
230 meta-toolchain
231 adt-installer
232 meta-ide-support
233
234 You can also run generated qemu images with a command like 'runqemu qemux86'
235 </literallayout>
236 The script gets its default list of common targets from the
237 <filename>conf-notes.txt</filename> file, which is found in the
238 <filename>meta-yocto</filename> directory within the
239 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
240 Should you have custom distributions, it is very easy to modify
241 this configuration file to include your targets for your
242 distribution.
243 See the
244 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
245 section in the Yocto Project Development Manual for more
246 information.
247 </para>
248
249 <para>
250 By default, running this script without a
251 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
252 argument creates the <filename>build</filename> directory
253 in your current working directory.
254 If you provide a Build Directory argument when you
255 <filename>source</filename> the script, you direct the OpenEmbedded
256 build system to create a Build Directory of your choice.
257 For example, the following command creates a Build Directory named
258 <filename>mybuilds</filename> that is outside of the
259 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
260 <literallayout class='monospaced'>
261 $ source &OE_INIT_FILE; ~/mybuilds
262 </literallayout>
263 The OpenEmbedded build system uses the template configuration
264 files, which are found by default in the
265 <filename>meta-yocto/conf</filename> directory in the
266 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
267 See the
268 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
269 section in the Yocto Project Development Manual for more
270 information.
271 <note>
272 The OpenEmbedded build system does not support file or directory names that
273 contain spaces.
274 If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
275 from a Source Directory that contains spaces in either the filenames
276 or directory names, the script returns an error indicating no such
277 file or directory.
278 Be sure to use a Source Directory free of names containing spaces.
279 </note>
280 </para>
281 </section>
282
283 <section id='structure-memres-core-script'>
284 <title><filename>oe-init-build-env-memres</filename></title>
285
286 <para>
287 This script is one of two scripts that set up the OpenEmbedded
288 build environment.
289 Aside from setting up the environment, this script starts a
290 memory-resident BitBake server.
291 For information on the other setup script, see the
292 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
293 section.
294 </para>
295
296 <para>
297 Memory-resident BitBake resides in memory until you specifically
298 remove it using the following BitBake command:
299 <literallayout class='monospaced'>
300 $ bitbake -m
301 </literallayout>
302 </para>
303
304 <para>
305 Running this script with the <filename>source</filename> command in
306 a shell makes changes to <filename>PATH</filename> and sets other
307 core BitBake variables based on the current working directory.
308 One of these variables is the
309 <link linkend='var-BBSERVER'><filename>BBSERVER</filename></link>
310 variable, which allows the OpenEmbedded build system to locate
311 the server that is running BitBake.
312 </para>
313
314 <para>
315 You need to run an environment setup script before using BitBake
316 commands.
317 Following is the script syntax:
318 <literallayout class='monospaced'>
319 $ source oe-init-build-env-memres &lt;port_number&gt; &lt;build_dir&gt;
320 </literallayout>
321 The script uses other scripts within the
322 <filename>scripts</filename> directory to do the bulk of the work.
323 </para>
324
325 <para>
326 If you do not provide a port number with the script, the
327 BitBake server at port "12345" is started.
328 </para>
329
330 <para>
331 When you run this script, your Yocto Project environment is set
332 up, a
333 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
334 is created, your working directory becomes the Build Directory,
335 and you are presented with a list of common BitBake targets.
336 Here is an example:
337 <literallayout class='monospaced'>
338 $ source oe-init-build-env-memres
339 No port specified, using dynamically selected port
340
341 ### Shell environment set up for builds. ###
342
343 You can now run 'bitbake &lt;target&gt;'
344
345 Common targets are:
346 core-image-minimal
347 core-image-sato
348 meta-toolchain
349 adt-installer
350 meta-ide-support
351
352 You can also run generated qemu images with a command like 'runqemu qemux86'
353 Bitbake server started on demand as needed, use bitbake -m to shut it down
354 </literallayout>
355 The script gets its default list of common targets from the
356 <filename>conf-notes.txt</filename> file, which is found in the
357 <filename>meta-yocto</filename> directory within the
358 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
359 Should you have custom distributions, it is very easy to modify
360 this configuration file to include your targets for your
361 distribution.
362 See the
363 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
364 section in the Yocto Project Development Manual for more
365 information.
366 </para>
367
368 <para>
369 By default, running this script without a
370 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
371 argument creates a build directory named
372 <filename>build</filename>.
373 If you provide a Build Directory argument when you
374 <filename>source</filename> the script, the Build Directory is
375 created using that name.
376 For example, the following command starts the BitBake server using
377 the default port "12345" and creates a Build Directory named
378 <filename>mybuilds</filename> that is outside of the
379 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
380 <literallayout class='monospaced'>
381 $ source oe-init-build-env-memres ~/mybuilds
382 </literallayout>
383 The OpenEmbedded build system uses the template configuration
384 files, which are found by default in the
385 <filename>meta-yocto/conf</filename> directory in the
386 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
387 See the
388 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
389 section in the Yocto Project Development Manual for more
390 information.
391 <note>
392 The OpenEmbedded build system does not support file or
393 directory names that contain spaces.
394 If you attempt to run the
395 <filename>oe-init-build-env-memres</filename> script
396 from a Source Directory that contains spaces in either the
397 filenames or directory names, the script returns an error
398 indicating no such file or directory.
399 Be sure to use a Source Directory free of names containing
400 spaces.
401 </note>
402 </para>
403 </section>
404
405 <section id='structure-basic-top-level'>
406 <title><filename>LICENSE, README, and README.hardware</filename></title>
407
408 <para>
409 These files are standard top-level files.
410 </para>
411 </section>
412</section>
413
414<section id='structure-build'>
415 <title>The Build Directory - <filename>build/</filename></title>
416
417 <para>
418 The OpenEmbedded build system creates the
419 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
420 when you run one of the build environment setup scripts (i.e.
421 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
422 or
423 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
424 </para>
425
426 <para>
427 If you do not give the Build Directory a specific name when you run
428 a setup script, the name defaults to <filename>build</filename>.
429 </para>
430
431 <para>
432 The
433 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable
434 points to the Build Directory.
435 </para>
436
437 <section id='structure-build-buildhistory'>
438 <title><filename>build/buildhistory</filename></title>
439
440 <para>
441 The OpenEmbedded build system creates this directory when you
442 enable the build history feature.
443 The directory tracks build information into image, packages, and
444 SDK subdirectories.
445 For information on the build history feature, see the
446 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
447 section.
448 </para>
449 </section>
450
451 <section id='structure-build-conf-local.conf'>
452 <title><filename>build/conf/local.conf</filename></title>
453
454 <para>
455 This configuration file contains all the local user configurations
456 for your build environment.
457 The <filename>local.conf</filename> file contains documentation on
458 the various configuration options.
459 Any variable set here overrides any variable set elsewhere within
460 the environment unless that variable is hard-coded within a file
461 (e.g. by using '=' instead of '?=').
462 Some variables are hard-coded for various reasons but these
463 variables are relatively rare.
464 </para>
465
466 <para>
467 Edit this file to set the
468 <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
469 for which you want to build, which package types you wish to use
470 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
471 the location from which you want to access downloaded files
472 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
473 and how you want your host machine to use resources
474 (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
475 and
476 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
477 </para>
478
479 <para>
480 If <filename>local.conf</filename> is not present when you
481 start the build, the OpenEmbedded build system creates it from
482 <filename>local.conf.sample</filename> when
483 you <filename>source</filename> the top-level build environment
484 setup script (i.e.
485 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
486 or
487 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
488 </para>
489
490 <para>
491 The source <filename>local.conf.sample</filename> file used
492 depends on the <filename>$TEMPLATECONF</filename> script variable,
493 which defaults to <filename>meta-yocto/conf</filename>
494 when you are building from the Yocto Project development
495 environment and defaults to <filename>meta/conf</filename> when
496 you are building from the OpenEmbedded Core environment.
497 Because the script variable points to the source of the
498 <filename>local.conf.sample</filename> file, this implies that
499 you can configure your build environment from any layer by setting
500 the variable in the top-level build environment setup script as
501 follows:
502 <literallayout class='monospaced'>
503 TEMPLATECONF=&lt;your_layer&gt;/conf
504 </literallayout>
505 Once the build process gets the sample file, it uses
506 <filename>sed</filename> to substitute final
507 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
508 values for all <filename>##OEROOT##</filename> values.
509 <note>
510 You can see how the <filename>TEMPLATECONF</filename> variable
511 is used by looking at the
512 <filename>scripts/oe-setup-builddir</filename> script in the
513 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
514 You can find the Yocto Project version of the
515 <filename>local.conf.sample</filename> file in the
516 <filename>meta-yocto/conf</filename> directory.
517 </note>
518 </para>
519 </section>
520
521 <section id='structure-build-conf-bblayers.conf'>
522 <title><filename>build/conf/bblayers.conf</filename></title>
523
524 <para>
525 This configuration file defines
526 <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
527 which are directory trees, traversed (or walked) by BitBake.
528 The <filename>bblayers.conf</filename> file uses the
529 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
530 variable to list the layers BitBake tries to find, and uses the
531 <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
532 variable to list layers that must not be removed.
533 </para>
534
535 <para>
536 If <filename>bblayers.conf</filename> is not present when you
537 start the build, the OpenEmbedded build system creates it from
538 <filename>bblayers.conf.sample</filename> when
539 you <filename>source</filename> the top-level build environment
540 setup script (i.e.
541 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
542 or
543 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
544 </para>
545
546 <para>
547 The source <filename>bblayers.conf.sample</filename> file used
548 depends on the <filename>$TEMPLATECONF</filename> script variable,
549 which defaults to <filename>meta-yocto/conf</filename>
550 when you are building from the Yocto Project development
551 environment and defaults to <filename>meta/conf</filename> when
552 you are building from the OpenEmbedded Core environment.
553 Because the script variable points to the source of the
554 <filename>bblayers.conf.sample</filename> file, this implies that
555 you can base your build from any layer by setting the variable in
556 the top-level build environment setup script as follows:
557 <literallayout class='monospaced'>
558 TEMPLATECONF=&lt;your_layer&gt;/conf
559 </literallayout>
560 Once the build process gets the sample file, it uses
561 <filename>sed</filename> to substitute final
562 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
563 values for all <filename>##OEROOT##</filename> values.
564 <note>
565 You can see how the <filename>TEMPLATECONF</filename> variable
566 <filename>scripts/oe-setup-builddir</filename> script in the
567 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
568 You can find the Yocto Project version of the
569 <filename>bblayers.conf.sample</filename> file in the
570 <filename>meta-yocto/conf</filename> directory.
571 </note>
572 </para>
573 </section>
574
575 <section id='structure-build-conf-sanity_info'>
576 <title><filename>build/conf/sanity_info</filename></title>
577
578 <para>
579 This file indicates the state of the sanity checks and is created
580 during the build.
581 </para>
582 </section>
583
584 <section id='structure-build-downloads'>
585 <title><filename>build/downloads/</filename></title>
586
587 <para>
588 This directory contains downloaded upstream source tarballs.
589 You can reuse the directory for multiple builds or move
590 the directory to another location.
591 You can control the location of this directory through the
592 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
593 </para>
594 </section>
595
596 <section id='structure-build-sstate-cache'>
597 <title><filename>build/sstate-cache/</filename></title>
598
599 <para>
600 This directory contains the shared state cache.
601 You can reuse the directory for multiple builds or move
602 the directory to another location.
603 You can control the location of this directory through the
604 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
605 </para>
606 </section>
607
608 <section id='structure-build-tmp'>
609 <title><filename>build/tmp/</filename></title>
610
611 <para>
612 The OpenEmbedded build system creates and uses this directory
613 for all the build system's output.
614 The
615 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
616 variable points to this directory.
617 </para>
618
619 <para>
620 BitBake creates this directory if it does not exist.
621 As a last resort, to clean up a build and start it from scratch
622 (other than the downloads), you can remove everything in the
623 <filename>tmp</filename> directory or get rid of the
624 directory completely.
625 If you do, you should also completely remove the
626 <filename>build/sstate-cache</filename> directory.
627 </para>
628 </section>
629
630 <section id='structure-build-tmp-buildstats'>
631 <title><filename>build/tmp/buildstats/</filename></title>
632
633 <para>
634 This directory stores the build statistics.
635 </para>
636 </section>
637
638 <section id='structure-build-tmp-cache'>
639 <title><filename>build/tmp/cache/</filename></title>
640
641 <para>
642 When BitBake parses the metadata, it creates a cache file of the result that can
643 be used when subsequently running commands.
644 BitBake stores these results here on a per-machine basis.
645 </para>
646 </section>
647
648 <section id='structure-build-tmp-deploy'>
649 <title><filename>build/tmp/deploy/</filename></title>
650
651 <para>
652 This directory contains any "end result" output from the
653 OpenEmbedded build process.
654 The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
655 variable points to this directory.
656 For more detail on the contents of the <filename>deploy</filename>
657 directory, see the
658 "<link linkend='images-dev-environment'>Images</link>" and
659 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
660 sections.
661 </para>
662 </section>
663
664 <section id='structure-build-tmp-deploy-deb'>
665 <title><filename>build/tmp/deploy/deb/</filename></title>
666
667 <para>
668 This directory receives any <filename>.deb</filename> packages produced by
669 the build process.
670 The packages are sorted into feeds for different architecture types.
671 </para>
672 </section>
673
674 <section id='structure-build-tmp-deploy-rpm'>
675 <title><filename>build/tmp/deploy/rpm/</filename></title>
676
677 <para>
678 This directory receives any <filename>.rpm</filename> packages produced by
679 the build process.
680 The packages are sorted into feeds for different architecture types.
681 </para>
682 </section>
683
684 <section id='structure-build-tmp-deploy-ipk'>
685 <title><filename>build/tmp/deploy/ipk/</filename></title>
686
687 <para>
688 This directory receives <filename>.ipk</filename> packages produced by
689 the build process.
690 </para>
691 </section>
692
693 <section id='structure-build-tmp-deploy-licenses'>
694 <title><filename>build/tmp/deploy/licenses/</filename></title>
695
696 <para>
697 This directory receives package licensing information.
698 For example, the directory contains sub-directories for <filename>bash</filename>,
699 <filename>busybox</filename>, and <filename>eglibc</filename> (among others) that in turn
700 contain appropriate <filename>COPYING</filename> license files with other licensing information.
701 For information on licensing, see the
702 "<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>"
703 section.
704 </para>
705 </section>
706
707 <section id='structure-build-tmp-deploy-images'>
708 <title><filename>build/tmp/deploy/images/</filename></title>
709
710 <para>
711 This directory receives complete filesystem images.
712 If you want to flash the resulting image from a build onto a device, look here for the image.
713 </para>
714
715 <para>
716 Be careful when deleting files in this directory.
717 You can safely delete old images from this directory (e.g.
718 <filename>core-image-*</filename>, <filename>hob-image-*</filename>,
719 etc.).
720 However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
721 bootloader and other supplementary files might be deployed here prior to building an
722 image.
723 Because these files are not directly produced from the image, if you
724 delete them they will not be automatically re-created when you build the image again.
725 </para>
726
727 <para>
728 If you do accidentally delete files here, you will need to force them to be
729 re-created.
730 In order to do that, you will need to know the target that produced them.
731 For example, these commands rebuild and re-create the kernel files:
732 <literallayout class='monospaced'>
733 $ bitbake -c clean virtual/kernel
734 $ bitbake virtual/kernel
735 </literallayout>
736 </para>
737 </section>
738
739 <section id='structure-build-tmp-deploy-sdk'>
740 <title><filename>build/tmp/deploy/sdk/</filename></title>
741
742 <para>
743 The OpenEmbedded build system creates this directory to hold
744 toolchain installer scripts, which when executed, install the
745 sysroot that matches your target hardware.
746 You can find out more about these installers in the
747 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
748 section in the Yocto Project Application Developer's Guide.
749 </para>
750 </section>
751
752 <section id='structure-build-tmp-sstate-control'>
753 <title><filename>build/tmp/sstate-control/</filename></title>
754
755 <para>
756 The OpenEmbedded build system uses this directory for the
757 shared state manifest files.
758 The shared state code uses these files to record the files
759 installed by each sstate task so that the files can be removed
760 when cleaning the recipe or when a newer version is about to
761 be installed.
762 The build system also uses the manifests to detect and produce
763 a warning when files from one task are overwriting those from
764 another.
765 </para>
766 </section>
767
768 <section id='structure-build-tmp-sysroots'>
769 <title><filename>build/tmp/sysroots/</filename></title>
770
771 <para>
772 This directory contains shared header files and libraries as well as other shared
773 data.
774 Packages that need to share output with other packages do so within this directory.
775 The directory is subdivided by architecture so multiple builds can run within
776 the one Build Directory.
777 </para>
778 </section>
779
780 <section id='structure-build-tmp-stamps'>
781 <title><filename>build/tmp/stamps/</filename></title>
782
783 <para>
784 This directory holds information that BitBake uses for accounting purposes
785 to track what tasks have run and when they have run.
786 The directory is sub-divided by architecture, package name, and
787 version.
788 Following is an example:
789 <literallayout class='monospaced'>
790 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
791 </literallayout>
792 Although the files in the directory are empty of data,
793 BitBake uses the filenames and timestamps for tracking purposes.
794 </para>
795 </section>
796
797 <section id='structure-build-tmp-log'>
798 <title><filename>build/tmp/log/</filename></title>
799
800 <para>
801 This directory contains general logs that are not otherwise placed using the
802 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
803 Examples of logs are the output from the
804 <filename>do_check_pkg</filename> or
805 <filename>do_distro_check</filename> tasks.
806 Running a build does not necessarily mean this directory is created.
807 </para>
808 </section>
809
810 <section id='structure-build-tmp-work'>
811 <title><filename>build/tmp/work/</filename></title>
812
813 <para>
814 This directory contains architecture-specific work sub-directories
815 for packages built by BitBake.
816 All tasks execute from the appropriate work directory.
817 For example, the source for a particular package is unpacked,
818 patched, configured and compiled all within its own work directory.
819 Within the work directory, organization is based on the package group
820 and version for which the source is being compiled
821 as defined by the
822 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
823 </para>
824
825 <para>
826 It is worth considering the structure of a typical work directory.
827 As an example, consider <filename>linux-yocto-kernel-3.0</filename>
828 on the machine <filename>qemux86</filename>
829 built within the Yocto Project.
830 For this package, a work directory of
831 <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
832 referred to as the
833 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
834 Within this directory, the source is unpacked to
835 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt.
836 (See the
837 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using a Quilt Flow</ulink>"
838 section in the Yocto Project Development Manual for more information.)
839 Within the <filename>linux-qemux86-standard-build</filename> directory,
840 standard Quilt directories <filename>linux-3.0/patches</filename>
841 and <filename>linux-3.0/.pc</filename> are created,
842 and standard Quilt commands can be used.
843 </para>
844
845 <para>
846 There are other directories generated within <filename>WORKDIR</filename>.
847 The most important directory is <filename>WORKDIR/temp/</filename>,
848 which has log files for each task (<filename>log.do_*.pid</filename>)
849 and contains the scripts BitBake runs for each task
850 (<filename>run.do_*.pid</filename>).
851 The <filename>WORKDIR/image/</filename> directory is where "make
852 install" places its output that is then split into sub-packages
853 within <filename>WORKDIR/packages-split/</filename>.
854 </para>
855 </section>
856
857 <section id='structure-build-work-shared'>
858 <title><filename>build/tmp/work-shared/</filename></title>
859
860 <para>
861 For efficiency, the OpenEmbedded build system creates and uses
862 this directory to hold recipes that share a work directory with
863 other recipes.
864 In practice, this is only used for <filename>gcc</filename>
865 and its variants (e.g. <filename>gcc-cross</filename>,
866 <filename>libgcc</filename>, <filename>gcc-runtime</filename>,
867 and so forth).
868 </para>
869 </section>
870</section>
871
872<section id='structure-meta'>
873 <title>The Metadata - <filename>meta/</filename></title>
874
875 <para>
876 As mentioned previously,
877 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> is the core
878 of the Yocto Project.
879 Metadata has several important subdivisions:
880 </para>
881
882 <section id='structure-meta-classes'>
883 <title><filename>meta/classes/</filename></title>
884
885 <para>
886 This directory contains the <filename>*.bbclass</filename> files.
887 Class files are used to abstract common code so it can be reused by multiple
888 packages.
889 Every package inherits the <filename>base.bbclass</filename> file.
890 Examples of other important classes are <filename>autotools.bbclass</filename>, which
891 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
892 Another example is <filename>kernel.bbclass</filename> that contains common code and functions
893 for working with the Linux kernel.
894 Functions like image generation or packaging also have their specific class files
895 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
896 <filename>package*.bbclass</filename>.
897 </para>
898
899 <para>
900 For reference information on classes, see the
901 "<link linkend='ref-classes'>Classes</link>" chapter.
902 </para>
903 </section>
904
905 <section id='structure-meta-conf'>
906 <title><filename>meta/conf/</filename></title>
907
908 <para>
909 This directory contains the core set of configuration files that start from
910 <filename>bitbake.conf</filename> and from which all other configuration
911 files are included.
912 See the include statements at the end of the
913 <filename>bitbake.conf</filename> file and you will note that even
914 <filename>local.conf</filename> is loaded from there.
915 While <filename>bitbake.conf</filename> sets up the defaults, you can often override
916 these by using the (<filename>local.conf</filename>) file, machine file or
917 the distribution configuration file.
918 </para>
919 </section>
920
921 <section id='structure-meta-conf-machine'>
922 <title><filename>meta/conf/machine/</filename></title>
923
924 <para>
925 This directory contains all the machine configuration files.
926 If you set <filename>MACHINE = "qemux86"</filename>,
927 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
928 directory.
929 The <filename>include</filename> directory contains various data common to multiple machines.
930 If you want to add support for a new machine to the Yocto Project, look in this directory.
931 </para>
932 </section>
933
934 <section id='structure-meta-conf-distro'>
935 <title><filename>meta/conf/distro/</filename></title>
936
937 <para>
938 The contents of this directory controls any distribution-specific
939 configurations.
940 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
941 This directory includes the versions and the
942 <filename>SRCDATE</filename> definitions for applications that are configured here.
943 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
944 Although this file mainly inherits its configuration from Poky.
945 </para>
946 </section>
947
948 <section id='structure-meta-conf-machine-sdk'>
949 <title><filename>meta/conf/machine-sdk/</filename></title>
950
951 <para>
952 The OpenEmbedded build system searches this directory for
953 configuration files that correspond to the value of
954 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
955 By default, 32-bit and 64-bit x86 files ship with the Yocto
956 Project that support some SDK hosts.
957 However, it is possible to extend that support to other SDK hosts
958 by adding additional configuration files in this subdirectory
959 within another layer.
960 </para>
961 </section>
962
963 <section id='structure-meta-files'>
964 <title><filename>meta/files/</filename></title>
965
966 <para>
967 This directory contains common license files and several text files
968 used by the build system.
969 The text files contain minimal device information and
970 lists of files and directories with known permissions.
971 </para>
972 </section>
973
974 <section id='structure-meta-lib'>
975 <title><filename>meta/lib/</filename></title>
976
977 <para>
978 This directory contains OpenEmbedded Python library code
979 used during the build process.
980 </para>
981 </section>
982
983 <section id='structure-meta-recipes-bsp'>
984 <title><filename>meta/recipes-bsp/</filename></title>
985
986 <para>
987 This directory contains anything linking to specific hardware or hardware
988 configuration information such as "u-boot" and "grub".
989 </para>
990 </section>
991
992 <section id='structure-meta-recipes-connectivity'>
993 <title><filename>meta/recipes-connectivity/</filename></title>
994
995 <para>
996 This directory contains libraries and applications related to communication with other devices.
997 </para>
998 </section>
999
1000 <section id='structure-meta-recipes-core'>
1001 <title><filename>meta/recipes-core/</filename></title>
1002
1003 <para>
1004 This directory contains what is needed to build a basic working Linux image
1005 including commonly used dependencies.
1006 </para>
1007 </section>
1008
1009 <section id='structure-meta-recipes-devtools'>
1010 <title><filename>meta/recipes-devtools/</filename></title>
1011
1012 <para>
1013 This directory contains tools that are primarily used by the build system.
1014 The tools, however, can also be used on targets.
1015 </para>
1016 </section>
1017
1018 <section id='structure-meta-recipes-extended'>
1019 <title><filename>meta/recipes-extended/</filename></title>
1020
1021 <para>
1022 This directory contains non-essential applications that add features compared to the
1023 alternatives in core.
1024 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
1025 compliance.
1026 </para>
1027 </section>
1028
1029 <section id='structure-meta-recipes-gnome'>
1030 <title><filename>meta/recipes-gnome/</filename></title>
1031
1032 <para>
1033 This directory contains all things related to the GTK+ application framework.
1034 </para>
1035 </section>
1036
1037 <section id='structure-meta-recipes-graphics'>
1038 <title><filename>meta/recipes-graphics/</filename></title>
1039
1040 <para>
1041 This directory contains X and other graphically related system libraries
1042 </para>
1043 </section>
1044
1045 <section id='structure-meta-recipes-kernel'>
1046 <title><filename>meta/recipes-kernel/</filename></title>
1047
1048 <para>
1049 This directory contains the kernel and generic applications and libraries that
1050 have strong kernel dependencies.
1051 </para>
1052 </section>
1053
1054 <section id='structure-meta-recipes-lsb4'>
1055 <title><filename>meta/recipes-lsb4/</filename></title>
1056
1057 <para>
1058 This directory contains recipes specifically added to support
1059 the Linux Standard Base (LSB) version 4.x.
1060 </para>
1061 </section>
1062
1063 <section id='structure-meta-recipes-multimedia'>
1064 <title><filename>meta/recipes-multimedia/</filename></title>
1065
1066 <para>
1067 This directory contains codecs and support utilities for audio, images and video.
1068 </para>
1069 </section>
1070
1071 <section id='structure-meta-recipes-qt'>
1072 <title><filename>meta/recipes-qt/</filename></title>
1073
1074 <para>
1075 This directory contains all things related to the Qt application framework.
1076 </para>
1077 </section>
1078
1079 <section id='structure-meta-recipes-rt'>
1080 <title><filename>meta/recipes-rt/</filename></title>
1081
1082 <para>
1083 This directory contains package and image recipes for using and testing
1084 the <filename>PREEMPT_RT</filename> kernel.
1085 </para>
1086 </section>
1087
1088 <section id='structure-meta-recipes-sato'>
1089 <title><filename>meta/recipes-sato/</filename></title>
1090
1091 <para>
1092 This directory contains the Sato demo/reference UI/UX and its associated applications
1093 and configuration data.
1094 </para>
1095 </section>
1096
1097 <section id='structure-meta-recipes-support'>
1098 <title><filename>meta/recipes-support/</filename></title>
1099
1100 <para>
1101 This directory contains recipes used by other recipes, but that are
1102 not directly included in images (i.e. dependencies of other
1103 recipes).
1104 </para>
1105 </section>
1106
1107 <section id='structure-meta-site'>
1108 <title><filename>meta/site/</filename></title>
1109
1110 <para>
1111 This directory contains a list of cached results for various architectures.
1112 Because certain "autoconf" test results cannot be determined when cross-compiling due to
1113 the tests not able to run on a live system, the information in this directory is
1114 passed to "autoconf" for the various architectures.
1115 </para>
1116 </section>
1117
1118 <section id='structure-meta-recipes-txt'>
1119 <title><filename>meta/recipes.txt</filename></title>
1120
1121 <para>
1122 This file is a description of the contents of <filename>recipes-*</filename>.
1123 </para>
1124 </section>
1125</section>
1126
1127</chapter>
1128<!--
1129vim: expandtab tw=80 ts=4
1130-->
diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css
new file mode 100644
index 0000000..e04b500
--- /dev/null
+++ b/documentation/ref-manual/ref-style.css
@@ -0,0 +1,985 @@
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/* This style defines how the permalink character
317 appears by itself and when hovered over with
318 the mouse. */
319
320[alt='Permalink'] { color: #eee; }
321[alt='Permalink']:hover { color: black; }
322
323
324div.informalfigure,
325div.informalexample,
326div.informaltable,
327div.figure,
328div.table,
329div.example {
330 margin: 1em 0em;
331 padding: 1em;
332 page-break-inside: avoid;
333}
334
335
336div.informalfigure p.title b,
337div.informalexample p.title b,
338div.informaltable p.title b,
339div.figure p.title b,
340div.example p.title b,
341div.table p.title b{
342 padding-top: 0em;
343 margin-top: 0em;
344 font-size: 100%;
345 font-weight: normal;
346}
347
348.mediaobject .caption,
349.mediaobject .caption p {
350 text-align: center;
351 font-size: 80%;
352 padding-top: 0.5em;
353 padding-bottom: 0.5em;
354}
355
356.epigraph {
357 padding-left: 55%;
358 margin-bottom: 1em;
359}
360
361.epigraph p {
362 text-align: left;
363}
364
365.epigraph .quote {
366 font-style: italic;
367}
368.epigraph .attribution {
369 font-style: normal;
370 text-align: right;
371}
372
373span.application {
374 font-style: italic;
375}
376
377.programlisting {
378 font-family: monospace;
379 font-size: 80%;
380 white-space: pre;
381 margin: 1.33em 0em;
382 padding: 1.33em;
383}
384
385.tip,
386.warning,
387.caution,
388.note {
389 margin-top: 1em;
390 margin-bottom: 1em;
391
392}
393
394/* force full width of table within div */
395.tip table,
396.warning table,
397.caution table,
398.note table {
399 border: none;
400 width: 100%;
401}
402
403
404.tip table th,
405.warning table th,
406.caution table th,
407.note table th {
408 padding: 0.8em 0.0em 0.0em 0.0em;
409 margin : 0em 0em 0em 0em;
410}
411
412.tip p,
413.warning p,
414.caution p,
415.note p {
416 margin-top: 0.5em;
417 margin-bottom: 0.5em;
418 padding-right: 1em;
419 text-align: left;
420}
421
422.acronym {
423 text-transform: uppercase;
424}
425
426b.keycap,
427.keycap {
428 padding: 0.09em 0.3em;
429 margin: 0em;
430}
431
432.itemizedlist li {
433 clear: none;
434}
435
436.filename {
437 font-size: medium;
438 font-family: Courier, monospace;
439}
440
441
442div.navheader, div.heading{
443 position: absolute;
444 left: 0em;
445 top: 0em;
446 width: 100%;
447 background-color: #cdf;
448 width: 100%;
449}
450
451div.navfooter, div.footing{
452 position: fixed;
453 left: 0em;
454 bottom: 0em;
455 background-color: #eee;
456 width: 100%;
457}
458
459
460div.navheader td,
461div.navfooter td {
462 font-size: 66%;
463}
464
465div.navheader table th {
466 /*font-family: Georgia, Times, serif;*/
467 /*font-size: x-large;*/
468 font-size: 80%;
469}
470
471div.navheader table {
472 border-left: 0em;
473 border-right: 0em;
474 border-top: 0em;
475 width: 100%;
476}
477
478div.navfooter table {
479 border-left: 0em;
480 border-right: 0em;
481 border-bottom: 0em;
482 width: 100%;
483}
484
485div.navheader table td a,
486div.navfooter table td a {
487 color: #777;
488 text-decoration: none;
489}
490
491/* normal text in the footer */
492div.navfooter table td {
493 color: black;
494}
495
496div.navheader table td a:visited,
497div.navfooter table td a:visited {
498 color: #444;
499}
500
501
502/* links in header and footer */
503div.navheader table td a:hover,
504div.navfooter table td a:hover {
505 text-decoration: underline;
506 background-color: transparent;
507 color: #33a;
508}
509
510div.navheader hr,
511div.navfooter hr {
512 display: none;
513}
514
515
516.qandaset tr.question td p {
517 margin: 0em 0em 1em 0em;
518 padding: 0em 0em 0em 0em;
519}
520
521.qandaset tr.answer td p {
522 margin: 0em 0em 1em 0em;
523 padding: 0em 0em 0em 0em;
524}
525.answer td {
526 padding-bottom: 1.5em;
527}
528
529.emphasis {
530 font-weight: bold;
531}
532
533
534 /************* /
535 / decorations /
536/ *************/
537
538.titlepage {
539}
540
541.part .title {
542}
543
544.subtitle {
545 border: none;
546}
547
548/*
549h1 {
550 border: none;
551}
552
553h2 {
554 border-top: solid 0.2em;
555 border-bottom: solid 0.06em;
556}
557
558h3 {
559 border-top: 0em;
560 border-bottom: solid 0.06em;
561}
562
563h4 {
564 border: 0em;
565 border-bottom: solid 0.06em;
566}
567
568h5 {
569 border: 0em;
570}
571*/
572
573.programlisting {
574 border: solid 1px;
575}
576
577div.figure,
578div.table,
579div.informalfigure,
580div.informaltable,
581div.informalexample,
582div.example {
583 border: 1px solid;
584}
585
586
587
588.tip,
589.warning,
590.caution,
591.note {
592 border: 1px solid;
593}
594
595.tip table th,
596.warning table th,
597.caution table th,
598.note table th {
599 border-bottom: 1px solid;
600}
601
602.question td {
603 border-top: 1px solid black;
604}
605
606.answer {
607}
608
609
610b.keycap,
611.keycap {
612 border: 1px solid;
613}
614
615
616div.navheader, div.heading{
617 border-bottom: 1px solid;
618}
619
620
621div.navfooter, div.footing{
622 border-top: 1px solid;
623}
624
625 /********* /
626 / colors /
627/ *********/
628
629body {
630 color: #333;
631 background: white;
632}
633
634a {
635 background: transparent;
636}
637
638a:hover {
639 background-color: #dedede;
640}
641
642
643h1,
644h2,
645h3,
646h4,
647h5,
648h6,
649h7,
650h8 {
651 background-color: transparent;
652}
653
654hr {
655 border-color: #aaa;
656}
657
658
659.tip, .warning, .caution, .note {
660 border-color: #fff;
661}
662
663
664.tip table th,
665.warning table th,
666.caution table th,
667.note table th {
668 border-bottom-color: #fff;
669}
670
671
672.warning {
673 background-color: #f0f0f2;
674}
675
676.caution {
677 background-color: #f0f0f2;
678}
679
680.tip {
681 background-color: #f0f0f2;
682}
683
684.note {
685 background-color: #f0f0f2;
686}
687
688.glossary dl dt,
689.variablelist dl dt,
690.variablelist dl dt span.term {
691 color: #044;
692}
693
694div.figure,
695div.table,
696div.example,
697div.informalfigure,
698div.informaltable,
699div.informalexample {
700 border-color: #aaa;
701}
702
703pre.programlisting {
704 color: black;
705 background-color: #fff;
706 border-color: #aaa;
707 border-width: 2px;
708}
709
710.guimenu,
711.guilabel,
712.guimenuitem {
713 background-color: #eee;
714}
715
716
717b.keycap,
718.keycap {
719 background-color: #eee;
720 border-color: #999;
721}
722
723
724div.navheader {
725 border-color: black;
726}
727
728
729div.navfooter {
730 border-color: black;
731}
732
733
734 /*********** /
735 / graphics /
736/ ***********/
737
738/*
739body {
740 background-image: url("images/body_bg.jpg");
741 background-attachment: fixed;
742}
743
744.navheader,
745.note,
746.tip {
747 background-image: url("images/note_bg.jpg");
748 background-attachment: fixed;
749}
750
751.warning,
752.caution {
753 background-image: url("images/warning_bg.jpg");
754 background-attachment: fixed;
755}
756
757.figure,
758.informalfigure,
759.example,
760.informalexample,
761.table,
762.informaltable {
763 background-image: url("images/figure_bg.jpg");
764 background-attachment: fixed;
765}
766
767*/
768h1,
769h2,
770h3,
771h4,
772h5,
773h6,
774h7{
775}
776
777/*
778Example of how to stick an image as part of the title.
779
780div.article .titlepage .title
781{
782 background-image: url("figures/white-on-black.png");
783 background-position: center;
784 background-repeat: repeat-x;
785}
786*/
787
788div.preface .titlepage .title,
789div.colophon .title,
790div.chapter .titlepage .title,
791div.article .titlepage .title
792{
793}
794
795div.section div.section .titlepage .title,
796div.sect2 .titlepage .title {
797 background: none;
798}
799
800
801h1.title {
802 background-color: transparent;
803 background-image: url("figures/poky-title.png");
804 background-repeat: no-repeat;
805 height: 256px;
806 text-indent: -9000px;
807 overflow:hidden;
808}
809
810h2.subtitle {
811 background-color: transparent;
812 text-indent: -9000px;
813 overflow:hidden;
814 width: 0px;
815 display: none;
816}
817
818 /*************************************** /
819 / pippin.gimp.org specific alterations /
820/ ***************************************/
821
822/*
823div.heading, div.navheader {
824 color: #777;
825 font-size: 80%;
826 padding: 0;
827 margin: 0;
828 text-align: left;
829 position: absolute;
830 top: 0px;
831 left: 0px;
832 width: 100%;
833 height: 50px;
834 background: url('/gfx/heading_bg.png') transparent;
835 background-repeat: repeat-x;
836 background-attachment: fixed;
837 border: none;
838}
839
840div.heading a {
841 color: #444;
842}
843
844div.footing, div.navfooter {
845 border: none;
846 color: #ddd;
847 font-size: 80%;
848 text-align:right;
849
850 width: 100%;
851 padding-top: 10px;
852 position: absolute;
853 bottom: 0px;
854 left: 0px;
855
856 background: url('/gfx/footing_bg.png') transparent;
857}
858*/
859
860
861
862 /****************** /
863 / nasty ie tweaks /
864/ ******************/
865
866/*
867div.heading, div.navheader {
868 width:expression(document.body.clientWidth + "px");
869}
870
871div.footing, div.navfooter {
872 width:expression(document.body.clientWidth + "px");
873 margin-left:expression("-5em");
874}
875body {
876 padding:expression("4em 5em 0em 5em");
877}
878*/
879
880 /**************************************** /
881 / mozilla vendor specific css extensions /
882/ ****************************************/
883/*
884div.navfooter, div.footing{
885 -moz-opacity: 0.8em;
886}
887
888div.figure,
889div.table,
890div.informalfigure,
891div.informaltable,
892div.informalexample,
893div.example,
894.tip,
895.warning,
896.caution,
897.note {
898 -moz-border-radius: 0.5em;
899}
900
901b.keycap,
902.keycap {
903 -moz-border-radius: 0.3em;
904}
905*/
906
907table tr td table tr td {
908 display: none;
909}
910
911
912hr {
913 display: none;
914}
915
916table {
917 border: 0em;
918}
919
920 .photo {
921 float: right;
922 margin-left: 1.5em;
923 margin-bottom: 1.5em;
924 margin-top: 0em;
925 max-width: 17em;
926 border: 1px solid gray;
927 padding: 3px;
928 background: white;
929}
930 .seperator {
931 padding-top: 2em;
932 clear: both;
933 }
934
935 #validators {
936 margin-top: 5em;
937 text-align: right;
938 color: #777;
939 }
940 @media print {
941 body {
942 font-size: 8pt;
943 }
944 .noprint {
945 display: none;
946 }
947 }
948
949
950.tip,
951.note {
952 background: #f0f0f2;
953 color: #333;
954 padding: 20px;
955 margin: 20px;
956}
957
958.tip h3,
959.note h3 {
960 padding: 0em;
961 margin: 0em;
962 font-size: 2em;
963 font-weight: bold;
964 color: #333;
965}
966
967.tip a,
968.note a {
969 color: #333;
970 text-decoration: underline;
971}
972
973.footnote {
974 font-size: small;
975 color: #333;
976}
977
978/* Changes the announcement text */
979.tip h3,
980.warning h3,
981.caution h3,
982.note h3 {
983 font-size:large;
984 color: #00557D;
985}
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
new file mode 100644
index 0000000..fc23a7b
--- /dev/null
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -0,0 +1,684 @@
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-tasks'>
6<title>Tasks</title>
7
8<para>
9 Tasks are units of execution for BitBake.
10 Recipes (<filename>.bb</filename> files) use tasks to complete
11 configuring, compiling, and packaging software.
12 This chapter provides a reference of the tasks defined in the
13 OpenEmbedded build system.
14</para>
15
16<section id='normal-recipe-build-tasks'>
17 <title>Normal Recipe Build Tasks</title>
18
19 <para>
20 The following sections describe normal tasks associated with building
21 a recipe.
22 </para>
23
24 <section id='ref-tasks-build'>
25 <title><filename>do_build</filename></title>
26
27 <para>
28 The default task for all recipes.
29 This task depends on all other normal tasks
30 required to build a recipe.
31 </para>
32 </section>
33
34 <section id='ref-tasks-compile'>
35 <title><filename>do_compile</filename></title>
36
37 <para>
38 Compiles the source in the compilation directory, which is pointed
39 to by the
40 <link linkend='var-B'><filename>B</filename></link> variable.
41 </para>
42 </section>
43
44 <section id='ref-tasks-compile_ptest_base'>
45 <title><filename>do_compile_ptest_base</filename></title>
46
47 <para>
48 Compiles the runtime test suite included in the software being
49 built.
50 </para>
51 </section>
52
53 <section id='ref-tasks-configure'>
54 <title><filename>do_configure</filename></title>
55
56 <para>
57 Configures the source by enabling and disabling any build-time and
58 configuration options for the software being built.
59 </para>
60 </section>
61
62 <section id='ref-tasks-configure_ptest_base'>
63 <title><filename>do_configure_ptest_base</filename></title>
64
65 <para>
66 Configures the runtime test suite included in the software being
67 built.
68 </para>
69 </section>
70
71 <section id='ref-tasks-deploy'>
72 <title><filename>do_deploy</filename></title>
73
74 <para>
75 Writes output files that are to be deployed to the deploy
76 directory, which is defined by the
77 <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>
78 variable.
79 </para>
80
81 <para>
82 The <filename>do_deploy</filename> task is a
83 shared state (sstate) task, which means that the task can
84 be accelerated through sstate use.
85 Realize also that if the task is re-executed, any previous output
86 is removed (i.e. "cleaned").
87 </para>
88 </section>
89
90 <section id='ref-tasks-fetch'>
91 <title><filename>do_fetch</filename></title>
92
93 <para>
94 Fetches the source code.
95 This task uses the
96 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
97 variable and the argument's prefix to determine the correct
98 fetcher module.
99 </para>
100 </section>
101
102 <section id='ref-tasks-install'>
103 <title><filename>do_install</filename></title>
104
105 <para>
106 Copies files from the compilation directory, which is defined by
107 the
108 <link linkend='var-B'><filename>B</filename></link> variable,
109 to a holding area defined by the
110 <link linkend='var-D'><filename>D</filename></link> variable.
111 </para>
112 </section>
113
114 <section id='ref-tasks-install_ptest_base'>
115 <title><filename>do_install_ptest_base</filename></title>
116
117 <para>
118 Copies the runtime test suite files from the compilation directory
119 to a holding area.
120 </para>
121 </section>
122
123 <section id='ref-tasks-package'>
124 <title><filename>do_package</filename></title>
125
126 <para>
127 Analyzes the content of the holding area and splits it into subsets
128 based on available packages and files.
129 </para>
130 </section>
131
132 <section id='ref-tasks-package_write_deb'>
133 <title><filename>do_package_write_deb</filename></title>
134
135 <para>
136 Creates the actual DEB packages and places them in the
137 <link linkend='package-feeds-dev-environment'>Package Feeds</link>
138 area.
139 </para>
140 </section>
141
142 <section id='ref-tasks-package_write_ipk'>
143 <title><filename>do_package_write_ipk</filename></title>
144
145 <para>
146 Creates the actual IPK packages and places them in the
147 <link linkend='package-feeds-dev-environment'>Package Feeds</link>
148 area.
149 </para>
150 </section>
151
152 <section id='ref-tasks-package_write_rpm'>
153 <title><filename>do_package_write_rpm</filename></title>
154
155 <para>
156 Creates the actual RPM packages and places them in the
157 <link linkend='package-feeds-dev-environment'>Package Feeds</link>
158 area.
159 </para>
160 </section>
161
162 <section id='ref-tasks-package_write_tar'>
163 <title><filename>do_package_write_tar</filename></title>
164
165 <para>
166 Creates tar archives for packages and places them in the
167 <link linkend='package-feeds-dev-environment'>Package Feeds</link>
168 area.
169 </para>
170 </section>
171
172 <section id='ref-tasks-packagedata'>
173 <title><filename>do_packagedata</filename></title>
174
175 <para>
176 Creates package metadata used by the build system to generate the
177 final packages.
178 </para>
179 </section>
180
181 <section id='ref-tasks-patch'>
182 <title><filename>do_patch</filename></title>
183
184 <para>
185 Locates patch files and applies them to the source code.
186 See the
187 "<link linkend='patching-dev-environment'>Patching</link>"
188 section for more information.
189 </para>
190 </section>
191
192 <section id='ref-tasks-populate_lic'>
193 <title><filename>do_populate_lic</filename></title>
194
195 <para>
196 Writes license information for the recipe that is collected later
197 when the image is constructed.
198 </para>
199 </section>
200
201 <section id='ref-tasks-populate_sdk'>
202 <title><filename>do_populate_sdk</filename></title>
203
204 <para>
205 Creates the file and directory structure for an installable SDK.
206 See the
207 "<link linkend='sdk-generation-dev-environment'>SDK Generation</link>"
208 section for more information.
209 </para>
210 </section>
211
212 <section id='ref-tasks-populate_sysroot'>
213 <title><filename>do_populate_sysroot</filename></title>
214
215 <para>
216 Copies a subset of files installed by the
217 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
218 task into the sysroot in order to make them available to other
219 recipes.
220 </para>
221
222 <para>
223 The <filename>do_populate_sysroot</filename> task is a
224 shared state (sstate) task, which means that the task can
225 be accelerated through sstate use.
226 Realize also that if the task is re-executed, any previous output
227 is removed (i.e. "cleaned").
228 </para>
229 </section>
230
231 <section id='ref-tasks-rm_work'>
232 <title><filename>do_rm_work</filename></title>
233
234 <para>
235 Removes work files after the OpenEmbedded build system has
236 finished with them.
237 You can learn more by looking at the
238 "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
239 section.
240 </para>
241 </section>
242
243 <section id='ref-tasks-rm_work_all'>
244 <title><filename>do_rm_work_all</filename></title>
245
246 <para>
247 Top-level task for removing work files after the build system has
248 finished with them.
249 </para>
250 </section>
251
252 <section id='ref-tasks-unpack'>
253 <title><filename>do_unpack</filename></title>
254
255 <para>
256 Unpacks the source code into a working directory pointed to
257 by
258 <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename>.
259 The
260 <link linkend='var-S'><filename>S</filename></link> variable also
261 plays a role in where unpacked source files ultimately reside.
262 For more information on how source files are unpacked, see the
263 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
264 section and the <filename>WORKDIR</filename> and
265 <filename>S</filename> variable descriptions.
266 </para>
267 </section>
268</section>
269
270<section id='manually-called-tasks'>
271 <title>Manually Called Tasks</title>
272
273 <para>
274 These tasks are typically manually triggered (e.g. by using the
275 <filename>bitbake -c</filename> command-line option):
276 </para>
277
278 <section id='ref-tasks-checkuri'>
279 <title><filename>do_checkuri</filename></title>
280
281 <para>
282 Validates the
283 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
284 value.
285 </para>
286 </section>
287
288 <section id='ref-tasks-checkuriall'>
289 <title><filename>do_checkuriall</filename></title>
290
291 <para>
292 Validates the
293 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
294 value for all recipes required to build a target.
295 </para>
296 </section>
297
298 <section id='ref-tasks-clean'>
299 <title><filename>do_clean</filename></title>
300
301 <para>
302 Removes all output files for a target from the
303 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
304 task forward (i.e.
305 <link linkend='ref-tasks-patch'><filename>do_unpack</filename></link>,
306 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
307 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
308 <link linkend='ref-tasks-install'><filename>do_install</filename></link>,
309 and
310 <link linkend='ref-tasks-package'><filename>do_package</filename></link>).
311 </para>
312
313 <para>
314 You can run this task using BitBake as follows:
315 <literallayout class='monospaced'>
316 $ bitbake -c clean &lt;recipe&gt;
317 </literallayout>
318 </para>
319
320 <para>
321 Running this task does not remove the
322 <link linkend='shared-state-cache'>sstate</link>) cache
323 files.
324 Consequently, if no changes have been made and the recipe is
325 rebuilt after cleaning, output files are simply restored from the
326 sstate cache.
327 If you want to remove the sstate cache files for the recipe,
328 you need to use the
329 <link linkend='ref-tasks-cleansstate'><filename>do_cleansstate</filename></link>
330 task instead (i.e. <filename>bitbake -c cleansstate &lt;recipe&gt;</filename>).
331 </para>
332 </section>
333
334 <section id='ref-tasks-cleanall'>
335 <title><filename>do_cleanall</filename></title>
336
337 <para>
338 Removes all output files, shared state
339 (<link linkend='shared-state-cache'>sstate</link>) cache, and
340 downloaded source files for a target (i.e. the contents of
341 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>).
342 Essentially, the <filename>do_cleanall</filename> task is
343 identical to the
344 <link linkend='ref-tasks-cleansstate'><filename>do_cleansstate</filename></link>
345 task with the added removal of downloaded source files.
346 </para>
347
348 <para>
349 You can run this task using BitBake as follows:
350 <literallayout class='monospaced'>
351 $ bitbake -c cleanall &lt;recipe&gt;
352 </literallayout>
353 </para>
354
355 <para>
356 Typically, you would not normally use the
357 <filename>cleanall</filename> task.
358 Do so only if you want to start fresh with the
359 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
360 task.
361 </para>
362 </section>
363
364 <section id='ref-tasks-cleansstate'>
365 <title><filename>do_cleansstate</filename></title>
366
367 <para>
368 Removes all output files and shared state
369 (<link linkend='shared-state-cache'>sstate</link>)
370 cache for a target.
371 Essentially, the <filename>do_cleansstate</filename> task is
372 identical to the
373 <link linkend='ref-tasks-clean'><filename>do_clean</filename></link>
374 task with the added removal of shared state
375 (<link linkend='shared-state-cache'>sstate</link>) cache.
376 </para>
377
378 <para>
379 You can run this task using BitBake as follows:
380 <literallayout class='monospaced'>
381 $ bitbake -c cleansstate &lt;recipe&gt;
382 </literallayout>
383 </para>
384
385 <para>
386 When you run the <filename>do_cleansstate</filename> task,
387 the OpenEmbedded build system no longer uses any
388 sstate.
389 Consequently, building the recipe from scratch is guaranteed.
390 <note>
391 The <filename>do_cleansstate</filename> task cannot remove
392 sstate from a remote sstate mirror.
393 If you need to build a target from scratch using remote
394 mirrors, use the "-f" option as follows:
395 <literallayout class='monospaced'>
396 $ bitbake -f -c do_cleansstate &lt;target&gt;
397 </literallayout>
398 </note>
399 </para>
400 </section>
401
402 <section id='ref-tasks-devshell'>
403 <title><filename>do_devshell</filename></title>
404
405 <para>
406 Starts a shell whose environment is set up for
407 development, debugging, or both.
408 See the
409 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>"
410 section in the Yocto Project Development Manual for more
411 information about using <filename>devshell</filename>.
412 </para>
413 </section>
414
415 <section id='ref-tasks-fetchall'>
416 <title><filename>do_fetchall</filename></title>
417
418 <para>
419 Fetches all remote sources required to build a target.
420 </para>
421 </section>
422
423 <section id='ref-tasks-listtasks'>
424 <title><filename>do_listtasks</filename></title>
425
426 <para>
427 Lists all defined tasks for a target.
428 </para>
429 </section>
430
431 <section id='ref-tasks-package_index'>
432 <title><filename>do_package_index</filename></title>
433
434 <para>
435 Creates or updates the index in the
436 <link linkend='package-feeds-dev-environment'>Package Feeds</link>
437 area.
438 <note>
439 This task is not triggered with the
440 <filename>bitbake -c</filename> command-line option as
441 are the other tasks in this section.
442 Because this task is specifically for the
443 <filename>package-index</filename> recipe,
444 you run it using
445 <filename>bitbake package-index</filename>.
446 </note>
447 </para>
448 </section>
449</section>
450
451<section id='image-related-tasks'>
452 <title>Image-Related Tasks</title>
453
454 <para>
455 The following tasks are applicable to image recipes.
456 </para>
457
458 <section id='ref-tasks-bootimg'>
459 <title><filename>do_bootimg</filename></title>
460
461 <para>
462 Creates a bootable live image.
463 See the
464 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
465 variable for additional information on live image types.
466 </para>
467 </section>
468
469 <section id='ref-tasks-bundle_initramfs'>
470 <title><filename>do_bundle_initramfs</filename></title>
471
472 <para>
473 Combines an initial RAM disk (initramfs) image and kernel
474 together to form a single image.
475 The
476 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
477 variable has some more information about these types of images.
478 </para>
479 </section>
480
481 <section id='ref-tasks-rootfs'>
482 <title><filename>do_rootfs</filename></title>
483
484 <para>
485 Creates the root filesystem (file and directory structure) for an
486 image.
487 See the
488 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
489 section for more information on how the root filesystem is created.
490 </para>
491 </section>
492
493 <section id='ref-tasks-testimage'>
494 <title><filename>do_testimage</filename></title>
495
496 <para>
497 Boots an image and performs runtime tests within the image.
498 For information on automatically testing images, see the
499 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
500 section in the Yocto Project Development Manual.
501 </para>
502 </section>
503
504 <section id='ref-tasks-testimage_auto'>
505 <title><filename>do_testimage_auto</filename></title>
506
507 <para>
508 Boots an image and performs runtime tests within the image
509 immediately after it has been built.
510 This task is enabled when you set
511 <link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link>
512 equal to "1".
513 </para>
514
515 <para>
516 For information on automatically testing images, see the
517 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
518 section in the Yocto Project Development Manual.
519 </para>
520 </section>
521
522 <section id='ref-tasks-vmdkimg'>
523 <title><filename>do_vmdkimg</filename></title>
524
525 <para>
526 Creates a <filename>.vmdk</filename> image for use with
527 <ulink url='http://www.vmware.com/'>VMware</ulink>
528 and compatible virtual machine hosts.
529 </para>
530 </section>
531</section>
532
533<section id='kernel-related-tasks'>
534 <title>Kernel-Related Tasks</title>
535
536 <para>
537 The following tasks are applicable to kernel recipes.
538 Some of these tasks (e.g. the
539 <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link>
540 task) are also applicable to recipes that use
541 Linux kernel style configuration such as the BusyBox recipe.
542 </para>
543
544 <section id='ref-tasks-compile_kernelmodules'>
545 <title><filename>do_compile_kernelmodules</filename></title>
546
547 <para>
548 Compiles loadable modules for the Linux kernel.
549 </para>
550 </section>
551
552 <section id='ref-tasks-diffconfig'>
553 <title><filename>do_diffconfig</filename></title>
554
555 <para>
556 Compares the old and new config files after running the
557 <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link>
558 task for the kernel.
559 </para>
560 </section>
561
562 <section id='ref-tasks-kernel_checkout'>
563 <title><filename>do_kernel_checkout</filename></title>
564
565 <para>
566 Checks out source/meta branches for a linux-yocto style kernel.
567 </para>
568 </section>
569
570 <section id='ref-tasks-kernel_configcheck'>
571 <title><filename>do_kernel_configcheck</filename></title>
572
573 <para>
574 Validates the kernel configuration for a linux-yocto style kernel.
575 </para>
576 </section>
577
578 <section id='ref-tasks-kernel_configme'>
579 <title><filename>do_kernel_configme</filename></title>
580
581 <para>
582 Assembles the kernel configuration for a linux-yocto style kernel.
583 </para>
584 </section>
585
586 <section id='ref-tasks-kernel_link_vmlinux'>
587 <title><filename>do_kernel_link_vmlinux</filename></title>
588
589 <para>
590 Creates a symbolic link in
591 <filename>arch/$arch/boot</filename> for vmlinux kernel
592 images.
593 </para>
594 </section>
595
596 <section id='ref-tasks-menuconfig'>
597 <title><filename>do_menuconfig</filename></title>
598
599 <para>
600 Runs <filename>make menuconfig</filename> for the kernel.
601 For information on <filename>menuconfig</filename>, see the
602 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using&nbsp;&nbsp;<filename>menuconfig</filename></ulink>"
603 section in the Yocto Project Development Manual.
604 </para>
605 </section>
606
607 <section id='ref-tasks-savedefconfig'>
608 <title><filename>do_savedefconfig</filename></title>
609
610 <para>
611 Creates a minimal Linux kernel configuration file.
612 </para>
613 </section>
614
615 <section id='ref-tasks-sizecheck'>
616 <title><filename>do_sizecheck</filename></title>
617
618 <para>
619 Checks the size of the kernel image against
620 <filename>KERNEL_IMAGE_MAXSIZE</filename> when set.
621 </para>
622 </section>
623
624 <section id='ref-tasks-strip'>
625 <title><filename>do_strip</filename></title>
626
627 <para>
628 Strips unneeded sections out of the Linux kernel image.
629 </para>
630 </section>
631
632 <section id='ref-tasks-uboot_mkimage'>
633 <title><filename>do_uboot_mkimage</filename></title>
634
635 <para>
636 Creates a uImage file from the kernel for the U-Boot bootloader.
637 </para>
638 </section>
639
640 <section id='ref-tasks-validate_branches'>
641 <title><filename>do_validate_branches</filename></title>
642
643 <para>
644 Ensures that the source, metadata (or both) branches are on the
645 locations specified by their
646 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
647 values for a linux-yocto style kernel.
648 </para>
649 </section>
650</section>
651
652<section id='miscellaneous-tasks'>
653 <title>Miscellaneous Tasks</title>
654
655 <para>
656 The following sections describe miscellaneous tasks.
657 </para>
658
659 <section id='ref-tasks-generate_qt_config_file'>
660 <title><filename>do_generate_qt_config_file</filename></title>
661
662 <para>
663 Writes a <filename>qt.conf</filename> configuration
664 file used for building a Qt-based application.
665 </para>
666 </section>
667
668 <section id='ref-tasks-spdx'>
669 <title><filename>do_spdx</filename></title>
670
671 <para>
672 A build stage that takes the source code and scans it on a remote
673 FOSSOLOGY server in order to produce an SPDX document.
674 This task applies only to the
675 <link linkend='ref-classes-spdx'><filename>spdx</filename></link>
676 class.
677 </para>
678 </section>
679</section>
680
681</chapter>
682<!--
683vim: expandtab tw=80 ts=4
684-->
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
new file mode 100644
index 0000000..c34188d
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,9714 @@
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-ABIEXTENSION'>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-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm>
50 <glossdef>
51 <para>
52 Extension to the Application Binary Interface (ABI)
53 field of the GNU canonical architecture name
54 (e.g. "eabi").
55 </para>
56
57 <para>
58 ABI extensions are set in the machine include files.
59 For example, the
60 <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>
61 file sets the following extension:
62 <literallayout class='monospaced'>
63 ABIEXTENSION = "eabi"
64 </literallayout>
65 </para>
66 </glossdef>
67 </glossentry>
68
69 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
70 <glossdef>
71 <para>
72 Specifies if an output package should still be produced if it is empty.
73 By default, BitBake does not produce empty packages.
74 This default behavior can cause issues when there is an
75 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
76 some other hard runtime requirement on the existence of the package.
77 </para>
78
79 <para>
80 Like all package-controlling variables, you must always use them in
81 conjunction with a package name override, as in:
82 <literallayout class='monospaced'>
83 ALLOW_EMPTY_${PN} = "1"
84 ALLOW_EMPTY_${PN}-dev = "1"
85 ALLOW_EMPTY_${PN}-staticdev = "1"
86 </literallayout>
87 </para>
88 </glossdef>
89 </glossentry>
90
91 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
92 <glossdef>
93 <para>
94 Lists commands in a package that need an alternative
95 binary naming scheme.
96 Sometimes the same command is provided in multiple packages.
97 When this occurs, the OpenEmbedded build system needs to
98 use the alternatives system to create a different binary
99 naming scheme so the commands can co-exist.
100 </para>
101
102 <para>
103 To use the variable, list out the package's commands
104 that also exist as part of another package.
105 For example, if the <filename>busybox</filename> package
106 has four commands that also exist as part of another
107 package, you identify them as follows:
108 <literallayout class='monospaced'>
109 ALTERNATIVE_busybox = "sh sed test bracket"
110 </literallayout>
111 For more information on the alternatives system, see the
112 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
113 section.
114 </para>
115 </glossdef>
116 </glossentry>
117
118 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
119 <glossdef>
120 <para>
121 Used by the alternatives system to map duplicated commands
122 to actual locations.
123 For example, if the <filename>bracket</filename> command
124 provided by the <filename>busybox</filename> package is
125 duplicated through another package, you must use the
126 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
127 specify the actual location:
128 <literallayout class='monospaced'>
129 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
130 </literallayout>
131 In this example, the binary for the
132 <filename>bracket</filename> command (i.e.
133 <filename>[</filename>) from the
134 <filename>busybox</filename> package resides in
135 <filename>/usr/bin/</filename>.
136 <note>
137 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
138 defined, it defaults to
139 <filename>${bindir}/&lt;name&gt;</filename>.
140 </note>
141 </para>
142
143 <para>
144 For more information on the alternatives system, see the
145 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
146 section.
147 </para>
148 </glossdef>
149 </glossentry>
150
151 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
152 <glossdef>
153 <para>
154 Used by the alternatives system to create default
155 priorities for duplicated commands.
156 You can use the variable to create a single default
157 regardless of the command name or package, a default for
158 specific duplicated commands regardless of the package, or
159 a default for specific commands tied to particular packages.
160 Here are the available syntax forms:
161 <literallayout class='monospaced'>
162 ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
163 ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
164 ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
165 </literallayout>
166 </para>
167
168 <para>
169 For more information on the alternatives system, see the
170 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
171 section.
172 </para>
173 </glossdef>
174 </glossentry>
175
176 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
177 <glossdef>
178 <para>
179 Used by the alternatives system to create default link
180 locations for duplicated commands.
181 You can use the variable to create a single default
182 location for all duplicated commands regardless of the
183 command name or package, a default for
184 specific duplicated commands regardless of the package, or
185 a default for specific commands tied to particular packages.
186 Here are the available syntax forms:
187 <literallayout class='monospaced'>
188 ALTERNATIVE_TARGET = "&lt;target&gt;"
189 ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
190 ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
191 </literallayout>
192 <note>
193 <para>
194 If <filename>ALTERNATIVE_TARGET</filename> is not
195 defined, it inherits the value from the
196 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
197 variable.
198 </para>
199
200 <para>
201 If <filename>ALTERNATIVE_LINK_NAME</filename> and
202 <filename>ALTERNATIVE_TARGET</filename> are the
203 same, the target for
204 <filename>ALTERNATIVE_TARGET</filename>
205 has "<filename>.{BPN}</filename>" appended to it.
206 </para>
207
208 <para>
209 Finally, if the file referenced has not been
210 renamed, the alternatives system will rename it to
211 avoid the need to rename alternative files in the
212 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
213 task while
214 retaining support for the command if necessary.
215 </para>
216 </note>
217 </para>
218
219 <para>
220 For more information on the alternatives system, see the
221 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
222 section.
223 </para>
224 </glossdef>
225 </glossentry>
226
227 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
228 <glossdef>
229 <para>
230 An override list of append strings for each
231 <link linkend='var-LABELS'><filename>LABEL</filename></link>.
232 </para>
233
234 <para>
235 See the
236 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
237 class for more information on how this variable is used.
238 </para>
239 </glossdef>
240 </glossentry>
241
242 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
243 <glossdef>
244 <para>The email address used to contact the original author
245 or authors in order to send patches and forward bugs.</para>
246 </glossdef>
247 </glossentry>
248
249 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
250 <glossdef>
251 <para>
252 Enables creating an automatic menu.
253 You must set this in your recipe.
254 The
255 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
256 class checks this variable.
257 </para>
258 </glossdef>
259 </glossentry>
260
261 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
262 <glossdef>
263 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
264 is set to the value of this variable, it specifies to use the latest
265 source revision in the repository.
266 Here is an example:
267 <literallayout class='monospaced'>
268 SRCREV = "${AUTOREV}"
269 </literallayout>
270 </para>
271 </glossdef>
272 </glossentry>
273
274 <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>
275 <glossdef>
276 <para>
277 The list of defined CPU and Application Binary Interface
278 (ABI) tunings (i.e. "tunes") available for use by the
279 OpenEmbedded build system.
280 </para>
281
282 <para>
283 The list simply presents the tunes that are available.
284 Not all tunes may be compatible with a particular
285 machine configuration, or with each other in a
286 <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>
287 configuration.
288 </para>
289
290 <para>
291 To add a tune to the list, be sure to append it with
292 spaces using the "+=" BitBake operator.
293 Do not simply replace the list by using the "=" operator.
294 See the
295 "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
296 section in the BitBake User Manual for more information.
297 </para>
298 </glossdef>
299 </glossentry>
300
301
302 </glossdiv>
303
304 <glossdiv id='var-glossary-b'><title>B</title>
305
306 <glossentry id='var-B'><glossterm>B</glossterm>
307 <glossdef>
308 <para>
309 The directory within the
310 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
311 in which the OpenEmbedded build system places generated
312 objects during a recipe's build process.
313 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
314 directory, which is defined as:
315 <literallayout class='monospaced'>
316 S = "${WORKDIR}/${BP}/"
317 </literallayout>
318 You can separate the (<filename>S</filename>) directory
319 and the directory pointed to by the <filename>B</filename>
320 variable.
321 Most Autotools-based recipes support separating these
322 directories.
323 The build system defaults to using separate directories for
324 <filename>gcc</filename> and some kernel recipes.
325 </para>
326 </glossdef>
327 </glossentry>
328
329 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
330 <glossdef>
331 <para>
332 Lists "recommended-only" packages to not install.
333 Recommended-only packages are packages installed only
334 through the
335 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
336 variable.
337 You can prevent any of these "recommended" packages from
338 being installed by listing them with the
339 <filename>BAD_RECOMMENDATIONS</filename> variable:
340 <literallayout class='monospaced'>
341 BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
342 </literallayout>
343 You can set this variable globally in your
344 <filename>local.conf</filename> file or you can attach it to
345 a specific image recipe by using the recipe name override:
346 <literallayout class='monospaced'>
347 BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
348 </literallayout>
349 </para>
350
351 <para>
352 It is important to realize that if you choose to not install
353 packages using this variable and some other packages are
354 dependent on them (i.e. listed in a recipe's
355 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
356 variable), the OpenEmbedded build system ignores your
357 request and will install the packages to avoid dependency
358 errors.
359 </para>
360
361 <para>
362 Support for this variable exists only when using the
363 IPK and RPM packaging backend.
364 Support does not exist for DEB.
365 </para>
366
367 <para>
368 See the
369 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
370 and the
371 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
372 variables for related information.
373 </para>
374 </glossdef>
375 </glossentry>
376
377 <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm>
378 <glossdef>
379 <para>
380 The library directory name for the CPU or Application
381 Binary Interface (ABI) tune.
382 The <filename>BASE_LIB</filename> applies only in the
383 Multilib context.
384 See the
385 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
386 section in the Yocto Project Development Manual for
387 information on Multilib.
388 </para>
389
390 <para>
391 The <filename>BASE_LIB</filename> variable is defined in
392 the machine include files in the
393 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
394 If Multilib is not being used, the value defaults to "lib".
395 </para>
396 </glossdef>
397 </glossentry>
398
399 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
400 <glossdef>
401 <para>
402 Defines how BitBake handles situations where an append
403 file (<filename>.bbappend</filename>) has no
404 corresponding recipe file (<filename>.bb</filename>).
405 This condition often occurs when layers get out of sync
406 (e.g. <filename>oe-core</filename> bumps a
407 recipe version and the old recipe no longer exists and the
408 other layer has not been updated to the new version
409 of the recipe yet).
410 </para>
411
412 <para>
413 The default fatal behavior is safest because it is
414 the sane reaction given something is out of sync.
415 It is important to realize when your changes are no longer
416 being applied.
417 </para>
418
419 <para>
420 You can change the default behavior by setting this
421 variable to "1", "yes", or "true"
422 in your <filename>local.conf</filename> file, which is
423 located in the
424 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
425 Here is an example:
426 <literallayout class='monospaced'>
427 BB_DANGLINGAPPENDS_WARNONLY = "1"
428 </literallayout>
429 </para>
430 </glossdef>
431 </glossentry>
432
433 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
434 <glossdef>
435 <para>
436 Monitors disk space and available inodes during the build
437 and allows you to control the build based on these
438 parameters.
439 </para>
440
441 <para>
442 Disk space monitoring is disabled by default.
443 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
444 variable to your <filename>conf/local.conf</filename> file found in the
445 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
446 Use the following form:
447 <literallayout class='monospaced'>
448 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
449
450 where:
451
452 &lt;action&gt; is:
453 ABORT: Immediately abort the build when
454 a threshold is broken.
455 STOPTASKS: Stop the build after the currently
456 executing tasks have finished when
457 a threshold is broken.
458 WARN: Issue a warning but continue the
459 build when a threshold is broken.
460 Subsequent warnings are issued as
461 defined by the
462 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
463 which must be defined in the
464 conf/local.conf file.
465
466 &lt;dir&gt; is:
467 Any directory you choose. You can specify one or
468 more directories to monitor by separating the
469 groupings with a space. If two directories are
470 on the same device, only the first directory
471 is monitored.
472
473 &lt;threshold&gt; is:
474 Either the minimum available disk space,
475 the minimum number of free inodes, or
476 both. You must specify at least one. To
477 omit one or the other, simply omit the value.
478 Specify the threshold using G, M, K for Gbytes,
479 Mbytes, and Kbytes, respectively. If you do
480 not specify G, M, or K, Kbytes is assumed by
481 default. Do not use GB, MB, or KB.
482 </literallayout>
483 </para>
484
485 <para>
486 Here are some examples:
487 <literallayout class='monospaced'>
488 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
489 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
490 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
491 </literallayout>
492 The first example works only if you also provide
493 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
494 in the <filename>conf/local.conf</filename>.
495 This example causes the build system to immediately
496 abort when either the disk space in <filename>${TMPDIR}</filename> drops
497 below 1 Gbyte or the available free inodes drops below
498 100 Kbytes.
499 Because two directories are provided with the variable, the
500 build system also issue a
501 warning when the disk space in the
502 <filename>${SSTATE_DIR}</filename> directory drops
503 below 1 Gbyte or the number of free inodes drops
504 below 100 Kbytes.
505 Subsequent warnings are issued during intervals as
506 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
507 variable.
508 </para>
509
510 <para>
511 The second example stops the build after all currently
512 executing tasks complete when the minimum disk space
513 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
514 directory drops below 1 Gbyte.
515 No disk monitoring occurs for the free inodes in this case.
516 </para>
517
518 <para>
519 The final example immediately aborts the build when the
520 number of free inodes in the <filename>${TMPDIR}</filename> directory
521 drops below 100 Kbytes.
522 No disk space monitoring for the directory itself occurs
523 in this case.
524 </para>
525 </glossdef>
526 </glossentry>
527
528 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
529 <glossdef>
530 <para>
531 Defines the disk space and free inode warning intervals.
532 To set these intervals, define the variable in your
533 <filename>conf/local.conf</filename> file in the
534 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
535 </para>
536
537 <para>
538 If you are going to use the
539 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
540 also use the
541 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
542 and define its action as "WARN".
543 During the build, subsequent warnings are issued each time
544 disk space or number of free inodes further reduces by
545 the respective interval.
546 </para>
547
548 <para>
549 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
550 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
551 the "WARN" action, the disk monitoring interval defaults to
552 the following:
553 <literallayout class='monospaced'>
554 BB_DISKMON_WARNINTERVAL = "50M,5K"
555 </literallayout>
556 </para>
557
558 <para>
559 When specifying the variable in your configuration file,
560 use the following form:
561 <literallayout class='monospaced'>
562 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
563
564 where:
565
566 &lt;disk_space_interval&gt; is:
567 An interval of memory expressed in either
568 G, M, or K for Gbytes, Mbytes, or Kbytes,
569 respectively. You cannot use GB, MB, or KB.
570
571 &lt;disk_inode_interval&gt; is:
572 An interval of free inodes expressed in either
573 G, M, or K for Gbytes, Mbytes, or Kbytes,
574 respectively. You cannot use GB, MB, or KB.
575 </literallayout>
576 </para>
577
578 <para>
579 Here is an example:
580 <literallayout class='monospaced'>
581 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
582 BB_DISKMON_WARNINTERVAL = "50M,5K"
583 </literallayout>
584 These variables cause the OpenEmbedded build system to
585 issue subsequent warnings each time the available
586 disk space further reduces by 50 Mbytes or the number
587 of free inodes further reduces by 5 Kbytes in the
588 <filename>${SSTATE_DIR}</filename> directory.
589 Subsequent warnings based on the interval occur each time
590 a respective interval is reached beyond the initial warning
591 (i.e. 1 Gbytes and 100 Kbytes).
592 </para>
593 </glossdef>
594 </glossentry>
595
596 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
597 <glossdef>
598 <para>
599 Causes tarballs of the Git repositories, including the
600 Git metadata, to be placed in the
601 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
602 directory.
603 </para>
604
605 <para>
606 For performance reasons, creating and placing tarballs of
607 the Git repositories is not the default action by the
608 OpenEmbedded build system.
609 <literallayout class='monospaced'>
610 BB_GENERATE_MIRROR_TARBALLS = "1"
611 </literallayout>
612 Set this variable in your <filename>local.conf</filename>
613 file in the
614 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
615 </para>
616 </glossdef>
617 </glossentry>
618
619 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
620 <glossdef>
621 <para>
622 The maximum number of tasks BitBake should run in parallel
623 at any one time.
624 If your host development system supports multiple cores,
625 a good rule of thumb is to set this variable to twice the
626 number of cores.
627 </para>
628
629 <para>
630 The default value for <filename>BB_NUMBER_THREADS</filename>
631 is equal to the number of cores your build system has.
632 </para>
633 </glossdef>
634 </glossentry>
635
636 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
637 <glossdef>
638 <para>
639 Allows you to extend a recipe so that it builds variants of the software.
640 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
641 which is a copy of Quilt built to run on the build system;
642 "crosses" such as <filename>gcc-cross</filename>,
643 which is a compiler built to run on the build machine but produces binaries
644 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
645 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
646 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
647 </para>
648
649 <para>
650 To build a different variant of the recipe with a minimal amount of code, it usually
651 is as simple as adding the following to your recipe:
652 <literallayout class='monospaced'>
653 BBCLASSEXTEND =+ "native nativesdk"
654 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
655 </literallayout>
656 </para>
657 </glossdef>
658 </glossentry>
659
660 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
661 <glossdef>
662 <para>Lists the names of configured layers.
663 These names are used to find the other <filename>BBFILE_*</filename>
664 variables.
665 Typically, each layer will append its name to this variable in its
666 <filename>conf/layer.conf</filename> file.
667 </para>
668 </glossdef>
669 </glossentry>
670
671 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
672 <glossdef>
673 <para>Variable that expands to match files from
674 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
675 in a particular layer.
676 This variable is used in the <filename>conf/layer.conf</filename> file and must
677 be suffixed with the name of the specific layer (e.g.
678 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
679 </glossdef>
680 </glossentry>
681
682 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
683 <glossdef>
684 <para>Assigns the priority for recipe files in each layer.</para>
685 <para>This variable is useful in situations where the same recipe appears in
686 more than one layer.
687 Setting this variable allows you to prioritize a
688 layer against other layers that contain the same recipe - effectively
689 letting you control the precedence for the multiple layers.
690 The precedence established through this variable stands regardless of a
691 recipe's version
692 (<link linkend='var-PV'><filename>PV</filename></link> variable).
693 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
694 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
695 lower precedence.</para>
696 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
697 precedence.
698 For example, the value 6 has a higher precedence than the value 5.
699 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
700 dependencies (see the
701 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
702 more information.
703 The default priority, if unspecified
704 for a layer with no dependencies, is the lowest defined priority + 1
705 (or 1 if no priorities are defined).</para>
706 <tip>
707 You can use the command <filename>bitbake-layers show-layers</filename> to list
708 all configured layers along with their priorities.
709 </tip>
710 </glossdef>
711 </glossentry>
712
713 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
714 <glossdef>
715 <para>List of recipe files used by BitBake to build software.</para>
716 </glossdef>
717 </glossentry>
718
719 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
720 <glossdef>
721 <para>Variable that controls how BitBake displays logs on build failure.</para>
722 </glossdef>
723 </glossentry>
724
725 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
726 <glossdef>
727 <para>Lists the layers to enable during the build.
728 This variable is defined in the <filename>bblayers.conf</filename> configuration
729 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
730 Here is an example:
731 <literallayout class='monospaced'>
732 BBLAYERS = " \
733 /home/scottrif/poky/meta \
734 /home/scottrif/poky/meta-yocto \
735 /home/scottrif/poky/meta-yocto-bsp \
736 /home/scottrif/poky/meta-mykernel \
737 "
738
739 BBLAYERS_NON_REMOVABLE ?= " \
740 /home/scottrif/poky/meta \
741 /home/scottrif/poky/meta-yocto \
742 "
743 </literallayout>
744 This example enables four layers, one of which is a custom, user-defined layer
745 named <filename>meta-mykernel</filename>.
746 </para>
747 </glossdef>
748 </glossentry>
749
750 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
751 <glossdef>
752 <para>Lists core layers that cannot be removed from the
753 <filename>bblayers.conf</filename> file during a build
754 using the
755 <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>.
756 <note>
757 When building an image outside of Hob, this variable
758 is ignored.
759 </note>
760 In order for BitBake to build your image using Hob, your
761 <filename>bblayers.conf</filename> file must include the
762 <filename>meta</filename> and <filename>meta-yocto</filename>
763 core layers.
764 Here is an example that shows these two layers listed in
765 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
766 <literallayout class='monospaced'>
767 BBLAYERS = " \
768 /home/scottrif/poky/meta \
769 /home/scottrif/poky/meta-yocto \
770 /home/scottrif/poky/meta-yocto-bsp \
771 /home/scottrif/poky/meta-mykernel \
772 "
773
774 BBLAYERS_NON_REMOVABLE ?= " \
775 /home/scottrif/poky/meta \
776 /home/scottrif/poky/meta-yocto \
777 "
778 </literallayout>
779 </para>
780 </glossdef>
781 </glossentry>
782
783 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
784 <glossdef>
785 <para>
786 Prevents BitBake from processing recipes and recipe
787 append files.
788 Use the <filename>BBMASK</filename> variable from within the
789 <filename>conf/local.conf</filename> file found
790 in the
791 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
792 </para>
793
794 <para>
795 You can use the <filename>BBMASK</filename> variable
796 to "hide" these <filename>.bb</filename> and
797 <filename>.bbappend</filename> files.
798 BitBake ignores any recipe or recipe append files that
799 match the expression.
800 It is as if BitBake does not see them at all.
801 Consequently, matching files are not parsed or otherwise
802 used by BitBake.</para>
803 <para>
804 The value you provide is passed to Python's regular
805 expression compiler.
806 The expression is compared against the full paths to
807 the files.
808 For complete syntax information, see Python's
809 documentation at
810 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
811 </para>
812
813 <para>
814 The following example uses a complete regular expression
815 to tell BitBake to ignore all recipe and recipe append
816 files in the <filename>meta-ti/recipes-misc/</filename>
817 directory:
818 <literallayout class='monospaced'>
819 BBMASK = "meta-ti/recipes-misc/"
820 </literallayout>
821 If you want to mask out multiple directories or recipes,
822 use the vertical bar to separate the regular expression
823 fragments.
824 This next example masks out multiple directories and
825 individual recipes:
826 <literallayout class='monospaced'>
827 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
828 BBMASK .= "|.*meta-oe/recipes-support/"
829 BBMASK .= "|.*openldap"
830 BBMASK .= "|.*opencv"
831 BBMASK .= "|.*lzma"
832 </literallayout>
833 Notice how the vertical bar is used to append the fragments.
834 <note>
835 When specifying a directory name, use the trailing
836 slash character to ensure you match just that directory
837 name.
838 </note>
839 </para>
840 </glossdef>
841 </glossentry>
842
843 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
844 <glossdef>
845 <para>
846 Used by BitBake to locate
847 <filename>.bbclass</filename> and configuration files.
848 This variable is analogous to the
849 <filename>PATH</filename> variable.
850 <note>
851 If you run BitBake from a directory outside of the
852 <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
853 you must be sure to set
854 <filename>BBPATH</filename> to point to the
855 Build Directory.
856 Set the variable as you would any environment variable
857 and then run BitBake:
858 <literallayout class='monospaced'>
859 $ BBPATH = "&lt;build_directory&gt;"
860 $ export BBPATH
861 $ bitbake &lt;target&gt;
862 </literallayout>
863 </note>
864 </para>
865 </glossdef>
866 </glossentry>
867
868 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
869 <glossdef>
870 <para>
871 Points to the server that runs memory-resident BitBake.
872 This variable is set by the
873 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
874 setup script and should not be hand-edited.
875 The variable is only used when you employ memory-resident
876 BitBake.
877 The setup script exports the value as follows:
878 <literallayout class='monospaced'>
879 export BBSERVER=localhost:$port
880 </literallayout>
881 For more information on how the
882 <filename>BBSERVER</filename> is used, see the
883 <filename>oe-init-build-env-memres</filename> script, which
884 is located in the
885 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
886 </para>
887 </glossdef>
888 </glossentry>
889
890 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
891 <glossdef>
892 <para>
893 When inheriting <filename>binconfig.bbclass</filename>
894 from a recipe, this variable specifies a wildcard for
895 configuration scripts that need editing.
896 The scripts are edited to correct any paths that have been
897 set up during compilation so that they are correct for
898 use when installed into the sysroot and called by the
899 build processes of other recipes.
900 </para>
901
902 <para>
903 For more information on how this variable works, see
904 <filename>meta/classes/binconfig.bbclass</filename> in the
905 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
906 You can also find general information on the class in the
907 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
908 section.
909 </para>
910 </glossdef>
911 </glossentry>
912
913 <glossentry id='var-BP'><glossterm>BP</glossterm>
914 <glossdef>
915 <para>The base recipe name and version but without any special
916 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
917 and so forth).
918 <filename>BP</filename> is comprised of the following:
919 <literallayout class="monospaced">
920 ${BPN}-${PV}
921 </literallayout></para>
922 </glossdef>
923 </glossentry>
924
925 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
926 <glossdef>
927 <para>The bare name of the recipe.
928 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
929 but removes common suffixes such as "-native" and "-cross" as well
930 as removes common prefixes such as multilib's "lib64-" and "lib32-".
931 The exact list of suffixes removed is specified by the
932 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
933 The exact list of prefixes removed is specified by the
934 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
935 Prefixes are removed for <filename>multilib</filename>
936 and <filename>nativesdk</filename> cases.</para>
937 </glossdef>
938 </glossentry>
939
940 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
941 <glossdef>
942 <para>
943 Specifies a URL for an upstream bug tracking website for
944 a recipe.
945 The OpenEmbedded build system does not use this variable.
946 Rather, the variable is a useful pointer in case a bug
947 in the software being built needs to be manually reported.
948 </para>
949 </glossdef>
950 </glossentry>
951
952 <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>
953 <glossdef>
954 <para>
955 Specifies the flags to pass to the C compiler when building
956 for the build host.
957 When building in the <filename>-native</filename> context,
958 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
959 is set to the value of this variable by default.
960 </para>
961 </glossdef>
962 </glossentry>
963
964 <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
965 <glossdef>
966 <para>
967 Specifies the flags to pass to the C pre-processor
968 (i.e. to both the C and the C++ compilers) when building
969 for the build host.
970 When building in the <filename>native</filename> context,
971 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
972 is set to the value of this variable by default.
973 </para>
974 </glossdef>
975 </glossentry>
976
977 <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>
978 <glossdef>
979 <para>
980 Specifies the flags to pass to the C++ compiler when
981 building for the build host.
982 When building in the <filename>native</filename> context,
983 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
984 is set to the value of this variable by default.
985 </para>
986 </glossdef>
987 </glossentry>
988
989 <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>
990 <glossdef>
991 <para>
992 Specifies the flags to pass to the linker when building
993 for the build host.
994 When building in the <filename>-native</filename> context,
995 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
996 is set to the value of this variable by default.
997 </para>
998 </glossdef>
999 </glossentry>
1000
1001 <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>
1002 <glossdef>
1003 <para>
1004 Specifies the optimization flags passed to the C compiler
1005 when building for the build host or the SDK.
1006 The flags are passed through the
1007 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1008 and
1009 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1010 default values.
1011 </para>
1012
1013 <para>
1014 The default value of the
1015 <filename>BUILD_OPTIMIZATION</filename> variable is
1016 "-O2 -pipe".
1017 </para>
1018 </glossdef>
1019 </glossentry>
1020
1021 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
1022 <glossdef>
1023 <para>
1024 Points to the location of the
1025 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1026 You can define this directory indirectly through the
1027 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
1028 and
1029 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
1030 scripts by passing in a Build Directory path when you run
1031 the scripts.
1032 If you run the scripts and do not provide a Build Directory
1033 path, the <filename>BUILDDIR</filename> defaults to
1034 <filename>build</filename> in the current directory.
1035 </para>
1036 </glossdef>
1037 </glossentry>
1038
1039 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
1040 <glossdef>
1041 <para>
1042 When inheriting the
1043 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1044 class, specifies whether or not to commit the build
1045 history output in a local Git repository.
1046 If set to "1", this local repository will be maintained
1047 automatically by the
1048 <filename>buildhistory</filename>
1049 class and a commit will be created on every
1050 build for changes to each top-level subdirectory of the
1051 build history output (images, packages, and sdk).
1052 If you want to track changes to build history over
1053 time, you should set this value to "1".
1054 </para>
1055
1056 <para>
1057 By default, the <filename>buildhistory</filename> class
1058 does not commit the build history output in a local
1059 Git repository:
1060 <literallayout class='monospaced'>
1061 BUILDHISTORY_COMMIT ?= "0"
1062 </literallayout>
1063 </para>
1064 </glossdef>
1065 </glossentry>
1066
1067 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
1068 <glossdef>
1069 <para>
1070 When inheriting the
1071 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1072 class, specifies the author to use for each Git commit.
1073 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
1074 variable to work, the
1075 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1076 variable must be set to "1".
1077 </para>
1078
1079 <para>
1080 Git requires that the value you provide for the
1081 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
1082 takes the form of "name &lt;email@host&gt;".
1083 Providing an email address or host that is not valid does
1084 not produce an error.
1085 </para>
1086
1087 <para>
1088 By default, the <filename>buildhistory</filename> class
1089 sets the variable as follows:
1090 <literallayout class='monospaced'>
1091 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
1092 </literallayout>
1093 </para>
1094 </glossdef>
1095 </glossentry>
1096
1097 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
1098 <glossdef>
1099 <para>
1100 When inheriting the
1101 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1102 class, specifies the directory in which build history
1103 information is kept.
1104 For more information on how the variable works, see the
1105 <filename>buildhistory.class</filename>.
1106 </para>
1107
1108 <para>
1109 By default, the <filename>buildhistory</filename> class
1110 sets the directory as follows:
1111 <literallayout class='monospaced'>
1112 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1113 </literallayout>
1114 </para>
1115 </glossdef>
1116 </glossentry>
1117
1118 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
1119 <glossdef>
1120 <para>
1121 When inheriting the
1122 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1123 class, specifies the build history features to be enabled.
1124 For more information on how build history works, see the
1125 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
1126 section.
1127 </para>
1128
1129 <para>
1130 You can specify three features in the form of a
1131 space-separated list:
1132 <itemizedlist>
1133 <listitem><para><emphasis>image:</emphasis>
1134 Analysis of the contents of images, which
1135 includes the list of installed packages among other
1136 things.
1137 </para></listitem>
1138 <listitem><para><emphasis>package:</emphasis>
1139 Analysis of the contents of individual packages.
1140 </para></listitem>
1141 <listitem><para><emphasis>sdk:</emphasis>
1142 Analysis of the contents of the software
1143 development kit (SDK).
1144 </para></listitem>
1145 </itemizedlist>
1146 </para>
1147
1148 <para>
1149 By default, the <filename>buildhistory</filename> class
1150 enables all three features:
1151 <literallayout class='monospaced'>
1152 BUILDHISTORY_FEATURES ?= "image package sdk"
1153 </literallayout>
1154 </para>
1155 </glossdef>
1156 </glossentry>
1157
1158 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
1159 <glossdef>
1160 <para>
1161 When inheriting the
1162 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1163 class, specifies a list of paths to files copied from the
1164 image contents into the build history directory under
1165 an "image-files" directory in the directory for
1166 the image, so that you can track the contents of each file.
1167 The default is to copy <filename>/etc/passwd</filename>
1168 and <filename>/etc/group</filename>, which allows you to
1169 monitor for changes in user and group entries.
1170 You can modify the list to include any file.
1171 Specifying an invalid path does not produce an error.
1172 Consequently, you can include files that might
1173 not always be present.
1174 </para>
1175
1176 <para>
1177 By default, the <filename>buildhistory</filename> class
1178 provides paths to the following files:
1179 <literallayout class='monospaced'>
1180 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1181 </literallayout>
1182 </para>
1183 </glossdef>
1184 </glossentry>
1185
1186 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
1187 <glossdef>
1188 <para>
1189 When inheriting the
1190 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1191 class, optionally specifies a remote repository
1192 to which build history pushes Git changes.
1193 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
1194 to work,
1195 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1196 must be set to "1".
1197 </para>
1198
1199 <para>
1200 The repository should correspond to a remote
1201 address that specifies a repository as understood by
1202 Git, or alternatively to a remote name that you have
1203 set up manually using <filename>git remote</filename>
1204 within the local repository.
1205 </para>
1206
1207 <para>
1208 By default, the <filename>buildhistory</filename> class
1209 sets the variable as follows:
1210 <literallayout class='monospaced'>
1211 BUILDHISTORY_PUSH_REPO ?= ""
1212 </literallayout>
1213 </para>
1214 </glossdef>
1215 </glossentry>
1216
1217 <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>
1218 <glossdef>
1219 <para>
1220 Specifies the flags to pass to the C compiler when building
1221 for the SDK.
1222 When building in the <filename>nativesdk</filename>
1223 context,
1224 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1225 is set to the value of this variable by default.
1226 </para>
1227 </glossdef>
1228 </glossentry>
1229
1230 <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>
1231 <glossdef>
1232 <para>
1233 Specifies the flags to pass to the C pre-processor
1234 (i.e. to both the C and the C++ compilers) when building
1235 for the SDK.
1236 When building in the <filename>nativesdk</filename>
1237 context,
1238 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
1239 is set to the value of this variable by default.
1240 </para>
1241 </glossdef>
1242 </glossentry>
1243
1244 <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>
1245 <glossdef>
1246 <para>
1247 Specifies the flags to pass to the C++ compiler when
1248 building for the SDK.
1249 When building in the <filename>nativesdk</filename>
1250 context,
1251 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
1252 is set to the value of this variable by default.
1253 </para>
1254 </glossdef>
1255 </glossentry>
1256
1257 <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>
1258 <glossdef>
1259 <para>
1260 Specifies the flags to pass to the linker when building
1261 for the SDK.
1262 When building in the <filename>nativesdk-</filename>
1263 context,
1264 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1265 is set to the value of this variable by default.
1266 </para>
1267 </glossdef>
1268 </glossentry>
1269
1270 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
1271 <glossdef>
1272 <para>
1273 Points to the location of the directory that holds build
1274 statistics when you use and enable the
1275 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
1276 class.
1277 The <filename>BUILDSTATS_BASE</filename> directory defaults
1278 to
1279 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
1280 </para>
1281 </glossdef>
1282 </glossentry>
1283
1284 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
1285 <glossdef>
1286 <para>
1287 For the BusyBox recipe, specifies whether to split the
1288 output executable file into two parts: one for features
1289 that require <filename>setuid root</filename>, and one for
1290 the remaining features (i.e. those that do not require
1291 <filename>setuid root</filename>).
1292 </para>
1293
1294 <para>
1295 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
1296 defaults to "1", which results in a single output
1297 executable file.
1298 Set the variable to "0" to split the output file.
1299 </para>
1300 </glossdef>
1301 </glossentry>
1302
1303 </glossdiv>
1304
1305 <glossdiv id='var-glossary-c'><title>C</title>
1306
1307 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
1308 <glossdef>
1309 <para>
1310 Specifies the flags to pass to the C compiler.
1311 This variable is exported to an environment
1312 variable and thus made visible to the software being
1313 built during the compilation step.
1314 </para>
1315
1316 <para>
1317 Default initialization for <filename>CFLAGS</filename>
1318 varies depending on what is being built:
1319 <itemizedlist>
1320 <listitem><para>
1321 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
1322 when building for the target
1323 </para></listitem>
1324 <listitem><para>
1325 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1326 when building for the build host (i.e.
1327 <filename>-native</filename>)
1328 </para></listitem>
1329 <listitem><para>
1330 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1331 when building for an SDK (i.e.
1332 <filename>nativesdk-</filename>)
1333 </para></listitem>
1334 </itemizedlist>
1335 </para>
1336 </glossdef>
1337 </glossentry>
1338
1339 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
1340 <glossdef>
1341 <para>
1342 An internal variable specifying the special class override
1343 that should currently apply (e.g. "class-target",
1344 "class-native", and so forth).
1345 The classes that use this variable set it to
1346 appropriate values.
1347 </para>
1348
1349 <para>
1350 You do not normally directly interact with this variable.
1351 The value for the <filename>CLASSOVERRIDE</filename>
1352 variable goes into
1353 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1354 and then can be used as an override.
1355 Here is an example where "python-native" is added to
1356 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1357 only when building for the native case:
1358 <literallayout class='monospaced'>
1359 DEPENDS_append_class-native = " python-native"
1360 </literallayout>
1361 </para>
1362 </glossdef>
1363 </glossentry>
1364
1365 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
1366 <glossdef>
1367 <para>
1368 Provides a list of hardware features that are enabled in
1369 both
1370 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1371 and
1372 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1373 This select list of features contains features that make
1374 sense to be controlled both at the machine and distribution
1375 configuration level.
1376 For example, the "bluetooth" feature requires hardware
1377 support but should also be optional at the distribution
1378 level, in case the hardware supports Bluetooth but you
1379 do not ever intend to use it.
1380 </para>
1381
1382 <para>
1383 For more information, see the
1384 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1385 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
1386 variables.
1387 </para>
1388 </glossdef>
1389 </glossentry>
1390
1391 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
1392 <glossdef>
1393 <para>
1394 Points to <filename>meta/files/common-licenses</filename>
1395 in the
1396 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1397 which is where generic license files reside.
1398 </para>
1399 </glossdef>
1400 </glossentry>
1401
1402 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
1403 <glossdef>
1404 <para>A regular expression that resolves to one or more hosts
1405 (when the recipe is native) or one or more targets (when
1406 the recipe is non-native) with which a recipe is compatible.
1407 The regular expression is matched against
1408 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
1409 You can use the variable to stop recipes from being built
1410 for classes of systems with which the recipes are not
1411 compatible.
1412 Stopping these builds is particularly useful with kernels.
1413 The variable also helps to increase parsing speed
1414 since the build system skips parsing recipes not
1415 compatible with the current system.</para>
1416 </glossdef>
1417 </glossentry>
1418
1419 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
1420 <glossdef>
1421 <para>A regular expression that resolves to one or more
1422 target machines with which a recipe is compatible.
1423 The regular expression is matched against
1424 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
1425 You can use the variable to stop recipes from being built
1426 for machines with which the recipes are not compatible.
1427 Stopping these builds is particularly useful with kernels.
1428 The variable also helps to increase parsing speed
1429 since the build system skips parsing recipes not
1430 compatible with the current machine.</para>
1431 </glossdef>
1432 </glossentry>
1433
1434 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
1435 <glossdef>
1436 <para>
1437 Defines wildcards to match when installing a list of
1438 complementary packages for all the packages explicitly
1439 (or implicitly) installed in an image.
1440 The resulting list of complementary packages is associated
1441 with an item that can be added to
1442 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
1443 An example usage of this is the "dev-pkgs" item that when
1444 added to <filename>IMAGE_FEATURES</filename> will
1445 install -dev packages (containing headers and other
1446 development files) for every package in the image.
1447 </para>
1448
1449 <para>
1450 To add a new feature item pointing to a wildcard, use a
1451 variable flag to specify the feature item name and
1452 use the value to specify the wildcard.
1453 Here is an example:
1454 <literallayout class='monospaced'>
1455 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1456 </literallayout>
1457 </para>
1458 </glossdef>
1459 </glossentry>
1460
1461 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
1462 <glossdef>
1463 <para>
1464 Identifies editable or configurable files that are part of a package.
1465 If the Package Management System (PMS) is being used to update
1466 packages on the target system, it is possible that
1467 configuration files you have changed after the original installation
1468 and that you now want to remain unchanged are overwritten.
1469 In other words, editable files might exist in the package that you do not
1470 want reset as part of the package update process.
1471 You can use the <filename>CONFFILES</filename> variable to list the files in the
1472 package that you wish to prevent the PMS from overwriting during this update process.
1473 </para>
1474
1475 <para>
1476 To use the <filename>CONFFILES</filename> variable, provide a package name
1477 override that identifies the resulting package.
1478 Then, provide a space-separated list of files.
1479 Here is an example:
1480 <literallayout class='monospaced'>
1481 CONFFILES_${PN} += "${sysconfdir}/file1 \
1482 ${sysconfdir}/file2 ${sysconfdir}/file3"
1483 </literallayout>
1484 </para>
1485
1486 <para>
1487 A relationship exists between the <filename>CONFFILES</filename> and
1488 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
1489 The files listed within <filename>CONFFILES</filename> must be a subset of
1490 the files listed within <filename>FILES</filename>.
1491 Because the configuration files you provide with <filename>CONFFILES</filename>
1492 are simply being identified so that the PMS will not overwrite them,
1493 it makes sense that
1494 the files must already be included as part of the package through the
1495 <filename>FILES</filename> variable.
1496 </para>
1497
1498 <note>
1499 When specifying paths as part of the <filename>CONFFILES</filename> variable,
1500 it is good practice to use appropriate path variables.
1501 For example, <filename>${sysconfdir}</filename> rather than
1502 <filename>/etc</filename> or <filename>${bindir}</filename> rather
1503 than <filename>/usr/bin</filename>.
1504 You can find a list of these variables at the top of the
1505 <filename>meta/conf/bitbake.conf</filename> file in the
1506 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1507 </note>
1508 </glossdef>
1509 </glossentry>
1510
1511 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
1512 <glossdef>
1513 <para>
1514 Identifies the initial RAM disk (initramfs) source files.
1515 The OpenEmbedded build system receives and uses
1516 this kernel Kconfig variable as an environment variable.
1517 By default, the variable is set to null ("").
1518 </para>
1519
1520 <para>
1521 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
1522 either a single cpio archive with a
1523 <filename>.cpio</filename> suffix or a
1524 space-separated list of directories and files for building
1525 the initramfs image.
1526 A cpio archive should contain a filesystem archive
1527 to be used as an initramfs image.
1528 Directories should contain a filesystem layout to be
1529 included in the initramfs image.
1530 Files should contain entries according to the format
1531 described by the
1532 <filename>usr/gen_init_cpio</filename> program in the
1533 kernel tree.
1534 </para>
1535
1536 <para>
1537 If you specify multiple directories and files, the
1538 initramfs image will be the aggregate of all of them.
1539 </para>
1540 </glossdef>
1541 </glossentry>
1542
1543 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
1544 <glossdef>
1545 <para>
1546 A list of files that contains <filename>autoconf</filename> test results relevant
1547 to the current build.
1548 This variable is used by the Autotools utilities when running
1549 <filename>configure</filename>.
1550 </para>
1551 </glossdef>
1552 </glossentry>
1553
1554 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
1555 <glossdef>
1556 <para>
1557 When a recipe inherits the
1558 <filename>distro_features_check</filename> class, this
1559 variable identifies distribution features that would
1560 be in conflict should the recipe
1561 be built.
1562 In other words, if the
1563 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
1564 lists a feature that also appears in
1565 <filename>DISTRO_FEATURES</filename> within the
1566 current configuration, an error occurs and the
1567 build stops.
1568 </para>
1569 </glossdef>
1570 </glossentry>
1571
1572 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
1573 <glossdef>
1574 <para>
1575 If set to "1" along with the
1576 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1577 variable, the OpenEmbedded build system copies
1578 into the image the license files, which are located in
1579 <filename>/usr/share/common-licenses</filename>,
1580 for each package.
1581 The license files are placed
1582 in directories within the image itself.
1583 </para>
1584 </glossdef>
1585 </glossentry>
1586
1587 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
1588 <glossdef>
1589 <para>
1590 If set to "1", the OpenEmbedded build system copies
1591 the license manifest for the image to
1592 <filename>/usr/share/common-licenses/license.manifest</filename>
1593 within the image itself.
1594 </para>
1595 </glossdef>
1596 </glossentry>
1597
1598 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
1599 <glossdef>
1600 <para>
1601 Specifies the list of packages to be added to the image.
1602 You should only set this variable in the
1603 <filename>local.conf</filename> configuration file found
1604 in the
1605 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1606 </para>
1607
1608 <para>
1609 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
1610 </para>
1611 </glossdef>
1612 </glossentry>
1613
1614 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
1615 <glossdef>
1616 <para>
1617 Specifies the parent directory of the OpenEmbedded
1618 Core Metadata layer (i.e. <filename>meta</filename>).
1619 </para>
1620
1621 <para>
1622 It is an important distinction that
1623 <filename>COREBASE</filename> points to the parent of this
1624 layer and not the layer itself.
1625 Consider an example where you have cloned the Poky Git
1626 repository and retained the <filename>poky</filename>
1627 name for your local copy of the repository.
1628 In this case, <filename>COREBASE</filename> points to
1629 the <filename>poky</filename> folder because it is the
1630 parent directory of the <filename>poky/meta</filename>
1631 layer.
1632 </para>
1633 </glossdef>
1634 </glossentry>
1635
1636 <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>
1637 <glossdef>
1638 <para>
1639 Specifies the flags to pass to the C pre-processor
1640 (i.e. to both the C and the C++ compilers).
1641 This variable is exported to an environment
1642 variable and thus made visible to the software being
1643 built during the compilation step.
1644 </para>
1645
1646 <para>
1647 Default initialization for <filename>CPPFLAGS</filename>
1648 varies depending on what is being built:
1649 <itemizedlist>
1650 <listitem><para>
1651 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>
1652 when building for the target
1653 </para></listitem>
1654 <listitem><para>
1655 <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link>
1656 when building for the build host (i.e.
1657 <filename>-native</filename>)
1658 </para></listitem>
1659 <listitem><para>
1660 <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link>
1661 when building for an SDK (i.e.
1662 <filename>nativesdk-</filename>)
1663 </para></listitem>
1664 </itemizedlist>
1665 </para>
1666 </glossdef>
1667 </glossentry>
1668
1669 <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>
1670 <glossdef>
1671 <para>
1672 Specifies the flags to pass to the C++ compiler.
1673 This variable is exported to an environment
1674 variable and thus made visible to the software being
1675 built during the compilation step.
1676 </para>
1677
1678 <para>
1679 Default initialization for <filename>CXXFLAGS</filename>
1680 varies depending on what is being built:
1681 <itemizedlist>
1682 <listitem><para>
1683 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>
1684 when building for the target
1685 </para></listitem>
1686 <listitem><para>
1687 <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link>
1688 when building for the build host (i.e.
1689 <filename>-native</filename>)
1690 </para></listitem>
1691 <listitem><para>
1692 <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
1693 when building for an SDK (i.e.
1694 <filename>nativesdk</filename>)
1695 </para></listitem>
1696 </itemizedlist>
1697 </para>
1698 </glossdef>
1699 </glossentry>
1700
1701 </glossdiv>
1702
1703 <glossdiv id='var-glossary-d'><title>D</title>
1704
1705 <glossentry id='var-D'><glossterm>D</glossterm>
1706 <glossdef>
1707 <para>
1708 The destination directory.
1709 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1710 where components are installed by the
1711 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1712 task.
1713 This location defaults to:
1714 <literallayout class='monospaced'>
1715 ${WORKDIR}/image
1716 </literallayout>
1717 </para>
1718 </glossdef>
1719 </glossentry>
1720
1721 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
1722 <glossdef>
1723 <para>
1724 The date and time on which the current build started.
1725 The format is suitable for timestamps.
1726 </para>
1727 </glossdef>
1728 </glossentry>
1729
1730 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
1731 <glossdef>
1732 <para>
1733 Specifies to build packages with debugging information.
1734 This influences the value of the
1735 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
1736 variable.
1737 </para>
1738 </glossdef>
1739 </glossentry>
1740
1741 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
1742 <glossdef>
1743 <para>
1744 The options to pass in
1745 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1746 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
1747 a system for debugging.
1748 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1749 </para>
1750 </glossdef>
1751 </glossentry>
1752
1753 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1754 <glossdef>
1755 <para>
1756 Specifies a weak bias for recipe selection priority.
1757 </para>
1758 <para>
1759 The most common usage of this is variable is to set
1760 it to "-1" within a recipe for a development version of a
1761 piece of software.
1762 Using the variable in this way causes the stable version
1763 of the recipe to build by default in the absence of
1764 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1765 being used to build the development version.
1766 </para>
1767 <note>
1768 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1769 is weak and is overridden by
1770 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1771 if that variable is different between two layers
1772 that contain different versions of the same recipe.
1773 </note>
1774 </glossdef>
1775 </glossentry>
1776
1777 <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>
1778 <glossdef>
1779 <para>
1780 The default CPU and Application Binary Interface (ABI)
1781 tunings (i.e. the "tune") used by the OpenEmbedded build
1782 system.
1783 The <filename>DEFAULTTUNE</filename> helps define
1784 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
1785 </para>
1786
1787 <para>
1788 The default tune is either implicitly or explicitly set
1789 by the machine
1790 (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).
1791 However, you can override the setting using available tunes
1792 as defined with
1793 <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>.
1794 </para>
1795 </glossdef>
1796 </glossentry>
1797
1798 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1799 <glossdef>
1800 <para>
1801 Lists a recipe's build-time dependencies
1802 (i.e. other recipe files).
1803 The system ensures that all the dependencies listed
1804 have been built and have their contents in the appropriate
1805 sysroots before the recipe's configure task is executed.
1806 </para>
1807
1808 <para>
1809 Consider this simple example for two recipes named "a" and
1810 "b" that produce similarly named packages.
1811 In this example, the <filename>DEPENDS</filename>
1812 statement appears in the "a" recipe:
1813 <literallayout class='monospaced'>
1814 DEPENDS = "b"
1815 </literallayout>
1816 Here, the dependency is such that the
1817 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
1818 task for recipe "a" depends on the
1819 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
1820 task of recipe "b".
1821 This means anything that recipe "b" puts into sysroot
1822 is available when recipe "a" is configuring itself.
1823 </para>
1824
1825 <para>
1826 For information on runtime dependencies, see the
1827 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1828 variable.
1829 </para>
1830 </glossdef>
1831 </glossentry>
1832
1833 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
1834 <glossdef>
1835 <para>
1836 Points to the general area that the OpenEmbedded build
1837 system uses to place images, packages, SDKs and other output
1838 files that are ready to be used outside of the build system.
1839 By default, this directory resides within the
1840 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1841 as <filename>${TMPDIR}/deploy</filename>.
1842 </para>
1843
1844 <para>
1845 For more information on the structure of the Build
1846 Directory, see
1847 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1848 section.
1849 For more detail on the contents of the
1850 <filename>deploy</filename> directory, see the
1851 "<link linkend='images-dev-environment'>Images</link>" and
1852 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1853 sections.
1854 </para>
1855 </glossdef>
1856 </glossentry>
1857
1858 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
1859 <glossdef>
1860 <para>
1861 Points to the area that the OpenEmbedded build system uses
1862 to place images and other associated output files that are
1863 ready to be deployed onto the target machine.
1864 The directory is machine-specific as it contains the
1865 <filename>${MACHINE}</filename> name.
1866 By default, this directory resides within the
1867 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1868 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
1869 </para>
1870
1871 <para>
1872 For more information on the structure of the Build
1873 Directory, see
1874 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1875 section.
1876 For more detail on the contents of the
1877 <filename>deploy</filename> directory, see the
1878 "<link linkend='images-dev-environment'>Images</link>" and
1879 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1880 sections.
1881 </para>
1882 </glossdef>
1883 </glossentry>
1884
1885 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
1886 <glossdef>
1887 <para>
1888 For recipes that inherit the
1889 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
1890 class, the <filename>DEPLOYDIR</filename> points to a
1891 temporary work area for deployed files that is set in the
1892 <filename>deploy</filename> class as follows:
1893 <literallayout class='monospaced'>
1894 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
1895 </literallayout>
1896 Recipes inheriting the <filename>deploy</filename> class
1897 should copy files to be deployed into
1898 <filename>DEPLOYDIR</filename>, and the class will take
1899 care of copying them into
1900 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
1901 afterwards.
1902 </para>
1903 </glossdef>
1904 </glossentry>
1905
1906 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1907 <glossdef>
1908 <para>The package description used by package managers.
1909 If not set, <filename>DESCRIPTION</filename> takes
1910 the value of the
1911 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
1912 variable.
1913 </para>
1914 </glossdef>
1915 </glossentry>
1916
1917 <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm>
1918 <glossdef>
1919 <para>
1920 A 32-bit MBR disk signature used by
1921 <filename>directdisk</filename> images.
1922 </para>
1923
1924 <para>
1925 By default, the signature is set to an automatically
1926 generated random value that allows the OpenEmbedded
1927 build system to create a boot loader.
1928 You can override the signature in the image recipe
1929 by setting <filename>DISK_SIGNATURE</filename> to an
1930 8-digit hex string.
1931 You might want to override
1932 <filename>DISK_SIGNATURE</filename> if you want the disk
1933 signature to remain constant between image builds.
1934 </para>
1935
1936 <para>
1937 When using Linux 3.8 or later, you can use
1938 <filename>DISK_SIGNATURE</filename> to specify the root
1939 by UUID to allow the kernel to locate the root device
1940 even if the device name changes due to differences in
1941 hardware configuration.
1942 By default, <filename>SYSLINUX_ROOT</filename> is set
1943 as follows:
1944 <literallayout class='monospaced'>
1945 SYSLINUX_ROOT = "root=/dev/sda2"
1946 </literallayout>
1947 However, you can change this to locate the root device
1948 using the disk signature instead:
1949 <literallayout class='monospaced'>
1950 SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02"
1951 </literallayout>
1952 </para>
1953
1954 <para>
1955 As previously mentioned, it is possible to set the
1956 <filename>DISK_SIGNATURE</filename> variable in your
1957 <filename>local.conf</filename> file to a fixed
1958 value if you do not want <filename>syslinux.cfg</filename>
1959 changing for each build.
1960 You might find this useful when you want to upgrade the
1961 root filesystem on a device without having to recreate or
1962 modify the master boot record.
1963 </para>
1964 </glossdef>
1965 </glossentry>
1966
1967 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
1968 <glossdef>
1969 <para>
1970 The short name of the distribution.
1971 This variable corresponds to a distribution
1972 configuration file whose root name is the same as the
1973 variable's argument and whose filename extension is
1974 <filename>.conf</filename>.
1975 For example, the distribution configuration file for the
1976 Poky distribution is named <filename>poky.conf</filename>
1977 and resides in the
1978 <filename>meta-yocto/conf/distro</filename> directory of
1979 the
1980 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1981 </para>
1982
1983 <para>
1984 Within that <filename>poky.conf</filename> file, the
1985 <filename>DISTRO</filename> variable is set as follows:
1986 <literallayout class='monospaced'>
1987 DISTRO = "poky"
1988 </literallayout>
1989 </para>
1990
1991 <para>
1992 Distribution configuration files are located in a
1993 <filename>conf/distro</filename> directory within the
1994 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
1995 that contains the distribution configuration.
1996 The value for <filename>DISTRO</filename> must not contain
1997 spaces, and is typically all lower-case.
1998 <note>
1999 If the <filename>DISTRO</filename> variable is blank, a set
2000 of default configurations are used, which are specified
2001 within
2002 <filename>meta/conf/distro/defaultsetup.conf</filename>
2003 also in the Source Directory.
2004 </note>
2005 </para>
2006 </glossdef>
2007 </glossentry>
2008
2009 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
2010 <glossdef>
2011 <para>
2012 Specifies a list of distro-specific packages to add to all images.
2013 This variable takes affect through
2014 <filename>packagegroup-base</filename> so the
2015 variable only really applies to the more full-featured
2016 images that include <filename>packagegroup-base</filename>.
2017 You can use this variable to keep distro policy out of
2018 generic images.
2019 As with all other distro variables, you set this variable
2020 in the distro <filename>.conf</filename> file.
2021 </para>
2022 </glossdef>
2023 </glossentry>
2024
2025 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
2026 <glossdef>
2027 <para>
2028 Specifies a list of distro-specific packages to add to all images
2029 if the packages exist.
2030 The packages might not exist or be empty (e.g. kernel modules).
2031 The list of packages are automatically installed but you can
2032 remove them.
2033 </para>
2034 </glossdef>
2035 </glossentry>
2036
2037 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
2038 <glossdef>
2039 <para>
2040 The software support you want in your distribution for
2041 various features.
2042 You define your distribution features in the distribution
2043 configuration file.
2044 </para>
2045
2046 <para>
2047 In most cases, the presence or absence of a feature in
2048 <filename>DISTRO_FEATURES</filename> is translated to the
2049 appropriate option supplied to the configure script
2050 during the
2051 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2052 task for recipes that optionally support the feature.
2053 For example, specifying "x11" in
2054 <filename>DISTRO_FEATURES</filename>, causes
2055 every piece of software built for the target that can
2056 optionally support X11 to have its X11 support enabled.
2057 </para>
2058
2059 <para>
2060 Two more examples are Bluetooth and NFS support.
2061 For a more complete list of features that ships with the
2062 Yocto Project and that you can provide with this variable,
2063 see the
2064 "<link linkend='ref-features-distro'>Distro Features</link>"
2065 section.
2066 </para>
2067 </glossdef>
2068 </glossentry>
2069
2070 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
2071 <glossdef>
2072 <para>Features to be added to
2073 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
2074 if not also present in
2075 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
2076 </para>
2077
2078 <para>
2079 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
2080 It is not intended to be user-configurable.
2081 It is best to just reference the variable to see which distro features are
2082 being backfilled for all distro configurations.
2083 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
2084 more information.
2085 </para>
2086 </glossdef>
2087 </glossentry>
2088
2089 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
2090 <glossdef>
2091 <para>Features from
2092 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
2093 that should not be backfilled (i.e. added to
2094 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
2095 during the build.
2096 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
2097 more information.
2098 </para>
2099 </glossdef>
2100 </glossentry>
2101
2102 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
2103 <glossdef>
2104 <para>The long name of the distribution.</para>
2105 </glossdef>
2106 </glossentry>
2107
2108 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
2109 <glossdef>
2110 <para>Alias names used for the recipe in various Linux distributions.</para>
2111 <para>See the
2112 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
2113 a Package Name Alias</ulink>" section in the Yocto Project Development
2114 Manual for more information.</para>
2115 </glossdef>
2116 </glossentry>
2117
2118 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
2119 <glossdef>
2120 <para>The version of the distribution.</para>
2121 </glossdef>
2122 </glossentry>
2123
2124 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
2125 <glossdef>
2126 <para>
2127 This variable lists overrides specific to the current
2128 distribution.
2129 By default, the variable list includes the value of the
2130 <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
2131 variable.
2132 You can extend the variable to apply any variable overrides
2133 you want as part of the distribution and are not
2134 already in <filename>OVERRIDES</filename> through
2135 some other means.
2136 </para>
2137 </glossdef>
2138 </glossentry>
2139
2140 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
2141 <glossdef>
2142 <para>
2143 The central download directory used by the build process to
2144 store downloads.
2145 By default, <filename>DL_DIR</filename> gets files
2146 suitable for mirroring for everything except Git
2147 repositories.
2148 If you want tarballs of Git repositories, use the
2149 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
2150 variable.
2151 </para>
2152
2153 <para>
2154 You can set this directory by defining the
2155 <filename>DL_DIR</filename> variable in the
2156 <filename>conf/local.conf</filename> file.
2157 This directory is self-maintaining and you should not have
2158 to touch it.
2159 By default, the directory is <filename>downloads</filename>
2160 in the
2161 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2162 <literallayout class='monospaced'>
2163 #DL_DIR ?= "${TOPDIR}/downloads"
2164 </literallayout>
2165 To specify a different download directory, simply remove
2166 the comment from the line and provide your directory.
2167 </para>
2168
2169 <para>
2170 During a first build, the system downloads many different
2171 source code tarballs from various upstream projects.
2172 Downloading can take a while, particularly if your network
2173 connection is slow.
2174 Tarballs are all stored in the directory defined by
2175 <filename>DL_DIR</filename> and the build system looks there
2176 first to find source tarballs.
2177 <note>
2178 When wiping and rebuilding, you can preserve this
2179 directory to speed up this part of subsequent
2180 builds.
2181 </note>
2182 </para>
2183
2184 <para>
2185 You can safely share this directory between multiple builds
2186 on the same development machine.
2187 For additional information on how the build process gets
2188 source files when working behind a firewall or proxy server,
2189 see this specific question in the
2190 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
2191 chapter.
2192 </para>
2193 </glossdef>
2194
2195 </glossentry>
2196 </glossdiv>
2197
2198 <glossdiv id='var-glossary-e'><title>E</title>
2199
2200 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
2201 <glossdef>
2202 <para></para>
2203 <para>Variable that controls which locales for
2204 <filename>eglibc</filename> are generated during the
2205 build (useful if the target device has 64Mbytes
2206 of RAM or less).</para>
2207 </glossdef>
2208 </glossentry>
2209
2210 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
2211 <glossdef>
2212 <para>
2213 Specifies the quality assurance checks whose failures are
2214 reported as errors by the OpenEmbedded build system.
2215 You set this variable in your distribution configuration
2216 file.
2217 For a list of the checks you can control with this variable,
2218 see the
2219 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
2220 section.
2221 </para>
2222 </glossdef>
2223 </glossentry>
2224
2225 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
2226 <glossdef>
2227 <para>
2228 When used with the
2229 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
2230 class, specifies the path used for storing the debug files
2231 created by the
2232 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
2233 which allows you to submit build errors you encounter to a
2234 central database.
2235 By default, the value of this variable is
2236 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
2237 </para>
2238
2239 <para>
2240 You can set <filename>ERR_REPORT_DIR</filename> to the path
2241 you want the error reporting tool to store the debug files
2242 as follows in your <filename>local.conf</filename> file:
2243 <literallayout class='monospaced'>
2244 ERR_REPORT_DIR = "path"
2245 </literallayout>
2246 </para>
2247 </glossdef>
2248 </glossentry>
2249
2250 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
2251 <glossdef>
2252 <para>
2253 Directs BitBake to exclude a recipe from world builds (i.e.
2254 <filename>bitbake world</filename>).
2255 During world builds, BitBake locates, parses and builds all
2256 recipes found in every layer exposed in the
2257 <filename>bblayers.conf</filename> configuration file.
2258 </para>
2259
2260 <para>
2261 To exclude a recipe from a world build using this variable,
2262 set the variable to "1" in the recipe.
2263 </para>
2264
2265 <note>
2266 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
2267 may still be built during a world build in order to satisfy
2268 dependencies of other recipes.
2269 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
2270 only ensures that the recipe is not explicitly added
2271 to the list of build targets in a world build.
2272 </note>
2273 </glossdef>
2274 </glossentry>
2275
2276 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
2277 <glossdef>
2278 <para>
2279 Used with file and pathnames to create a prefix for a recipe's
2280 version based on the recipe's
2281 <link linkend='var-PE'><filename>PE</filename></link> value.
2282 If <filename>PE</filename> is set and greater than zero for a recipe,
2283 <filename>EXTENDPE</filename> becomes that value (e.g if
2284 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
2285 becomes "1_").
2286 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
2287 zero, <filename>EXTENDPE</filename> becomes "".</para>
2288 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
2289 variable for an example.
2290 </para>
2291 </glossdef>
2292 </glossentry>
2293
2294 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
2295 <glossdef>
2296 <para>
2297 The full package version specification as it appears on the
2298 final packages produced by a recipe.
2299 The variable's value is normally used to fix a runtime
2300 dependency to the exact same version of another package
2301 in the same recipe:
2302 <literallayout class='monospaced'>
2303 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
2304 </literallayout>
2305 </para>
2306
2307 <para>
2308 The dependency relationships are intended to force the
2309 package manager to upgrade these types of packages in
2310 lock-step.
2311 </para>
2312 </glossdef>
2313 </glossentry>
2314
2315 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
2316 <glossdef>
2317 <para>
2318 If <filename>externalsrc.bbclass</filename> is inherited,
2319 this variable points to the source tree, which is
2320 outside of the OpenEmbedded build system.
2321 When set, this variable sets the
2322 <link linkend='var-S'><filename>S</filename></link>
2323 variable, which is what the OpenEmbedded build system uses
2324 to locate unpacked recipe source code.
2325 </para>
2326
2327 <para>
2328 For more information on
2329 <filename>externalsrc.bbclass</filename>, see the
2330 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2331 section.
2332 You can also find information on how to use this variable
2333 in the
2334 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2335 section in the Yocto Project Development Manual.
2336 </para>
2337 </glossdef>
2338 </glossentry>
2339
2340 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
2341 <glossdef>
2342 <para>
2343 If <filename>externalsrc.bbclass</filename> is inherited,
2344 this variable points to the directory in which the recipe's
2345 source code is built,
2346 which is outside of the OpenEmbedded build system.
2347 When set, this variable sets the
2348 <link linkend='var-B'><filename>B</filename></link>
2349 variable, which is what the OpenEmbedded build system uses
2350 to locate the Build Directory.
2351 </para>
2352
2353 <para>
2354 For more information on
2355 <filename>externalsrc.bbclass</filename>, see the
2356 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2357 section.
2358 You can also find information on how to use this variable
2359 in the
2360 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2361 section in the Yocto Project Development Manual.
2362 </para>
2363 </glossdef>
2364 </glossentry>
2365
2366 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
2367 <glossdef>
2368 <para>
2369 The list of additional features to include in an image.
2370 Typically, you configure this variable in your
2371 <filename>local.conf</filename> file, which is found in the
2372 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2373 Although you can use this variable from within a recipe,
2374 best practices dictate that you do not.
2375 <note>
2376 To enable primary features from within the image
2377 recipe, use the
2378 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2379 variable.
2380 </note>
2381 </para>
2382
2383 <para>
2384 Here are some examples of features you can add:
2385 <literallayout class='monospaced'>
2386"dbg-pkgs" - Adds -dbg packages for all installed packages
2387 including symbol information for debugging and
2388 profiling.
2389
2390"debug-tweaks" - Makes an image suitable for development.
2391 For example, ssh root access has a blank
2392 password. You should remove this feature
2393 before you produce a production image.
2394
2395"dev-pkgs" - Adds -dev packages for all installed packages.
2396 This is useful if you want to develop against
2397 the libraries in the image.
2398
2399"read-only-rootfs" - Creates an image whose root
2400 filesystem is read-only. See the
2401 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
2402 section in the Yocto Project
2403 Development Manual for more
2404 information
2405
2406"tools-debug" - Adds debugging tools such as gdb and
2407 strace.
2408
2409"tools-profile" - Adds profiling tools such as oprofile,
2410 exmap, lttng and valgrind (x86 only).
2411
2412"tools-sdk" - Adds development tools such as gcc, make,
2413 pkgconfig and so forth.
2414
2415"tools-testapps" - Adds useful testing tools such as
2416 ts_print, aplay, arecord and so
2417 forth.
2418
2419 </literallayout>
2420 </para>
2421
2422 <para>
2423 For a complete list of image features that ships with the
2424 Yocto Project, see the
2425 "<link linkend="ref-features-image">Image Features</link>"
2426 section.
2427 </para>
2428
2429 <para>
2430 For an example that shows how to customize your image by
2431 using this variable, see the
2432 "<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>"
2433 section in the Yocto Project Development Manual.
2434 </para>
2435 </glossdef>
2436 </glossentry>
2437
2438 <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
2439 <glossdef>
2440 <para>
2441 Specifies additional options for the image
2442 creation command that has been specified in
2443 <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
2444 When setting this variable, you should
2445 use an override for the associated type.
2446 Here is an example:
2447 <literallayout class='monospaced'>
2448 EXTRA_IMAGECMD_ext3 ?= "-i 4096"
2449 </literallayout>
2450 </para>
2451 </glossdef>
2452 </glossentry>
2453
2454 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
2455 <glossdef>
2456 <para>A list of recipes to build that do not provide packages
2457 for installing into the root filesystem.
2458 </para>
2459 <para>Sometimes a recipe is required to build the final image but is not
2460 needed in the root filesystem.
2461 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
2462 list these recipes and thus specify the dependencies.
2463 A typical example is a required bootloader in a machine configuration.
2464 </para>
2465 <note>
2466 To add packages to the root filesystem, see the various
2467 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
2468 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
2469 variables.
2470 </note>
2471 </glossdef>
2472 </glossentry>
2473
2474 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
2475 <glossdef>
2476 <para>Additional <filename>cmake</filename> options.</para>
2477 </glossdef>
2478 </glossentry>
2479
2480 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
2481 <glossdef>
2482 <para>Additional <filename>configure</filename> script options.</para>
2483 </glossdef>
2484 </glossentry>
2485
2486 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
2487 <glossdef>
2488 <para>Additional GNU <filename>make</filename> options.</para>
2489 </glossdef>
2490 </glossentry>
2491
2492 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
2493 <glossdef>
2494 <para>
2495 When a recipe inherits the
2496 <link linkend='ref-classes-scons'><filename>scons</filename></link>
2497 class, this variable specifies additional configuration
2498 options you want to pass to the
2499 <filename>scons</filename> command line.
2500 </para>
2501 </glossdef>
2502 </glossentry>
2503
2504 <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>EXTRA_QMAKEVARS_POST</glossterm>
2505 <glossdef>
2506 <para>
2507 Configuration variables or options you want to pass to
2508 <filename>qmake</filename>.
2509 Use this variable when the arguments need to be after the
2510 <filename>.pro</filename> file list on the command line.
2511 </para>
2512
2513 <para>
2514 This variable is used with recipes that inherit the
2515 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2516 class or other classes that inherit
2517 <filename>qmake_base</filename>.
2518 </para>
2519 </glossdef>
2520 </glossentry>
2521
2522 <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>EXTRA_QMAKEVARS_PRE</glossterm>
2523 <glossdef>
2524 <para>
2525 Configuration variables or options you want to pass to
2526 <filename>qmake</filename>.
2527 Use this variable when the arguments need to be before the
2528 <filename>.pro</filename> file list on the command line.
2529 </para>
2530
2531 <para>
2532 This variable is used with recipes that inherit the
2533 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2534 class or other classes that inherit
2535 <filename>qmake_base</filename>.
2536 </para>
2537 </glossdef>
2538 </glossentry>
2539
2540 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
2541 <glossdef>
2542 <para>
2543 When a recipe inherits the
2544 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
2545 class, this variable provides image level user and group
2546 operations.
2547 This is a more global method of providing user and group
2548 configuration as compared to using the
2549 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
2550 class, which ties user and group configurations to a
2551 specific recipe.
2552 </para>
2553
2554 <para>
2555 The set list of commands you can configure using the
2556 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
2557 <filename>extrausers</filename> class.
2558 These commands map to the normal Unix commands of the same
2559 names:
2560 <literallayout class='monospaced'>
2561 # EXTRA_USERS_PARAMS = "\
2562 # useradd -p '' tester; \
2563 # groupadd developers; \
2564 # userdel nobody; \
2565 # groupdel -g video; \
2566 # groupmod -g 1020 developers; \
2567 # usermod -s /bin/sh tester; \
2568 # "
2569 </literallayout>
2570 </para>
2571 </glossdef>
2572 </glossentry>
2573
2574 </glossdiv>
2575
2576 <glossdiv id='var-glossary-f'><title>F</title>
2577
2578 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
2579 <glossdef>
2580 <para>
2581 Defines one or more packages to include in an image when
2582 a specific item is included in
2583 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2584 When setting the value, <filename>FEATURE_PACKAGES</filename>
2585 should have the name of the feature item as an override.
2586 Here is an example:
2587 <literallayout class='monospaced'>
2588 FEATURE_PACKAGES_widget = "package1 package2"
2589 </literallayout>
2590 In this example, if "widget" were added to
2591 <filename>IMAGE_FEATURES</filename>, "package1" and
2592 "package2" would be included in the image.
2593 <note>
2594 Packages installed by features defined through
2595 <filename>FEATURE_PACKAGES</filename> are often package
2596 groups.
2597 While similarly named, you should not confuse the
2598 <filename>FEATURE_PACKAGES</filename> variable with
2599 package groups, which are discussed elsewhere in the
2600 documentation.
2601 </note>
2602 </para>
2603 </glossdef>
2604 </glossentry>
2605
2606 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
2607 <glossdef>
2608 <para>
2609 Points to the base URL of the server and location within
2610 the document-root that provides the metadata and
2611 packages required by OPKG to support runtime package
2612 management of IPK packages.
2613 You set this variable in your
2614 <filename>local.conf</filename> file.
2615 </para>
2616
2617 <para>
2618 Consider the following example:
2619 <literallayout class='monospaced'>
2620 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2621 </literallayout>
2622 This example assumes you are serving your packages over
2623 HTTP and your databases are located in a directory
2624 named <filename>BOARD-dir</filename>, which is underneath
2625 your HTTP server's document-root.
2626 In this case, the OpenEmbedded build system generates a set
2627 of configuration files for you in your target that work
2628 with the feed.
2629 </para>
2630 </glossdef>
2631 </glossentry>
2632
2633 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
2634 <glossdef>
2635 <para>
2636 The list of directories or files that are placed in packages.
2637 </para>
2638
2639 <para>
2640 To use the <filename>FILES</filename> variable, provide a package name
2641 override that identifies the resulting package.
2642 Then, provide a space-separated list of files or paths that identifies the
2643 files you want included as part of the resulting package.
2644 Here is an example:
2645 <literallayout class='monospaced'>
2646 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
2647 </literallayout>
2648 </para>
2649
2650 <note>
2651 When specifying paths as part of the <filename>FILES</filename> variable,
2652 it is good practice to use appropriate path variables.
2653 For example, use <filename>${sysconfdir}</filename> rather than
2654 <filename>/etc</filename>, or <filename>${bindir}</filename> rather
2655 than <filename>/usr/bin</filename>.
2656 You can find a list of these variables at the top of the
2657 <filename>meta/conf/bitbake.conf</filename> file in the
2658 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2659 </note>
2660
2661 <para>
2662 If some of the files you provide with the <filename>FILES</filename> variable
2663 are editable and you know they should not be
2664 overwritten during the package update process by the Package Management
2665 System (PMS), you can identify these files so that the PMS will not
2666 overwrite them.
2667 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
2668 variable for information on how to identify these files to the PMS.
2669 </para>
2670
2671 </glossdef>
2672 </glossentry>
2673
2674 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
2675 <glossdef>
2676 <para>
2677 Extends the search path the OpenEmbedded build system uses
2678 when looking for files and patches as it processes recipes
2679 and append files.
2680 The default directories BitBake uses when it processes
2681 recipes are initially defined by the
2682 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2683 variable.
2684 You can extend <filename>FILESPATH</filename> variable
2685 by using <filename>FILESEXTRAPATHS</filename>.
2686 </para>
2687
2688 <para>
2689 Best practices dictate that you accomplish this by using
2690 <filename>FILESEXTRAPATHS</filename> from within a
2691 <filename>.bbappend</filename> file and that you prepend
2692 paths as follows:
2693 <literallayout class='monospaced'>
2694 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2695 </literallayout>
2696 In the above example, the build system first looks for files
2697 in a directory that has the same name as the corresponding
2698 append file.
2699 <note>
2700 <para>When extending <filename>FILESEXTRAPATHS</filename>,
2701 be sure to use the immediate expansion
2702 (<filename>:=</filename>) operator.
2703 Immediate expansion makes sure that BitBake evaluates
2704 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
2705 at the time the directive is encountered rather than at
2706 some later time when expansion might result in a
2707 directory that does not contain the files you need.
2708 </para>
2709 <para>Also, include the trailing separating colon
2710 character if you are prepending.
2711 The trailing colon character is necessary because you
2712 are directing BitBake to extend the path by prepending
2713 directories to the search path.</para>
2714 </note>
2715 Here is another common use:
2716 <literallayout class='monospaced'>
2717 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
2718 </literallayout>
2719 In this example, the build system extends the
2720 <filename>FILESPATH</filename> variable to include a
2721 directory named <filename>files</filename> that is in the
2722 same directory as the corresponding append file.
2723 </para>
2724
2725 <para>
2726 Here is a final example that specifically adds three paths:
2727 <literallayout class='monospaced'>
2728 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
2729 </literallayout>
2730 </para>
2731
2732 <para>
2733 By prepending paths in <filename>.bbappend</filename>
2734 files, you allow multiple append files that reside in
2735 different layers but are used for the same recipe to
2736 correctly extend the path.
2737 </para>
2738 </glossdef>
2739 </glossentry>
2740
2741 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
2742 <glossdef>
2743 <para>
2744 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2745 used by the OpenEmbedded build system for creating
2746 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
2747 You can find more information on how overrides are handled
2748 in the BitBake Manual that is located at
2749 <filename>bitbake/doc/manual</filename> in the
2750 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2751 </para>
2752
2753 <para>
2754 By default, the <filename>FILESOVERRIDES</filename>
2755 variable is defined as:
2756 <literallayout class='monospaced'>
2757 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2758 </literallayout>
2759
2760 <note>
2761 Do not hand-edit the <filename>FILESOVERRIDES</filename>
2762 variable.
2763 The values match up with expected overrides and are
2764 used in an expected manner by the build system.
2765 </note>
2766 </para>
2767 </glossdef>
2768 </glossentry>
2769
2770 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
2771 <glossdef>
2772 <para>
2773 The default set of directories the OpenEmbedded build system
2774 uses when searching for patches and files.
2775 During the build process, BitBake searches each directory in
2776 <filename>FILESPATH</filename> in the specified order when
2777 looking for files and patches specified by each
2778 <filename>file://</filename> URI in a recipe.
2779 </para>
2780
2781 <para>
2782 The default value for the <filename>FILESPATH</filename>
2783 variable is defined in the <filename>base.bbclass</filename>
2784 class found in <filename>meta/classes</filename> in the
2785 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2786 <literallayout class='monospaced'>
2787 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2788 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2789 </literallayout>
2790 <note>
2791 Do not hand-edit the <filename>FILESPATH</filename>
2792 variable.
2793 If you want the build system to look in directories
2794 other than the defaults, extend the
2795 <filename>FILESPATH</filename> variable by using the
2796 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2797 variable.
2798 </note>
2799 Be aware that the default <filename>FILESPATH</filename>
2800 directories do not map to directories in custom layers
2801 where append files (<filename>.bbappend</filename>)
2802 are used.
2803 If you want the build system to find patches or files
2804 that reside with your append files, you need to extend
2805 the <filename>FILESPATH</filename> variable by using
2806 the
2807 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2808 variable.
2809 </para>
2810 </glossdef>
2811 </glossentry>
2812
2813 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
2814 <glossdef>
2815 <para>Allows you to define your own file permissions settings table as part of
2816 your configuration for the packaging process.
2817 For example, suppose you need a consistent set of custom permissions for
2818 a set of groups and users across an entire work project.
2819 It is best to do this in the packages themselves but this is not always
2820 possible.
2821 </para>
2822 <para>
2823 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
2824 is located in the <filename>meta/files</filename> folder in the
2825 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2826 If you create your own file permissions setting table, you should place it in your
2827 layer or the distro's layer.
2828 </para>
2829 <para>
2830 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
2831 <filename>conf/local.conf</filename> file, which is found in the
2832 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
2833 point to your custom <filename>fs-perms.txt</filename>.
2834 You can specify more than a single file permissions setting table.
2835 The paths you specify to these files must be defined within the
2836 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
2837 </para>
2838 <para>
2839 For guidance on how to create your own file permissions settings table file,
2840 examine the existing <filename>fs-perms.txt</filename>.
2841 </para>
2842 </glossdef>
2843 </glossentry>
2844
2845 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
2846 <glossdef>
2847 <para>
2848 When a recipe inherits the
2849 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
2850 class, this variable identifies packages containing font
2851 files that need to be cached by Fontconfig.
2852 By default, the <filename>fontcache</filename> class assumes
2853 that fonts are in the recipe's main package
2854 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2855 Use this variable if fonts you need are in a package
2856 other than that main package.
2857 </para>
2858 </glossdef>
2859 </glossentry>
2860
2861 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
2862 <glossdef>
2863 <para>
2864 The options to pass in
2865 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
2866 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
2867 when compiling an optimized system.
2868 This variable defaults to
2869 "-O2 -pipe ${DEBUG_FLAGS}".
2870 </para>
2871 </glossdef>
2872 </glossentry>
2873 </glossdiv>
2874
2875 <glossdiv id='var-glossary-g'><title>G</title>
2876
2877 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
2878 <glossdef>
2879 <para>
2880 When a recipe inherits the
2881 <filename>useradd</filename> class, this variable
2882 specifies for a package what parameters should be passed
2883 to the <filename>groupadd</filename> command
2884 if you wish to add a group to the system when the package
2885 is installed.
2886 </para>
2887
2888 <para>
2889 Here is an example from the <filename>dbus</filename>
2890 recipe:
2891 <literallayout class='monospaced'>
2892 GROUPADD_PARAM_${PN} = "-r netdev"
2893 </literallayout>
2894 For information on the standard Linux shell command
2895 <filename>groupadd</filename>, see
2896 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
2897 </para>
2898 </glossdef>
2899 </glossentry>
2900
2901 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
2902 <glossdef>
2903 <para>
2904 When a recipe inherits the
2905 <filename>useradd</filename> class, this variable
2906 specifies for a package what parameters should be passed
2907 to the <filename>groupmems</filename> command
2908 if you wish to modify the members of a group when the
2909 package is installed.
2910 </para>
2911
2912 <para>
2913 For information on the standard Linux shell command
2914 <filename>groupmems</filename>, see
2915 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
2916 </para>
2917 </glossdef>
2918 </glossentry>
2919
2920 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
2921 <glossdef>
2922 <para>
2923 Configures the GNU GRand Unified Bootloader (GRUB) to have
2924 graphics and serial in the boot menu.
2925 Set this variable to "1" in your
2926 <filename>local.conf</filename> or distribution
2927 configuration file to enable graphics and serial
2928 in the menu.
2929 </para>
2930
2931 <para>
2932 See the
2933 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2934 class for more information on how this variable is used.
2935 </para>
2936 </glossdef>
2937 </glossentry>
2938
2939 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
2940 <glossdef>
2941 <para>
2942 Additional options to add to the GNU GRand Unified
2943 Bootloader (GRUB) configuration.
2944 Use a semi-colon character (<filename>;</filename>) to
2945 separate multiple options.
2946 </para>
2947
2948 <para>
2949 The <filename>GRUB_OPTS</filename> variable is optional.
2950 See the
2951 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2952 class for more information on how this variable is used.
2953 </para>
2954 </glossdef>
2955 </glossentry>
2956
2957 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
2958 <glossdef>
2959 <para>
2960 Specifies the timeout before executing the default
2961 <filename>LABEL</filename> in the GNU GRand Unified
2962 Bootloader (GRUB).
2963 </para>
2964
2965 <para>
2966 The <filename>GRUB_TIMEOUT</filename> variable is optional.
2967 See the
2968 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2969 class for more information on how this variable is used.
2970 </para>
2971 </glossdef>
2972 </glossentry>
2973
2974 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
2975 <glossdef>
2976 <para>
2977 For recipes that inherit the
2978 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
2979 class, this variable specifies the packages that contain the
2980 GTK+ input method modules being installed when the modules
2981 are in packages other than the main package.
2982 </para>
2983 </glossdef>
2984 </glossentry>
2985
2986 </glossdiv>
2987
2988 <glossdiv id='var-glossary-h'><title>H</title>
2989
2990 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
2991 <glossdef>
2992 <para>Website where more information about the software the recipe is building
2993 can be found.</para>
2994 </glossdef>
2995 </glossentry>
2996
2997 <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm>
2998 <glossdef>
2999 <para>
3000 Specifies architecture-specific compiler flags that are
3001 passed to the C compiler.
3002 </para>
3003
3004 <para>
3005 Default initialization for <filename>HOST_CC_ARCH</filename>
3006 varies depending on what is being built:
3007 <itemizedlist>
3008 <listitem><para>
3009 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
3010 when building for the target
3011 </para></listitem>
3012 <listitem><para>
3013 <filename>BUILD_CC_ARCH</filename>
3014 when building for the build host (i.e.
3015 <filename>native</filename>)
3016 </para></listitem>
3017 <listitem><para>
3018 <filename>BUILDSDK_CC_ARCH</filename>
3019 when building for an SDK (i.e.
3020 <filename>nativesdk</filename>)
3021 </para></listitem>
3022 </itemizedlist>
3023 </para>
3024 </glossdef>
3025 </glossentry>
3026
3027 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
3028 <glossdef>
3029 <para>
3030 Specifies the system, including the architecture and the
3031 operating system, for with the build is occurring
3032 in the context of the current
3033 recipe.
3034 The OpenEmbedded build system automatically sets this
3035 variable.
3036 You do not need to set the variable yourself.
3037 </para>
3038
3039 <para>
3040 Here are two examples:
3041 <itemizedlist>
3042 <listitem><para>Given a native recipe on a 32-bit
3043 x86 machine running Linux, the value is
3044 "i686-linux".
3045 </para></listitem>
3046 <listitem><para>Given a recipe being built for a
3047 little-endian MIPS target running Linux,
3048 the value might be "mipsel-linux".
3049 </para></listitem>
3050 </itemizedlist>
3051 </para>
3052 </glossdef>
3053 </glossentry>
3054
3055 </glossdiv>
3056
3057 <glossdiv id='var-glossary-i'><title>I</title>
3058
3059 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
3060 <glossdef>
3061 <para>
3062 Disables or enables the <filename>icecc</filename>
3063 (Icecream) function.
3064 For more information on this function and best practices
3065 for using this variable, see the
3066 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
3067 section.
3068 </para>
3069
3070 <para>
3071 Setting this variable to "1" in your
3072 <filename>local.conf</filename> disables the function:
3073 <literallayout class='monospaced'>
3074 ICECC_DISABLED ??= "1"
3075 </literallayout>
3076 To enable the function, set the variable as follows:
3077 <literallayout class='monospaced'>
3078 ICECC_DISABLED = ""
3079 </literallayout>
3080 </para>
3081 </glossdef>
3082 </glossentry>
3083
3084 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
3085 <glossdef>
3086 <para>
3087 Points to the <filename>icecc-create-env</filename> script
3088 that you provide.
3089 This variable is used by the
3090 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3091 class.
3092 You set this variable in your
3093 <filename>local.conf</filename> file.
3094 </para>
3095
3096 <para>
3097 If you do not point to a script that you provide, the
3098 OpenEmbedded build system uses the default script provided
3099 by the <filename>icecc-create-env.bb</filename> recipe,
3100 which is a modified version and not the one that comes with
3101 <filename>icecc</filename>.
3102 </para>
3103 </glossdef>
3104 </glossentry>
3105
3106 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
3107 <glossdef>
3108 <para>
3109 Extra options passed to the <filename>make</filename>
3110 command during the
3111 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
3112 task that specify parallel compilation.
3113 This variable usually takes the form of
3114 <filename>-j 4</filename>, where the number
3115 represents the maximum number of parallel threads
3116 <filename>make</filename> can run.
3117 <note>
3118 The options passed affect builds on all enabled
3119 machines on the network, which are machines running the
3120 <filename>iceccd</filename> daemon.
3121 </note>
3122 </para>
3123
3124 <para>
3125 If your enabled machines support multiple cores,
3126 coming up with the maximum number of parallel threads
3127 that gives you the best performance could take some
3128 experimentation since machine speed, network lag,
3129 available memory, and existing machine loads can all
3130 affect build time.
3131 Consequently, unlike the
3132 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
3133 variable, there is no rule-of-thumb for setting
3134 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
3135 optimal performance.
3136 </para>
3137
3138 <para>
3139 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
3140 the build system does not use it (i.e. the system does
3141 not detect and assign the number of cores as is done with
3142 <filename>PARALLEL_MAKE</filename>).
3143 </para>
3144 </glossdef>
3145 </glossentry>
3146
3147 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
3148 <glossdef>
3149 <para>
3150 The location of the <filename>icecc</filename> binary.
3151 You can set this variable in your
3152 <filename>local.conf</filename> file.
3153 If your <filename>local.conf</filename> file does not define
3154 this variable, the
3155 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3156 class attempts to define it by locating
3157 <filename>icecc</filename> using <filename>which</filename>.
3158 </para>
3159 </glossdef>
3160 </glossentry>
3161
3162 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
3163 <glossdef>
3164 <para>
3165 Identifies user classes that you do not want the
3166 Icecream distributed compile support to consider.
3167 This variable is used by the
3168 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3169 class.
3170 You set this variable in your
3171 <filename>local.conf</filename> file.
3172 </para>
3173
3174 <para>
3175 When you list classes using this variable, you are
3176 "blacklisting" them from distributed compilation across
3177 remote hosts.
3178 Any classes you list will be distributed and compiled
3179 locally.
3180 </para>
3181 </glossdef>
3182 </glossentry>
3183
3184 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
3185 <glossdef>
3186 <para>
3187 Identifies user recipes that you do not want the
3188 Icecream distributed compile support to consider.
3189 This variable is used by the
3190 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3191 class.
3192 You set this variable in your
3193 <filename>local.conf</filename> file.
3194 </para>
3195
3196 <para>
3197 When you list packages using this variable, you are
3198 "blacklisting" them from distributed compilation across
3199 remote hosts.
3200 Any packages you list will be distributed and compiled
3201 locally.
3202 </para>
3203 </glossdef>
3204 </glossentry>
3205
3206 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
3207 <glossdef>
3208 <para>
3209 Identifies user recipes that use an empty
3210 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
3211 variable that you want to force remote distributed
3212 compilation on using the Icecream distributed compile
3213 support.
3214 This variable is used by the
3215 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3216 class.
3217 You set this variable in your
3218 <filename>local.conf</filename> file.
3219 </para>
3220 </glossdef>
3221 </glossentry>
3222
3223 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
3224 <glossdef>
3225 <para>
3226 The base name of image output files.
3227 This variable defaults to the recipe name
3228 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
3229 </para>
3230 </glossdef>
3231 </glossentry>
3232
3233 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
3234 <glossdef>
3235 <para>
3236 A list of classes that all images should inherit.
3237 You typically use this variable to specify the list of
3238 classes that register the different types of images
3239 the OpenEmbedded build system creates.
3240 </para>
3241
3242 <para>
3243 The default value for <filename>IMAGE_CLASSES</filename> is
3244 <filename>image_types</filename>.
3245 You can set this variable in your
3246 <filename>local.conf</filename> or in a distribution
3247 configuration file.
3248 </para>
3249
3250 <para>
3251 For more information, see
3252 <filename>meta/classes/image_types.bbclass</filename> in the
3253 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3254 </para>
3255 </glossdef>
3256 </glossentry>
3257
3258 <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>
3259 <glossdef>
3260 <para>
3261 Specifies the command to create the image file for a
3262 specific image type, which corresponds to the value set
3263 set in
3264 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
3265 (e.g. <filename>ext3</filename>,
3266 <filename>btrfs</filename>, and so forth).
3267 When setting this variable, you should use
3268 an override for the associated type.
3269 Here is an example:
3270 <literallayout class='monospaced'>
3271 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
3272 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
3273 ${EXTRA_IMAGECMD}"
3274 </literallayout>
3275 You typically do not need to set this variable unless
3276 you are adding support for a new image type.
3277 For more examples on how to set this variable, see the
3278 <link linkend='ref-classes-image_types'><filename>image_types</filename></link>
3279 class file, which is
3280 <filename>meta/classes/image_types.bbclass</filename>.
3281 </para>
3282 </glossdef>
3283 </glossentry>
3284
3285 <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>
3286 <glossdef>
3287 <para>
3288 Specifies one or more files that contain custom device
3289 tables that are passed to the
3290 <filename>makedevs</filename> command as part of creating
3291 an image.
3292 These files list basic device nodes that should be
3293 created under <filename>/dev</filename> within the image.
3294 If <filename>IMAGE_DEVICE_TABLES</filename> is not set,
3295 <filename>files/device_table-minimal.txt</filename> is
3296 used, which is located by
3297 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
3298 For details on how you should write device table files,
3299 see <filename>meta/files/device_table-minimal.txt</filename>
3300 as an example.
3301 </para>
3302 </glossdef>
3303 </glossentry>
3304
3305 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
3306 <glossdef>
3307 <para>
3308 The primary list of features to include in an image.
3309 Typically, you configure this variable in an image recipe.
3310 Although you can use this variable from your
3311 <filename>local.conf</filename> file, which is found in the
3312 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
3313 best practices dictate that you do not.
3314 <note>
3315 To enable extra features from outside the image recipe,
3316 use the
3317 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
3318 </note>
3319 For a list of image features that ships with the Yocto
3320 Project, see the
3321 "<link linkend="ref-features-image">Image Features</link>"
3322 section.
3323 </para>
3324
3325 <para>
3326 For an example that shows how to customize your image by
3327 using this variable, see the
3328 "<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>"
3329 section in the Yocto Project Development Manual.
3330 </para>
3331 </glossdef>
3332 </glossentry>
3333
3334 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
3335 <glossdef>
3336 <para>
3337 Specifies the formats the OpenEmbedded build system uses
3338 during the build when creating the root filesystem.
3339 For example, setting <filename>IMAGE_FSTYPES</filename>
3340 as follows causes the build system to create root
3341 filesystems using two formats: <filename>.ext3</filename>
3342 and <filename>.tar.bz2</filename>:
3343 <literallayout class='monospaced'>
3344 IMAGE_FSTYPES = "ext3 tar.bz2"
3345 </literallayout>
3346 For the complete list of supported image formats from which
3347 you can choose, see
3348 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
3349 </para>
3350
3351 <note>
3352 If you add "live" to <filename>IMAGE_FSTYPES</filename>
3353 inside an image recipe, be sure that you do so prior to the
3354 "inherit image" line of the recipe or the live image will
3355 not build.
3356 </note>
3357
3358 <note>
3359 Due to the way this variable is processed, it is not
3360 possible to update its contents using
3361 <filename>_append</filename> or
3362 <filename>_prepend</filename>. To add one or more
3363 additional options to this variable the
3364 <filename>+=</filename> operator must be used.
3365 </note>
3366 </glossdef>
3367 </glossentry>
3368
3369 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
3370 <glossdef>
3371 <para>
3372 Specifies the packages to install into an image.
3373 The <filename>IMAGE_INSTALL</filename> variable is a
3374 mechanism for an image recipe and you should use it
3375 with care to avoid ordering issues.
3376 <note>
3377 When working with an
3378 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
3379 image, do not use the <filename>IMAGE_INSTALL</filename>
3380 variable to specify packages for installation.
3381 Instead, use the
3382 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
3383 variable, which allows the initial RAM disk (initramfs)
3384 recipe to use a fixed set of packages and not be
3385 affected by <filename>IMAGE_INSTALL</filename>.
3386 </note>
3387 </para>
3388
3389 <para>
3390 Image recipes set <filename>IMAGE_INSTALL</filename>
3391 to specify the packages to install into an image through
3392 <filename>image.bbclass</filename>.
3393 Additionally, "helper" classes exist, such as
3394 <filename>core-image.bbclass</filename>, that can take
3395 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
3396 lists and turn these into auto-generated entries in
3397 <filename>IMAGE_INSTALL</filename> in addition to its
3398 default contents.
3399 </para>
3400
3401 <para>
3402 Using <filename>IMAGE_INSTALL</filename> with the
3403 <filename>+=</filename> operator from the
3404 <filename>/conf/local.conf</filename> file or from within
3405 an image recipe is not recommended as it can cause ordering
3406 issues.
3407 Since <filename>core-image.bbclass</filename> sets
3408 <filename>IMAGE_INSTALL</filename> to a default value using
3409 the <filename>?=</filename> operator, using a
3410 <filename>+=</filename> operation against
3411 <filename>IMAGE_INSTALL</filename> will result in
3412 unexpected behavior when used in
3413 <filename>conf/local.conf</filename>.
3414 Furthermore, the same operation from within an image
3415 recipe may or may not succeed depending on the specific
3416 situation.
3417 In both these cases, the behavior is contrary to how most
3418 users expect the <filename>+=</filename> operator to work.
3419 </para>
3420
3421 <para>
3422 When you use this variable, it is best to use it as follows:
3423 <literallayout class='monospaced'>
3424 IMAGE_INSTALL_append = " package-name"
3425 </literallayout>
3426 Be sure to include the space between the quotation character
3427 and the start of the package name or names.
3428 </para>
3429 </glossdef>
3430 </glossentry>
3431
3432 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
3433 <glossdef>
3434 <para>
3435 Specifies the list of locales to install into the image
3436 during the root filesystem construction process.
3437 The OpenEmbedded build system automatically splits locale
3438 files, which are used for localization, into separate
3439 packages.
3440 Setting the <filename>IMAGE_LINGUAS</filename> variable
3441 ensures that any locale packages that correspond to packages
3442 already selected for installation into the image are also
3443 installed.
3444 Here is an example:
3445 <literallayout class='monospaced'>
3446 IMAGE_LINGUAS = "pt-br de-de"
3447 </literallayout>
3448 In this example, the build system ensures any Brazilian
3449 Portuguese and German locale files that correspond to
3450 packages in the image are installed (i.e.
3451 <filename>*-locale-pt-br</filename>
3452 and <filename>*-locale-de-de</filename> as well as
3453 <filename>*-locale-pt</filename>
3454 and <filename>*-locale-de</filename>, since some software
3455 packages only provide locale files by language and not by
3456 country-specific language).
3457 </para>
3458 </glossdef>
3459 </glossentry>
3460
3461 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
3462 <glossdef>
3463 <para>
3464 The manifest file for the image.
3465 This file lists all the installed packages that make up
3466 the image.
3467 The file contains package information on a line-per-package
3468 basis as follows:
3469 <literallayout class='monospaced'>
3470 &lt;packagename&gt; &lt;packagearch&gt; &lt;version&gt;
3471 </literallayout>
3472 </para>
3473
3474 <para>
3475 The
3476 <link linkend='ref-classes-image'><filename>image</filename></link>
3477 class defines the manifest file as follows:
3478 <literallayout class='monospaced'>
3479 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
3480 </literallayout>
3481 The location is derived using the
3482 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3483 and
3484 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
3485 variables.
3486 You can find information on how the image
3487 is created in the
3488 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
3489 section.
3490 </para>
3491 </glossdef>
3492 </glossentry>
3493
3494 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
3495 <glossdef>
3496 <para>
3497 The name of the output image files minus the extension.
3498 This variable is derived using the
3499 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
3500 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3501 and
3502 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3503 variables:
3504 <literallayout class='monospaced'>
3505 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
3506 </literallayout>
3507 </para>
3508 </glossdef>
3509 </glossentry>
3510
3511 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
3512 <glossdef>
3513 <para>
3514 Defines a multiplier that the build system applies to the initial image
3515 size for cases when the multiplier times the returned disk usage value
3516 for the image is greater than the sum of
3517 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3518 and
3519 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
3520 The result of the multiplier applied to the initial image size creates
3521 free disk space in the image as overhead.
3522 By default, the build process uses a multiplier of 1.3 for this variable.
3523 This default value results in 30% free disk space added to the image when this
3524 method is used to determine the final generated image size.
3525 You should be aware that post install scripts and the package management
3526 system uses disk space inside this overhead area.
3527 Consequently, the multiplier does not produce an image with
3528 all the theoretical free disk space.
3529 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3530 for information on how the build system determines the overall image size.
3531 </para>
3532
3533 <para>
3534 The default 30% free disk space typically gives the image enough room to boot
3535 and allows for basic post installs while still leaving a small amount of
3536 free disk space.
3537 If 30% free space is inadequate, you can increase the default value.
3538 For example, the following setting gives you 50% free space added to the image:
3539 <literallayout class='monospaced'>
3540 IMAGE_OVERHEAD_FACTOR = "1.5"
3541 </literallayout>
3542 </para>
3543
3544 <para>
3545 Alternatively, you can ensure a specific amount of free disk space is added
3546 to the image by using the
3547 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3548 variable.
3549 </para>
3550 </glossdef>
3551 </glossentry>
3552
3553 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
3554 <glossdef>
3555 <para>
3556 Defines the package type (DEB, RPM, IPK, or TAR) used
3557 by the OpenEmbedded build system.
3558 The variable is defined appropriately by the
3559 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
3560 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
3561 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
3562 or
3563 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3564 class.
3565 </para>
3566
3567 <para>
3568 The
3569 <link linkend='ref-classes-populate-sdk-*'><filename>package_sdk_base</filename></link>
3570 and
3571 <link linkend='ref-classes-image'><filename>image</filename></link>
3572 classes use the <filename>IMAGE_PKGTYPE</filename> for
3573 packaging up images and SDKs.
3574 </para>
3575
3576 <para>
3577 You should not set the <filename>IMAGE_PKGTYPE</filename>
3578 manually.
3579 Rather, the variable is set indirectly through the
3580 appropriate
3581 <link linkend='ref-classes-package'><filename>package_*</filename></link>
3582 class using the
3583 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3584 variable.
3585 The OpenEmbedded build system uses the first package type
3586 (e.g. DEB, RPM, or IPK) that appears with the variable
3587 <note>
3588 Files using the <filename>.tar</filename> format are
3589 never used as a substitute packaging format for DEB,
3590 RPM, and IPK formatted files for your image or SDK.
3591 </note>
3592 </para>
3593 </glossdef>
3594 </glossentry>
3595
3596 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
3597 <glossdef>
3598 <para>
3599 Added by classes to run post processing commands once the
3600 OpenEmbedded build system has created the image.
3601 You can specify shell commands separated by semicolons:
3602 <literallayout class='monospaced'>
3603 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
3604 </literallayout>
3605 If you need to pass the path to the root filesystem within
3606 the command, you can use
3607 <filename>${IMAGE_ROOTFS}</filename>, which points to
3608 the root filesystem image.
3609 </para>
3610 </glossdef>
3611 </glossentry>
3612
3613 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
3614 <glossdef>
3615 <para>
3616 The location of the root filesystem while it is under
3617 construction (i.e. during the
3618 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
3619 task).
3620 This variable is not configurable.
3621 Do not change it.
3622 </para>
3623 </glossdef>
3624 </glossentry>
3625
3626 <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>
3627 <glossdef>
3628 <para>
3629 Specifies the alignment for the output image file in
3630 Kbytes.
3631 If the size of the image is not a multiple of
3632 this value, then the size is rounded up to the nearest
3633 multiple of the value.
3634 The default value is "1".
3635 See
3636 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
3637 for additional information.
3638 </para>
3639 </glossdef>
3640 </glossentry>
3641
3642 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
3643 <glossdef>
3644 <para>
3645 Defines additional free disk space created in the image in Kbytes.
3646 By default, this variable is set to "0".
3647 This free disk space is added to the image after the build system determines
3648 the image size as described in
3649 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
3650 </para>
3651
3652 <para>
3653 This variable is particularly useful when you want to ensure that a
3654 specific amount of free disk space is available on a device after an image
3655 is installed and running.
3656 For example, to be sure 5 Gbytes of free disk space is available, set the
3657 variable as follows:
3658 <literallayout class='monospaced'>
3659 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3660 </literallayout>
3661 </para>
3662
3663 <para>
3664 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
3665 of extra space with the line:
3666 <literallayout class='monospaced'>
3667 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3668 </literallayout>
3669 </para>
3670 </glossdef>
3671 </glossentry>
3672
3673 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
3674 <glossdef>
3675 <para>
3676 Defines the size in Kbytes for the generated image.
3677 The OpenEmbedded build system determines the final size for the generated
3678 image using an algorithm that takes into account the initial disk space used
3679 for the generated image, a requested size for the image, and requested
3680 additional free disk space to be added to the image.
3681 Programatically, the build system determines the final size of the
3682 generated image as follows:
3683 <literallayout class='monospaced'>
3684 if (image-du * overhead) &lt; rootfs-size:
3685 internal-rootfs-size = rootfs-size + xspace
3686 else:
3687 internal-rootfs-size = (image-du * overhead) + xspace
3688
3689 where:
3690
3691 image-du = Returned value of the du command on
3692 the image.
3693
3694 overhead = IMAGE_OVERHEAD_FACTOR
3695
3696 rootfs-size = IMAGE_ROOTFS_SIZE
3697
3698 internal-rootfs-size = Initial root filesystem
3699 size before any modifications.
3700
3701 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3702 </literallayout>
3703 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
3704 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
3705 variables for related information.
3706<!-- In the above example, <filename>overhead</filename> is defined by the
3707 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
3708 variable, <filename>xspace</filename> is defined by the
3709 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3710 variable, and <filename>du</filename> is the results of the disk usage command
3711 on the initially generated image. -->
3712 </para>
3713 </glossdef>
3714 </glossentry>
3715
3716 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
3717 <glossdef>
3718 <para>
3719 Specifies a dependency from one image type on another.
3720 Here is an example from the
3721 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
3722 class:
3723 <literallayout class='monospaced'>
3724 IMAGE_TYPEDEP_live = "ext3"
3725 </literallayout>
3726 In the previous example, the variable ensures that when
3727 "live" is listed with the
3728 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3729 variable, the OpenEmbedded build system produces an
3730 <filename>ext3</filename> image first since one of the
3731 components of the live
3732 image is an <filename>ext3</filename>
3733 formatted partition containing the root
3734 filesystem.
3735 </para>
3736 </glossdef>
3737 </glossentry>
3738
3739 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
3740 <glossdef>
3741 <para>
3742 Specifies the complete list of supported image types
3743 by default:
3744 <literallayout class='monospaced'>
3745 jffs2
3746 jffs2.sum
3747 cramfs
3748 ext2
3749 ext2.gz
3750 ext2.bz2
3751 ext3
3752 ext3.gz
3753 ext2.lzma
3754 btrfs
3755 live
3756 squashfs
3757 squashfs-xz
3758 ubi
3759 ubifs
3760 tar
3761 tar.gz
3762 tar.bz2
3763 tar.xz
3764 cpio
3765 cpio.gz
3766 cpio.xz
3767 cpio.lzma
3768 vmdk
3769 elf
3770 </literallayout>
3771 For more information about these types of images, see
3772 <filename>meta/classes/image_types*.bbclass</filename>
3773 in the
3774 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3775 </para>
3776 </glossdef>
3777 </glossentry>
3778
3779 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
3780 <glossdef>
3781 <para>Helps define the recipe revision for recipes that share
3782 a common <filename>include</filename> file.
3783 You can think of this variable as part of the recipe revision
3784 as set from within an include file.</para>
3785 <para>Suppose, for example, you have a set of recipes that
3786 are used across several projects.
3787 And, within each of those recipes the revision
3788 (its <link linkend='var-PR'><filename>PR</filename></link>
3789 value) is set accordingly.
3790 In this case, when the revision of those recipes changes,
3791 the burden is on you to find all those recipes and
3792 be sure that they get changed to reflect the updated
3793 version of the recipe.
3794 In this scenario, it can get complicated when recipes
3795 that are used in many places and provide common functionality
3796 are upgraded to a new revision.</para>
3797 <para>A more efficient way of dealing with this situation is
3798 to set the <filename>INC_PR</filename> variable inside
3799 the <filename>include</filename> files that the recipes
3800 share and then expand the <filename>INC_PR</filename>
3801 variable within the recipes to help
3802 define the recipe revision.
3803 </para>
3804 <para>
3805 The following provides an example that shows how to use
3806 the <filename>INC_PR</filename> variable
3807 given a common <filename>include</filename> file that
3808 defines the variable.
3809 Once the variable is defined in the
3810 <filename>include</filename> file, you can use the
3811 variable to set the <filename>PR</filename> values in
3812 each recipe.
3813 You will notice that when you set a recipe's
3814 <filename>PR</filename> you can provide more granular
3815 revisioning by appending values to the
3816 <filename>INC_PR</filename> variable:
3817 <literallayout class='monospaced'>
3818recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3819recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3820recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3821recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3822 </literallayout>
3823 The first line of the example establishes the baseline
3824 revision to be used for all recipes that use the
3825 <filename>include</filename> file.
3826 The remaining lines in the example are from individual
3827 recipes and show how the <filename>PR</filename> value
3828 is set.</para>
3829 </glossdef>
3830 </glossentry>
3831
3832 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
3833 <glossdef>
3834 <para>
3835 Specifies a space-separated list of license names
3836 (as they would appear in
3837 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
3838 that should be excluded from the build.
3839 Recipes that provide no alternatives to listed incompatible
3840 licenses are not built.
3841 Packages that are individually licensed with the specified
3842 incompatible licenses will be deleted.
3843 </para>
3844
3845 <note>
3846 This functionality is only regularly tested using
3847 the following setting:
3848 <literallayout class='monospaced'>
3849 INCOMPATIBLE_LICENSE = "GPLv3"
3850 </literallayout>
3851 Although you can use other settings, you might be required
3852 to remove dependencies on or provide alternatives to
3853 components that are required to produce a functional system
3854 image.
3855 </note>
3856 </glossdef>
3857 </glossentry>
3858
3859 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
3860 <glossdef>
3861 <para>
3862 Prevents the default dependencies, namely the C compiler
3863 and standard C library (libc), from being added to
3864 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
3865 This variable is usually used within recipes that do not
3866 require any compilation using the C compiler.
3867 </para>
3868
3869 <para>
3870 Set the variable to "1" to prevent the default dependencies
3871 from being added.
3872 </para>
3873 </glossdef>
3874 </glossentry>
3875
3876 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
3877 <glossdef>
3878 <para>
3879 If set to "1", causes the build to not strip binaries in resulting packages.
3880 </para>
3881 </glossdef>
3882 </glossentry>
3883
3884 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
3885 <glossdef>
3886 <para>
3887 Causes the named class to be inherited at
3888 this point during parsing.
3889 The variable is only valid in configuration files.
3890 </para>
3891 </glossdef>
3892 </glossentry>
3893
3894 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
3895 <glossdef>
3896 <para>
3897 Lists classes that will be inherited at the
3898 distribution level.
3899 It is unlikely that you want to edit this variable.
3900 </para>
3901
3902 <para>
3903 The default value of the variable is set as follows in the
3904 <filename>meta/conf/distro/defaultsetup.conf</filename>
3905 file:
3906 <literallayout class='monospaced'>
3907 INHERIT_DISTRO ?= "debian devshell sstate license"
3908 </literallayout>
3909 </para>
3910 </glossdef>
3911 </glossentry>
3912
3913 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
3914 <glossdef>
3915 <para>
3916 Defines the format for the output image of an initial
3917 RAM disk (initramfs), which is used during boot.
3918 Supported formats are the same as those supported by the
3919 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3920 variable.
3921 </para>
3922 </glossdef>
3923 </glossentry>
3924
3925 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
3926 <glossdef>
3927 <para>
3928 Causes the OpenEmbedded build system to build an additional
3929 recipe as a dependency to your root filesystem recipe
3930 (e.g. <filename>core-image-sato</filename>).
3931 The additional recipe is used to create an initial RAM disk
3932 (initramfs) that might be needed during the initial boot of
3933 the target system to accomplish such things as loading
3934 kernel modules prior to mounting the root file system.
3935 </para>
3936
3937 <para>
3938 When you set the variable, specify the name of the
3939 initramfs you want created.
3940 The following example, which is set in the
3941 <filename>local.conf</filename> configuration file, causes
3942 a separate recipe to be created that results in an
3943 initramfs image named
3944 <filename>core-image-sato-initramfs.bb</filename> to be
3945 created:
3946 <literallayout class='monospaced'>
3947 INITRAMFS_IMAGE = "core-image-minimal-initramfs"
3948 </literallayout>
3949 By default, the
3950 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3951 class sets this variable to a null string as follows:
3952 <literallayout class='monospaced'>
3953 INITRAMFS_IMAGE = ""
3954 </literallayout>
3955 </para>
3956
3957 <para>
3958 See the
3959 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
3960 file for additional information.
3961 You can also reference the
3962 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/kernel.bbclass'><filename>kernel.bbclass</filename></ulink>
3963 file to see how the variable is used.
3964 </para>
3965 </glossdef>
3966 </glossentry>
3967
3968 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
3969 <glossdef>
3970 <para>
3971 Controls whether or not the image recipe specified by
3972 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
3973 is run through an extra pass during kernel compilation
3974 in order to build a single binary that contains both the
3975 kernel image and the initial RAM disk (initramfs).
3976 Using an extra compilation pass ensures that when a kernel
3977 attempts to use an initramfs, it does not encounter
3978 circular dependencies should the initramfs include kernel
3979 modules.
3980 </para>
3981
3982 <para>
3983 The combined binary is deposited into the
3984 <filename>tmp/deploy</filename> directory, which is part
3985 of the
3986 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
3987 </para>
3988
3989 <para>
3990 Setting the variable to "1" in a configuration file causes
3991 the OpenEmbedded build system to make the extra pass during
3992 kernel compilation:
3993 <literallayout class='monospaced'>
3994 INITRAMFS_IMAGE_BUNDLE = "1"
3995 </literallayout>
3996 By default, the
3997 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3998 class sets this variable to a null string as follows:
3999 <literallayout class='monospaced'>
4000 INITRAMFS_IMAGE_BUNDLE = ""
4001 </literallayout>
4002 <note>
4003 You must set the
4004 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
4005 a configuration file.
4006 You cannot set the variable in a recipe file.
4007 </note>
4008 See the
4009 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
4010 file for additional information.
4011 </para>
4012 </glossdef>
4013 </glossentry>
4014
4015 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
4016 <glossdef>
4017 <para>
4018 Indicates a filesystem image to use as an initial RAM
4019 disk (<filename>initrd</filename>).
4020 </para>
4021
4022 <para>
4023 The <filename>INITRD</filename> variable is an optional
4024 variable used with the
4025 <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link>
4026 class.
4027 </para>
4028 </glossdef>
4029 </glossentry>
4030
4031 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
4032 <glossdef>
4033 <para>
4034 The filename of the initialization script as installed to
4035 <filename>${sysconfdir}/init.d</filename>.
4036 </para>
4037 <para>
4038 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
4039 The variable is mandatory.
4040 </para>
4041 </glossdef>
4042 </glossentry>
4043
4044 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
4045 <glossdef>
4046 <para>
4047 A list of the packages that contain initscripts.
4048 If multiple packages are specified, you need to append the package name
4049 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
4050 <para>
4051 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
4052 The variable is optional and defaults to the
4053 <link linkend='var-PN'><filename>PN</filename></link> variable.
4054 </para>
4055 </glossdef>
4056 </glossentry>
4057
4058 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
4059 <glossdef>
4060 <para>
4061 Specifies the options to pass to <filename>update-rc.d</filename>.
4062 Here is an example:
4063 <literallayout class='monospaced'>
4064 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
4065 </literallayout>
4066 In this example, the script has a runlevel of 99,
4067 starts the script in initlevels 2 and 5, and
4068 stops the script in levels 0, 1 and 6.
4069 </para>
4070 <para>
4071 The variable is mandatory and is used in recipes when using
4072 <filename>update-rc.d.bbclass</filename>.
4073 </para>
4074 </glossdef>
4075 </glossentry>
4076
4077 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
4078 <glossdef>
4079 <para>
4080 Specifies the QA checks to skip for a specific package
4081 within a recipe.
4082 For example, to skip the check for symbolic link
4083 <filename>.so</filename> files in the main package of a
4084 recipe, add the following to the recipe.
4085 The package name override must be used, which in this
4086 example is <filename>${PN}</filename>:
4087 <literallayout class='monospaced'>
4088 INSANE_SKIP_${PN} += "dev-so"
4089 </literallayout>
4090 </para>
4091 <para>
4092 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
4093 section for a list of the valid QA checks you can
4094 specify using this variable.
4095 </para>
4096 </glossdef>
4097 </glossentry>
4098
4099 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
4100 <glossdef>
4101 <para>
4102 When the IPK backend is in use and package management
4103 is enabled on the target, you can use this variable to
4104 set up <filename>opkg</filename> in the target image
4105 to point to package feeds on a nominated server.
4106 Once the feed is established, you can perform
4107 installations or upgrades using the package manager
4108 at runtime.
4109 </para>
4110 </glossdef>
4111 </glossentry>
4112
4113<!--
4114 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
4115 <glossdef>
4116 <para>
4117 An environment variable that defines the directory where
4118 post installation hooks are installed for the
4119 post install environment.
4120 This variable is fixed as follows:
4121 <literallayout class='monospaced'>
4122 ${WORKDIR}/intercept_scripts
4123 </literallayout>
4124 </para>
4125
4126 <para>
4127 After installation of a target's root filesystem,
4128 post installation scripts, which are essentially bash scripts,
4129 are all executed just a single time.
4130 Limiting execution of these scripts minimizes installation
4131 time that would be lengthened due to certain packages
4132 triggering redundant operations.
4133 For example, consider the installation of font packages
4134 as a common example.
4135 Without limiting the execution of post installation scripts,
4136 all font directories would be rescanned to create the
4137 cache after each individual font package was installed.
4138 </para>
4139
4140 <para>
4141 Do not edit the <filename>INTERCEPT_DIR</filename>
4142 variable.
4143 </para>
4144 </glossdef>
4145 </glossentry>
4146-->
4147
4148 </glossdiv>
4149
4150<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
4151<!-- </glossdiv>-->
4152
4153 <glossdiv id='var-glossary-k'><title>K</title>
4154
4155 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
4156 <glossdef>
4157 <para>
4158 Defines the kernel architecture used when assembling
4159 the configuration.
4160 Architectures supported for this release are:
4161 <literallayout class='monospaced'>
4162 powerpc
4163 i386
4164 x86_64
4165 arm
4166 qemu
4167 mips
4168 </literallayout>
4169 </para>
4170
4171 <para>
4172 You define the <filename>KARCH</filename> variable in the
4173 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
4174 </para>
4175 </glossdef>
4176 </glossentry>
4177
4178 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
4179 <glossdef>
4180 <para>
4181 A regular expression used by the build process to explicitly
4182 identify the kernel branch that is validated, patched
4183 and configured during a build.
4184 The <filename>KBRANCH</filename> variable is optional.
4185 You can use it to trigger checks to ensure the exact kernel
4186 branch you want is being used by the build process.
4187 </para>
4188
4189 <para>
4190 Values for this variable are set in the kernel's recipe
4191 file and the kernel's append file.
4192 For example, if you are using the Yocto Project kernel that
4193 is based on the Linux 3.10 kernel, the kernel recipe file
4194 is the
4195 <filename>meta/recipes-kernel/linux/linux-yocto_3.10.bb</filename>
4196 file.
4197 Following is the default value for <filename>KBRANCH</filename>
4198 and the default override for the architectures the Yocto
4199 Project supports:
4200 <literallayout class='monospaced'>
4201 KBRANCH_DEFAULT = "standard/base"
4202 KBRANCH = "${KBRANCH_DEFAULT}"
4203 </literallayout>
4204 This branch exists in the <filename>linux-yocto-3.10</filename>
4205 kernel Git repository
4206 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.10/refs/heads'></ulink>.
4207 </para>
4208
4209 <para>
4210 This variable is also used from the kernel's append file
4211 to identify the kernel branch specific to a particular
4212 machine or target hardware.
4213 The kernel's append file is located in the BSP layer for
4214 a given machine.
4215 For example, the kernel append file for the Crown Bay BSP is in the
4216 <filename>meta-intel</filename> Git repository and is named
4217 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend</filename>.
4218 Here are the related statements from the append file:
4219 <literallayout class='monospaced'>
4220 COMPATIBLE_MACHINE_crownbay = "crownbay"
4221 KMACHINE_crownbay = "crownbay"
4222 KBRANCH_crownbay = "standard/crownbay"
4223 KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb"
4224
4225 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
4226 KMACHINE_crownbay-noemgd = "crownbay"
4227 KBRANCH_crownbay-noemgd = "standard/crownbay"
4228 KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb"
4229 </literallayout>
4230 The <filename>KBRANCH_*</filename> statements identify
4231 the kernel branch to use when building for the Crown
4232 Bay BSP.
4233 In this case there are two identical statements: one
4234 for each type of Crown Bay machine.
4235 </para>
4236 </glossdef>
4237 </glossentry>
4238
4239 <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
4240 <glossdef>
4241 <para>
4242 Defines the Linux kernel source repository's default
4243 branch used to build the Linux kernel.
4244 The <filename>KBRANCH_DEFAULT</filename> value is
4245 the default value for
4246 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
4247 Unless you specify otherwise,
4248 <filename>KBRANCH_DEFAULT</filename> initializes to
4249 "master".
4250 </para>
4251 </glossdef>
4252 </glossentry>
4253
4254 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
4255 <glossdef>
4256 <para>
4257 Specifies additional <filename>make</filename>
4258 command-line arguments the OpenEmbedded build system
4259 passes on when compiling the kernel.
4260 </para>
4261 </glossdef>
4262 </glossentry>
4263
4264 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
4265 <glossdef>
4266 <para>Includes additional metadata from the Yocto Project kernel Git repository.
4267 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
4268 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4269 is provided through
4270 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
4271 and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
4272 You can use the <filename>KERNEL_FEATURES</filename> variable to further
4273 add metadata for all BSPs.</para>
4274 <para>The metadata you add through this variable includes config fragments and
4275 features descriptions,
4276 which usually includes patches as well as config fragments.
4277 You typically override the <filename>KERNEL_FEATURES</filename> variable
4278 for a specific machine.
4279 In this way, you can provide validated, but optional, sets of kernel
4280 configurations and features.</para>
4281 <para>For example, the following adds <filename>netfilter</filename> to all
4282 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
4283 machine:
4284 <literallayout class='monospaced'>
4285 # Add netfilter to all linux-yocto kernels
4286 KERNEL_FEATURES="features/netfilter"
4287
4288 # Add sound support to the qemux86 machine
4289 KERNEL_FEATURES_append_qemux86=" cfg/sound"
4290 </literallayout></para>
4291 </glossdef>
4292 </glossentry>
4293
4294 <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm>
4295 <glossdef>
4296 <para>
4297 The base name of the kernel image.
4298 This variable is set in the
4299 <link linkend='ref-classes-kernel'>kernel</link> class
4300 as follows:
4301 <literallayout class='monospaced'>
4302 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
4303 </literallayout>
4304 See the
4305 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>,
4306 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
4307 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
4308 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
4309 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
4310 and
4311 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
4312 variables for additional information.
4313 </para>
4314 </glossdef>
4315 </glossentry>
4316
4317 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
4318 <glossdef>
4319 <para>The type of kernel to build for a device, usually set by the
4320 machine configuration files and defaults to "zImage".
4321 This variable is used
4322 when building the kernel and is passed to <filename>make</filename> as the target to
4323 build.</para>
4324 </glossdef>
4325 </glossentry>
4326
4327 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
4328 <glossdef>
4329 <para>
4330 The location of the kernel sources.
4331 This variable is set to the value of the
4332 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
4333 within the <filename>module.bbclass</filename> class.
4334 For information on how this variable is used, see the
4335 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
4336 section.
4337 </para>
4338
4339 <para>
4340 To help maximize compatibility with out-of-tree drivers
4341 used to build modules, the OpenEmbedded build system also
4342 recognizes and uses the
4343 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
4344 variable, which is identical to the
4345 <filename>KERNEL_PATH</filename> variable.
4346 Both variables are common variables used by external
4347 Makefiles to point to the kernel source directory.
4348 </para>
4349 </glossdef>
4350 </glossentry>
4351
4352 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
4353 <glossdef>
4354 <para>
4355 The location of the kernel sources.
4356 This variable is set to the value of the
4357 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
4358 within the <filename>module.bbclass</filename> class.
4359 For information on how this variable is used, see the
4360 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
4361 section.
4362 </para>
4363
4364 <para>
4365 To help maximize compatibility with out-of-tree drivers
4366 used to build modules, the OpenEmbedded build system also
4367 recognizes and uses the
4368 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
4369 variable, which is identical to the
4370 <filename>KERNEL_SRC</filename> variable.
4371 Both variables are common variables used by external
4372 Makefiles to point to the kernel source directory.
4373 </para>
4374 </glossdef>
4375 </glossentry>
4376
4377 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
4378 <glossdef>
4379 <para>
4380 Provides a short description of a configuration fragment.
4381 You use this variable in the <filename>.scc</filename>
4382 file that describes a configuration fragment file.
4383 Here is the variable used in a file named
4384 <filename>smp.scc</filename> to describe SMP being
4385 enabled:
4386 <literallayout class='monospaced'>
4387 define KFEATURE_DESCRIPTION "Enable SMP"
4388 </literallayout>
4389 </para>
4390 </glossdef>
4391 </glossentry>
4392
4393 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
4394 <glossdef>
4395 <para>
4396 The machine as known by the kernel.
4397 Sometimes the machine name used by the kernel does not match the machine name
4398 used by the OpenEmbedded build system.
4399 For example, the machine name that the OpenEmbedded build system understands as
4400 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
4401 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
4402 For cases like these, the <filename>KMACHINE</filename> variable maps the
4403 kernel machine name to the OpenEmbedded build system machine name.
4404 </para>
4405
4406 <para>
4407 Kernel machine names are initially defined in the
4408 Yocto Linux Kernel's <filename>meta</filename> branch.
4409 From the <filename>meta</filename> branch, look in
4410 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
4411 For example, from the <filename>meta</filename> branch in the
4412 <filename>linux-yocto-3.0</filename> kernel, the
4413 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
4414 has the following:
4415 <literallayout class='monospaced'>
4416 define KMACHINE cedartrail
4417 define KTYPE standard
4418 define KARCH i386
4419
4420 include ktypes/standard
4421 branch cedartrail
4422
4423 include cedartrail.scc
4424 </literallayout>
4425 You can see that the kernel understands the machine name for
4426 the Cedar Trail Board Support Package (BSP) as
4427 <filename>cedartrail</filename>.
4428 </para>
4429
4430 <para>
4431 If you look in the Cedar Trail BSP layer in the
4432 <filename>meta-intel</filename>
4433 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
4434 at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
4435 you will find the following statements among others:
4436 <literallayout class='monospaced'>
4437 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
4438 KMACHINE_cedartrail = "cedartrail"
4439 KBRANCH_cedartrail = "yocto/standard/cedartrail"
4440 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
4441 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
4442
4443 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
4444 KMACHINE_cedartrail-nopvr = "cedartrail"
4445 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
4446 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
4447 </literallayout>
4448 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
4449 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
4450 names.
4451 </para>
4452
4453 <para>
4454 This append file uses two <filename>KMACHINE</filename> statements.
4455 The first is not really necessary but does ensure that the machine known to the
4456 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
4457 in the kernel also known as <filename>cedartrail</filename>:
4458 <literallayout class='monospaced'>
4459 KMACHINE_cedartrail = "cedartrail"
4460 </literallayout>
4461 </para>
4462
4463 <para>
4464 The second statement is a good example of why the <filename>KMACHINE</filename> variable
4465 is needed.
4466 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
4467 machine name to refer to the Cedar Trail BSP that does not support the proprietary
4468 PowerVR driver.
4469 The kernel, however, uses the machine name <filename>cedartrail</filename>.
4470 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
4471 the kernel's <filename>cedartrail</filename> name:
4472 <literallayout class='monospaced'>
4473 KMACHINE_cedartrail-nopvr = "cedartrail"
4474 </literallayout>
4475 </para>
4476
4477 <para>
4478 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
4479 Project kernel machine names and the OpenEmbedded machine names.
4480 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
4481 name you use is different than that used in the kernel.
4482 </para>
4483 </glossdef>
4484 </glossentry>
4485
4486 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
4487 <glossdef>
4488 <para>
4489 Defines the kernel type to be used in assembling the
4490 configuration.
4491 The linux-yocto recipes define "standard", "tiny",
4492 and "preempt-rt" kernel types.
4493 See the
4494 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4495 section in the Yocto Project Linux Kernel Development
4496 Manual for more information on kernel types.
4497 </para>
4498
4499 <para>
4500 You define the <filename>KTYPE</filename> variable in the
4501 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
4502 The value you use must match the value used for the
4503 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
4504 value used by the kernel recipe.
4505 </para>
4506 </glossdef>
4507 </glossentry>
4508 </glossdiv>
4509
4510 <glossdiv id='var-glossary-l'><title>L</title>
4511
4512 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
4513 <glossdef>
4514 <para>
4515 Provides a list of targets for automatic configuration.
4516 </para>
4517
4518 <para>
4519 See the
4520 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
4521 class for more information on how this variable is used.
4522 </para>
4523 </glossdef>
4524 </glossentry>
4525
4526 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
4527 <glossdef>
4528 <para>Lists the layers that this recipe depends upon, separated by spaces.
4529 Optionally, you can specify a specific layer version for a dependency
4530 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
4531 to be compared against
4532 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
4533 in this case).
4534 An error will be produced if any dependency is missing or
4535 the version numbers do not match exactly (if specified).
4536 This variable is used in the <filename>conf/layer.conf</filename> file
4537 and must be suffixed with the name of the specific layer (e.g.
4538 <filename>LAYERDEPENDS_mylayer</filename>).</para>
4539 </glossdef>
4540 </glossentry>
4541
4542 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
4543 <glossdef>
4544 <para>When used inside the <filename>layer.conf</filename> configuration
4545 file, this variable provides the path of the current layer.
4546 This variable is not available outside of <filename>layer.conf</filename>
4547 and references are expanded immediately when parsing of the file completes.</para>
4548 </glossdef>
4549 </glossentry>
4550
4551 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
4552 <glossdef>
4553 <para>Optionally specifies the version of a layer as a single number.
4554 You can use this within
4555 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
4556 for another layer in order to depend on a specific version
4557 of the layer.
4558 This variable is used in the <filename>conf/layer.conf</filename> file
4559 and must be suffixed with the name of the specific layer (e.g.
4560 <filename>LAYERVERSION_mylayer</filename>).</para>
4561 </glossdef>
4562 </glossentry>
4563
4564 <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
4565 <glossdef>
4566 <para>
4567 Specifies the flags to pass to the linker.
4568 This variable is exported to an environment
4569 variable and thus made visible to the software being
4570 built during the compilation step.
4571 </para>
4572
4573 <para>
4574 Default initialization for <filename>LDFLAGS</filename>
4575 varies depending on what is being built:
4576 <itemizedlist>
4577 <listitem><para>
4578 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
4579 when building for the target
4580 </para></listitem>
4581 <listitem><para>
4582 <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
4583 when building for the build host (i.e.
4584 <filename>-native</filename>)
4585 </para></listitem>
4586 <listitem><para>
4587 <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
4588 when building for an SDK (i.e.
4589 <filename>nativesdk-</filename>)
4590 </para></listitem>
4591 </itemizedlist>
4592 </para>
4593 </glossdef>
4594 </glossentry>
4595
4596 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
4597 <glossdef>
4598 <para>
4599 Specifies the lead (or primary) compiled library file
4600 (<filename>.so</filename>) that the
4601 <link linkend='ref-classes-debian'><filename>debian</filename></link>
4602 class applies its naming policy to given a recipe that
4603 packages multiple libraries.
4604 </para>
4605
4606 <para>
4607 This variable works in conjunction with the
4608 <filename>debian</filename> class.
4609 </para>
4610 </glossdef>
4611 </glossentry>
4612
4613 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
4614 <glossdef>
4615 <para>Checksums of the license text in the recipe source code.</para>
4616 <para>This variable tracks changes in license text of the source
4617 code files.
4618 If the license text is changed, it will trigger a build
4619 failure, which gives the developer an opportunity to review any
4620 license change.</para>
4621 <para>
4622 This variable must be defined for all recipes (unless
4623 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
4624 is set to "CLOSED")</para>
4625 <para>For more information, see the
4626 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
4627 Tracking License Changes</link> section</para>
4628 </glossdef>
4629 </glossentry>
4630
4631 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
4632 <glossdef>
4633 <para>
4634 The list of source licenses for the recipe.
4635 Follow these rules:
4636 <itemizedlist>
4637 <listitem><para>Do not use spaces within individual
4638 license names.</para></listitem>
4639 <listitem><para>Separate license names using
4640 | (pipe) when there is a choice between licenses.
4641 </para></listitem>
4642 <listitem><para>Separate license names using
4643 &amp; (ampersand) when multiple licenses exist
4644 that cover different parts of the source.
4645 </para></listitem>
4646 <listitem><para>You can use spaces between license
4647 names.</para></listitem>
4648 <listitem><para>For standard licenses, use the names
4649 of the files in
4650 <filename>meta/files/common-licenses/</filename>
4651 or the
4652 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
4653 flag names defined in
4654 <filename>meta/conf/licenses.conf</filename>.
4655 </para></listitem>
4656 </itemizedlist>
4657 </para>
4658
4659 <para>
4660 Here are some examples:
4661 <literallayout class='monospaced'>
4662 LICENSE = "LGPLv2.1 | GPLv3"
4663 LICENSE = "MPL-1 &amp; LGPLv2.1"
4664 LICENSE = "GPLv2+"
4665 </literallayout>
4666 The first example is from the recipes for Qt, which the user
4667 may choose to distribute under either the LGPL version
4668 2.1 or GPL version 3.
4669 The second example is from Cairo where two licenses cover
4670 different parts of the source code.
4671 The final example is from <filename>sysstat</filename>,
4672 which presents a single license.
4673 </para>
4674
4675 <para>
4676 You can also specify licenses on a per-package basis to
4677 handle situations where components of the output have
4678 different licenses.
4679 For example, a piece of software whose code is
4680 licensed under GPLv2 but has accompanying documentation
4681 licensed under the GNU Free Documentation License 1.2 could
4682 be specified as follows:
4683 <literallayout class='monospaced'>
4684 LICENSE = "GFDL-1.2 &amp; GPLv2"
4685 LICENSE_${PN} = "GPLv2"
4686 LICENSE_${PN}-doc = "GFDL-1.2"
4687 </literallayout>
4688 </para>
4689 </glossdef>
4690 </glossentry>
4691
4692 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
4693 <glossdef>
4694 <para>Path to additional licenses used during the build.
4695 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
4696 to define the directory that holds common license text used during the build.
4697 The <filename>LICENSE_PATH</filename> variable allows you to extend that
4698 location to other areas that have additional licenses:
4699 <literallayout class='monospaced'>
4700 LICENSE_PATH += "/path/to/additional/common/licenses"
4701 </literallayout></para>
4702 </glossdef>
4703 </glossentry>
4704
4705 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
4706 <glossdef>
4707 <para>
4708 Defines the kernel type to be used in assembling the
4709 configuration.
4710 The linux-yocto recipes define "standard", "tiny", and
4711 "preempt-rt" kernel types.
4712 See the
4713 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4714 section in the Yocto Project Linux Kernel Development
4715 Manual for more information on kernel types.
4716 </para>
4717
4718 <para>
4719 If you do not specify a
4720 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
4721 "standard".
4722 Together with
4723 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
4724 the <filename>LINUX_KERNEL_TYPE</filename> variable
4725 defines the search
4726 arguments used by the kernel tools to find the appropriate
4727 description within the kernel
4728 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4729 with which to build out the sources and configuration.
4730 </para>
4731 </glossdef>
4732 </glossentry>
4733
4734 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
4735 <glossdef>
4736 <para>The Linux version from <filename>kernel.org</filename>
4737 on which the Linux kernel image being built using the
4738 OpenEmbedded build system is based.
4739 You define this variable in the kernel recipe.
4740 For example, the <filename>linux-yocto-3.4.bb</filename>
4741 kernel recipe found in
4742 <filename>meta/recipes-kernel/linux</filename>
4743 defines the variables as follows:
4744 <literallayout class='monospaced'>
4745 LINUX_VERSION ?= "3.4.24"
4746 </literallayout>
4747 The <filename>LINUX_VERSION</filename> variable is used to
4748 define <link linkend='var-PV'><filename>PV</filename></link>
4749 for the recipe:
4750 <literallayout class='monospaced'>
4751 PV = "${LINUX_VERSION}+git${SRCPV}"
4752 </literallayout></para>
4753 </glossdef>
4754 </glossentry>
4755
4756 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
4757 <glossdef>
4758 <para>A string extension compiled into the version
4759 string of the Linux kernel built with the OpenEmbedded
4760 build system.
4761 You define this variable in the kernel recipe.
4762 For example, the linux-yocto kernel recipes all define
4763 the variable as follows:
4764 <literallayout class='monospaced'>
4765 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
4766 </literallayout>
4767 Defining this variable essentially sets the
4768 Linux kernel configuration item
4769 <filename>CONFIG_LOCALVERSION</filename>, which is visible
4770 through the <filename>uname</filename> command.
4771 Here is an example that shows the extension assuming it
4772 was set as previously shown:
4773 <literallayout class='monospaced'>
4774 $ uname -r
4775 3.7.0-rc8-custom
4776 </literallayout>
4777 </para>
4778 </glossdef>
4779 </glossentry>
4780
4781 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
4782 <glossdef>
4783 <para>
4784 Specifies the directory to which the OpenEmbedded build
4785 system writes overall log files.
4786 The default directory is <filename>${TMPDIR}/log</filename>.
4787 </para>
4788 <para>
4789 For the directory containing logs specific to each task,
4790 see the <link linkend='var-T'><filename>T</filename></link>
4791 variable.
4792 </para>
4793 </glossdef>
4794 </glossentry>
4795
4796 </glossdiv>
4797
4798 <glossdiv id='var-glossary-m'><title>M</title>
4799
4800 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
4801 <glossdef>
4802 <para>
4803 Specifies the target device for which the image is built.
4804 You define <filename>MACHINE</filename> in the
4805 <filename>local.conf</filename> file found in the
4806 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
4807 By default, <filename>MACHINE</filename> is set to
4808 "qemux86", which is an x86-based architecture machine to
4809 be emulated using QEMU:
4810 <literallayout class='monospaced'>
4811 MACHINE ?= "qemux86"
4812 </literallayout>
4813 The variable corresponds to a machine configuration file of the
4814 same name, through which machine-specific configurations are set.
4815 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
4816 exists the corresponding <filename>qemux86.conf</filename> machine
4817 configuration file, which can be found in the
4818 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4819 in <filename>meta/conf/machine</filename>.
4820 </para>
4821
4822 <para>
4823 The list of machines supported by the Yocto Project as
4824 shipped include the following:
4825 <literallayout class='monospaced'>
4826 MACHINE ?= "qemuarm"
4827 MACHINE ?= "qemumips"
4828 MACHINE ?= "qemuppc"
4829 MACHINE ?= "qemux86"
4830 MACHINE ?= "qemux86-64"
4831 MACHINE ?= "genericx86"
4832 MACHINE ?= "genericx86-64"
4833 MACHINE ?= "beaglebone"
4834 MACHINE ?= "mpc8315e-rdb"
4835 MACHINE ?= "edgerouter"
4836 </literallayout>
4837 The last five are Yocto Project reference hardware boards, which
4838 are provided in the <filename>meta-yocto-bsp</filename> layer.
4839 <note>Adding additional Board Support Package (BSP) layers
4840 to your configuration adds new possible settings for
4841 <filename>MACHINE</filename>.
4842 </note>
4843 </para>
4844 </glossdef>
4845 </glossentry>
4846
4847 <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
4848 <glossdef>
4849 <para>
4850 Specifies the name of the machine-specific architecture.
4851 This variable is set automatically from
4852 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
4853 or
4854 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
4855 You should not hand-edit the
4856 <filename>MACHINE_ARCH</filename> variable.
4857 </para>
4858 </glossdef>
4859 </glossentry>
4860
4861 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
4862 <glossdef>
4863 <para></para>
4864 <para>
4865 A list of required machine-specific packages to install as part of
4866 the image being built.
4867 The build process depends on these packages being present.
4868 Furthermore, because this is a "machine essential" variable, the list of
4869 packages are essential for the machine to boot.
4870 The impact of this variable affects images based on
4871 <filename>packagegroup-core-boot</filename>,
4872 including the <filename>core-image-minimal</filename> image.
4873 </para>
4874 <para>
4875 This variable is similar to the
4876 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
4877 variable with the exception that the image being built has a build
4878 dependency on the variable's list of packages.
4879 In other words, the image will not build if a file in this list is not found.
4880 </para>
4881 <para>
4882 As an example, suppose the machine for which you are building requires
4883 <filename>example-init</filename> to be run during boot to initialize the hardware.
4884 In this case, you would use the following in the machine's
4885 <filename>.conf</filename> configuration file:
4886 <literallayout class='monospaced'>
4887 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4888 </literallayout>
4889 </para>
4890 </glossdef>
4891 </glossentry>
4892
4893 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
4894 <glossdef>
4895 <para></para>
4896 <para>
4897 A list of recommended machine-specific packages to install as part of
4898 the image being built.
4899 The build process does not depend on these packages being present.
4900 However, because this is a "machine essential" variable, the list of
4901 packages are essential for the machine to boot.
4902 The impact of this variable affects images based on
4903 <filename>packagegroup-core-boot</filename>,
4904 including the <filename>core-image-minimal</filename> image.
4905 </para>
4906 <para>
4907 This variable is similar to the
4908 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
4909 variable with the exception that the image being built does not have a build
4910 dependency on the variable's list of packages.
4911 In other words, the image will still build if a package in this list is not found.
4912 Typically, this variable is used to handle essential kernel modules, whose
4913 functionality may be selected to be built into the kernel rather than as a module,
4914 in which case a package will not be produced.
4915 </para>
4916 <para>
4917 Consider an example where you have a custom kernel where a specific touchscreen
4918 driver is required for the machine to be usable.
4919 However, the driver can be built as a module or
4920 into the kernel depending on the kernel configuration.
4921 If the driver is built as a module, you want it to be installed.
4922 But, when the driver is built into the kernel, you still want the
4923 build to succeed.
4924 This variable sets up a "recommends" relationship so that in the latter case,
4925 the build will not fail due to the missing package.
4926 To accomplish this, assuming the package for the module was called
4927 <filename>kernel-module-ab123</filename>, you would use the
4928 following in the machine's <filename>.conf</filename> configuration
4929 file:
4930 <literallayout class='monospaced'>
4931 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4932 </literallayout>
4933 </para>
4934 <para>
4935 Some examples of these machine essentials are flash, screen, keyboard, mouse,
4936 or touchscreen drivers (depending on the machine).
4937 </para>
4938 </glossdef>
4939 </glossentry>
4940
4941 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
4942 <glossdef>
4943 <para>
4944 A list of machine-specific packages to install as part of the
4945 image being built that are not essential for the machine to boot.
4946 However, the build process for more fully-featured images
4947 depends on the packages being present.
4948 </para>
4949 <para>
4950 This variable affects all images based on
4951 <filename>packagegroup-base</filename>, which does not include the
4952 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4953 images.
4954 </para>
4955 <para>
4956 The variable is similar to the
4957 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
4958 variable with the exception that the image being built has a build
4959 dependency on the variable's list of packages.
4960 In other words, the image will not build if a file in this list is not found.
4961 </para>
4962 <para>
4963 An example is a machine that has WiFi capability but is not
4964 essential for the machine to boot the image.
4965 However, if you are building a more fully-featured image, you want to enable
4966 the WiFi.
4967 The package containing the firmware for the WiFi hardware is always
4968 expected to exist, so it is acceptable for the build process to depend upon
4969 finding the package.
4970 In this case, assuming the package for the firmware was called
4971 <filename>wifidriver-firmware</filename>, you would use the following in the
4972 <filename>.conf</filename> file for the machine:
4973 <literallayout class='monospaced'>
4974 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4975 </literallayout>
4976 </para>
4977 </glossdef>
4978 </glossentry>
4979
4980 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
4981 <glossdef>
4982 <para></para>
4983 <para>
4984 A list of machine-specific packages to install as part of the
4985 image being built that are not essential for booting the machine.
4986 The image being built has no build dependency on this list of packages.
4987 </para>
4988 <para>
4989 This variable affects only images based on
4990 <filename>packagegroup-base</filename>, which does not include the
4991 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4992 images.
4993 </para>
4994 <para>
4995 This variable is similar to the
4996 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
4997 variable with the exception that the image being built does not have a build
4998 dependency on the variable's list of packages.
4999 In other words, the image will build if a file in this list is not found.
5000 </para>
5001 <para>
5002 An example is a machine that has WiFi capability but is not essential
5003 For the machine to boot the image.
5004 However, if you are building a more fully-featured image, you want to enable
5005 WiFi.
5006 In this case, the package containing the WiFi kernel module will not be produced
5007 if the WiFi driver is built into the kernel, in which case you still want the
5008 build to succeed instead of failing as a result of the package not being found.
5009 To accomplish this, assuming the package for the module was called
5010 <filename>kernel-module-examplewifi</filename>, you would use the
5011 following in the <filename>.conf</filename> file for the machine:
5012 <literallayout class='monospaced'>
5013 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
5014 </literallayout>
5015 </para>
5016 </glossdef>
5017 </glossentry>
5018
5019 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
5020 <glossdef>
5021 <para>
5022 Specifies the list of hardware features the
5023 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
5024 of supporting.
5025 For related information on enabling features, see the
5026 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
5027 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
5028 and
5029 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
5030 variables.
5031 </para>
5032
5033 <para>
5034 For a list of hardware features supported by the Yocto
5035 Project as shipped, see the
5036 "<link linkend='ref-features-machine'>Machine Features</link>"
5037 section.
5038 </para>
5039 </glossdef>
5040 </glossentry>
5041
5042 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
5043 <glossdef>
5044 <para>Features to be added to
5045 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
5046 if not also present in
5047 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
5048 </para>
5049
5050 <para>
5051 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
5052 It is not intended to be user-configurable.
5053 It is best to just reference the variable to see which machine features are
5054 being backfilled for all machine configurations.
5055 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
5056 more information.
5057 </para>
5058 </glossdef>
5059 </glossentry>
5060
5061 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
5062 <glossdef>
5063 <para>Features from
5064 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
5065 that should not be backfilled (i.e. added to
5066 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
5067 during the build.
5068 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
5069 more information.
5070 </para>
5071 </glossdef>
5072 </glossentry>
5073
5074 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
5075 <glossdef>
5076 <para>
5077 Lists overrides specific to the current machine.
5078 By default, this list includes the value
5079 of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
5080 You can extend the list to apply variable overrides for
5081 classes of machines.
5082 For example, all QEMU emulated machines (e.g. qemuarm,
5083 qemux86, and so forth) include a common file named
5084 <filename>meta/conf/machine/include/qemu.inc</filename>
5085 that prepends <filename>MACHINEOVERRIDES</filename> with
5086 the following variable override:
5087 <literallayout class='monospaced'>
5088 MACHINEOVERRIDES =. "qemuall:"
5089 </literallayout>
5090 Applying an override like <filename>qemuall</filename>
5091 affects all QEMU emulated machines elsewhere.
5092 Here is an example from the
5093 <filename>connman-conf</filename> recipe:
5094 <literallayout class='monospaced'>
5095 SRC_URI_append_qemuall = "file://wired.config \
5096 file://wired-setup \
5097 "
5098 </literallayout>
5099 </para>
5100 </glossdef>
5101 </glossentry>
5102
5103 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
5104 <glossdef>
5105 <para>The email address of the distribution maintainer.</para>
5106 </glossdef>
5107 </glossentry>
5108
5109 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
5110 <glossdef>
5111 <para>
5112 Specifies additional paths from which the OpenEmbedded
5113 build system gets source code.
5114 When the build system searches for source code, it first
5115 tries the local download directory.
5116 If that location fails, the build system tries locations
5117 defined by
5118 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
5119 the upstream source, and then locations specified by
5120 <filename>MIRRORS</filename> in that order.
5121 </para>
5122
5123 <para>
5124 Assuming your distribution
5125 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
5126 is "poky", the default value for
5127 <filename>MIRRORS</filename> is defined in the
5128 <filename>conf/distro/poky.conf</filename> file in the
5129 <filename>meta-yocto</filename> Git repository.
5130 </para>
5131 </glossdef>
5132 </glossentry>
5133
5134 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
5135 <glossdef>
5136 <para>
5137 Specifies a prefix has been added to
5138 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
5139 of a recipe or package, such as a Multilib version.
5140 The variable is used in places where the prefix needs to be
5141 added to or removed from a the name (e.g. the
5142 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
5143 <filename>MLPREFIX</filename> gets set when a prefix has been
5144 added to <filename>PN</filename>.
5145 </para>
5146 </glossdef>
5147 </glossentry>
5148
5149 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
5150 <glossdef>
5151 <para>
5152 Lists kernel modules that need to be auto-loaded during
5153 boot.
5154 </para>
5155
5156 <para>
5157 You can use this variable anywhere that it can be
5158 recognized by the kernel recipe or out-of-tree kernel
5159 module recipe (e.g. a machine configuration file, a
5160 distribution configuration file, an append file for the
5161 recipe, or the recipe itself).
5162 </para>
5163
5164 <para>
5165 Specify it as follows:
5166 <literallayout class='monospaced'>
5167 module_autoload_&lt;modname&gt; = "modname1 modname2 modname3"
5168 </literallayout>
5169 You must use the kernel module name override.
5170 </para>
5171
5172 <para>
5173 Including <filename>module_autoload</filename> causes the
5174 OpenEmbedded build system to populate the
5175 <filename>/etc/modules-load.d/modname.conf</filename>
5176 file with the list of modules to be auto-loaded on boot.
5177 The modules appear one-per-line in the file.
5178 Here is an example of the most common use case:
5179 <literallayout class='monospaced'>
5180 module_autoload_modname = "modname"
5181 </literallayout>
5182 </para>
5183
5184 <para>
5185 For information on how to populate the
5186 <filename>modname.conf</filename> file with
5187 <filename>modprobe.d</filename> syntax lines, see the
5188 <link linkend='var-module_conf'><filename>module_conf</filename></link>
5189 variable.
5190 </para>
5191 </glossdef>
5192 </glossentry>
5193
5194 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
5195 <glossdef>
5196 <para>
5197 Specifies <filename>modprobe.d</filename> syntax lines
5198 for inclusion in the
5199 <filename>/etc/modprobe.d/modname.conf</filename> file.
5200 </para>
5201
5202 <para>
5203 You can use this variable anywhere that it can be
5204 recognized by the kernel recipe or out-of-tree kernel
5205 module recipe (e.g. a machine configuration file, a
5206 distribution configuration file, an append file for the
5207 recipe, or the recipe itself).
5208 </para>
5209
5210 <para>
5211 Here is the general syntax:
5212 <literallayout class='monospaced'>
5213 module_conf_&lt;modname&gt; = "modprobe.d-syntax"
5214 </literallayout>
5215 You must use the kernel module name override.
5216 </para>
5217
5218 <para>
5219 Run <filename>man modprobe.d</filename> in the shell to
5220 find out more information on the exact syntax for lines
5221 you want to provide with <filename>module_conf</filename>.
5222 </para>
5223
5224 <para>
5225 Including <filename>module_conf</filename> causes the
5226 OpenEmbedded build system to populate the
5227 <filename>/etc/modprobe.d/modname.conf</filename>
5228 file with <filename>modprobe.d</filename> syntax lines.
5229 Here is an example:
5230 <literallayout class='monospaced'>
5231 module_conf_&lt;modname&gt; = "options modname arg1=val1 arg2=val2"
5232 </literallayout>
5233 </para>
5234
5235 <para>
5236 For information on how to specify kernel modules to
5237 auto-load on boot, see the
5238 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
5239 variable.
5240 </para>
5241 </glossdef>
5242 </glossentry>
5243
5244 <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm>
5245 <glossdef>
5246 <para>
5247 The base name of the kernel modules tarball.
5248 This variable is set in the
5249 <link linkend='ref-classes-kernel'>kernel</link> class
5250 as follows:
5251 <literallayout class='monospaced'>
5252 MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
5253 </literallayout>
5254 See the
5255 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
5256 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
5257 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
5258 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
5259 and
5260 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
5261 variables for additional information.
5262 </para>
5263 </glossdef>
5264 </glossentry>
5265
5266 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
5267 <glossdef>
5268 <para>
5269 Controls creation of the <filename>modules-*.tgz</filename>
5270 file.
5271 Set this variable to "0" to disable creation of this
5272 file, which contains all of the kernel modules resulting
5273 from a kernel build.
5274 </para>
5275 </glossdef>
5276 </glossentry>
5277
5278 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
5279 <glossdef>
5280 <para>
5281 Separates files for different machines such that you can build
5282 for multiple target machines using the same output directories.
5283 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
5284 for an example.
5285 </para>
5286 </glossdef>
5287 </glossentry>
5288
5289 </glossdiv>
5290
5291 <glossdiv id='var-glossary-n'><title>N</title>
5292
5293 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
5294 <glossdef>
5295 <para>
5296 A string identifying the host distribution.
5297 Strings consist of the host distributor ID
5298 followed by the release, as reported by the
5299 <filename>lsb_release</filename> tool
5300 or as read from <filename>/etc/lsb-release</filename>.
5301 For example, when running a build on Ubuntu 12.10, the value
5302 is "Ubuntu-12.10".
5303 If this information is unable to be determined, the value
5304 resolves to "Unknown".
5305 </para>
5306 <para>
5307 This variable is used by default to isolate native shared
5308 state packages for different distributions (e.g. to avoid
5309 problems with <filename>glibc</filename> version
5310 incompatibilities).
5311 Additionally, the variable is checked against
5312 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
5313 if that variable is set.
5314 </para>
5315 </glossdef>
5316 </glossentry>
5317
5318 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
5319 <glossdef>
5320 <para>
5321 Prevents installation of all "recommended-only" packages.
5322 Recommended-only packages are packages installed only
5323 through the
5324 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
5325 variable).
5326 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
5327 to "1" turns this feature on:
5328 <literallayout class='monospaced'>
5329 NO_RECOMMENDATIONS = "1"
5330 </literallayout>
5331 You can set this variable globally in your
5332 <filename>local.conf</filename> file or you can attach it to
5333 a specific image recipe by using the recipe name override:
5334 <literallayout class='monospaced'>
5335 NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
5336 </literallayout>
5337 </para>
5338
5339 <para>
5340 It is important to realize that if you choose to not install
5341 packages using this variable and some other packages are
5342 dependent on them (i.e. listed in a recipe's
5343 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5344 variable), the OpenEmbedded build system ignores your
5345 request and will install the packages to avoid dependency
5346 errors.
5347 <note>
5348 Some recommended packages might be required for certain
5349 system functionality, such as kernel modules.
5350 It is up to you to add packages with the
5351 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
5352 variable.
5353 </note>
5354 </para>
5355
5356 <para>
5357 Support for this variable exists only when using the
5358 IPK and RPM packaging backend.
5359 Support does not exist for DEB.
5360 </para>
5361
5362 <para>
5363 See the
5364 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
5365 and the
5366 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
5367 variables for related information.
5368 </para>
5369 </glossdef>
5370 </glossentry>
5371
5372 <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm>
5373 <glossdef>
5374 <para>
5375 Causes the OpenEmbedded build system to skip building the
5376 <filename>.hddimg</filename> image.
5377 The <filename>NOHDD</filename> variable is used with the
5378 <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link>
5379 class.
5380 Set the variable to "1" to prevent the
5381 <filename>.hddimg</filename> image from being built.
5382 </para>
5383 </glossdef>
5384 </glossentry>
5385
5386 <glossentry id='var-NOISO'><glossterm>NOISO</glossterm>
5387 <glossdef>
5388 <para>
5389 Causes the OpenEmbedded build system to skip building the
5390 ISO image.
5391 The <filename>NOISO</filename> variable is used with the
5392 <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link>
5393 class.
5394 Set the variable to "1" to prevent the ISO image from
5395 being built.
5396 To enable building an ISO image, set the variable to "0".
5397 </para>
5398 </glossdef>
5399 </glossentry>
5400
5401 </glossdiv>
5402
5403 <glossdiv id='var-glossary-o'><title>O</title>
5404
5405 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
5406 <glossdef>
5407 <para>
5408 When a recipe inherits the
5409 <filename>binconfig.bbclass</filename> class, this variable
5410 specifies additional arguments passed to the "sed" command.
5411 The sed command alters any paths in configuration scripts
5412 that have been set up during compilation.
5413 Inheriting this class results in all paths in these scripts
5414 being changed to point into the
5415 <filename>sysroots/</filename> directory so that all builds
5416 that use the script will use the correct directories
5417 for the cross compiling layout.
5418 </para>
5419
5420 <para>
5421 See the <filename>meta/classes/binconfig.bbclass</filename>
5422 in the
5423 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
5424 for details on how this class applies these additional
5425 sed command arguments.
5426 For general information on the
5427 <filename>binconfig.bbclass</filename> class, see the
5428 "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
5429 section.
5430 </para>
5431 </glossdef>
5432 </glossentry>
5433
5434 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
5435 <glossdef>
5436 <para>
5437 An internal variable used to tell the OpenEmbedded build
5438 system what Python modules to import for every Python
5439 function run by the system.
5440 </para>
5441
5442 <note>
5443 Do not set this variable.
5444 It is for internal use only.
5445 </note>
5446 </glossdef>
5447 </glossentry>
5448
5449 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
5450 <glossdef>
5451 <para>
5452 Controls how the OpenEmbedded build system spawns
5453 interactive terminals on the host development system
5454 (e.g. using the BitBake command with the
5455 <filename>-c devshell</filename> command-line option).
5456 For more information, see the
5457 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
5458 in the Yocto Project Development Manual.
5459 </para>
5460
5461 <para>
5462 You can use the following values for the
5463 <filename>OE_TERMINAL</filename> variable:
5464 <literallayout class='monospaced'>
5465 auto
5466 gnome
5467 xfce
5468 rxvt
5469 screen
5470 konsole
5471 none
5472 </literallayout>
5473 <note>Konsole support only works for KDE 3.x.
5474 Also, "auto" is the default behavior for
5475 <filename>OE_TERMINAL</filename></note>
5476 </para>
5477 </glossdef>
5478 </glossentry>
5479
5480 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
5481 <glossdef>
5482 <para>
5483 The directory from which the top-level build environment
5484 setup script is sourced.
5485 The Yocto Project makes two top-level build environment
5486 setup scripts available:
5487 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
5488 and
5489 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
5490 When you run one of these scripts, the
5491 <filename>OEROOT</filename> variable resolves to the
5492 directory that contains the script.
5493 </para>
5494
5495 <para>
5496 For additional information on how this variable is used,
5497 see the initialization scripts.
5498 </para>
5499 </glossdef>
5500 </glossentry>
5501
5502 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
5503 <glossdef>
5504 <para>
5505 Declares the oldest version of the Linux kernel that the
5506 produced binaries must support.
5507 This variable is passed into the build of the Embedded
5508 GNU C Library (<filename>eglibc</filename>).
5509 </para>
5510
5511 <para>
5512 The default for this variable comes from the
5513 <filename>meta/conf/bitbake.conf</filename> configuration
5514 file.
5515 You can override this default by setting the variable
5516 in a custom distribution configuration file.
5517 </para>
5518 </glossdef>
5519 </glossentry>
5520
5521 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
5522 <glossdef>
5523 <para>
5524 BitBake uses <filename>OVERRIDES</filename> to control
5525 what variables are overridden after BitBake parses
5526 recipes and configuration files.
5527 You can find more information on how overrides are handled
5528 in the BitBake Manual that is located at
5529 <filename>bitbake/doc/manual</filename> in the
5530 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5531 </para>
5532 </glossdef>
5533 </glossentry>
5534 </glossdiv>
5535
5536 <glossdiv id='var-glossary-p'><title>P</title>
5537
5538 <glossentry id='var-P'><glossterm>P</glossterm>
5539 <glossdef>
5540 <para>The recipe name and version.
5541 <filename>P</filename> is comprised of the following:
5542 <literallayout class='monospaced'>
5543 ${PN}-${PV}
5544 </literallayout></para>
5545 </glossdef>
5546 </glossentry>
5547
5548 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
5549 <glossdef>
5550 <para>
5551 The architecture of the resulting package or packages.
5552 </para>
5553
5554 <para>
5555 By default, the value of this variable is set to
5556 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
5557 when building for the target,
5558 <filename>BUILD_ARCH</filename> when building for the
5559 build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
5560 for the SDK.
5561 However, if your recipe's output packages are built
5562 specific to the target machine rather than general for
5563 the architecture of the machine, you should set
5564 <filename>PACKAGE_ARCH</filename> to the value of
5565 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
5566 in the recipe as follows:
5567 <literallayout class='monospaced'>
5568 PACKAGE_ARCH = "${MACHINE_ARCH}"
5569 </literallayout>
5570 </para>
5571 </glossdef>
5572 </glossentry>
5573
5574 <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
5575 <glossdef>
5576 <para>
5577 Specifies a list of architectures compatible with
5578 the target machine.
5579 This variable is set automatically and should not
5580 normally be hand-edited.
5581 Entries are separated using spaces and listed in order
5582 of priority.
5583 The default value for
5584 <filename>PACKAGE_ARCHS</filename> is "all any noarch
5585 ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
5586 </para>
5587 </glossdef>
5588 </glossentry>
5589
5590
5591
5592 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
5593 <glossdef>
5594 <para>Enables easily adding packages to
5595 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
5596 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
5597 so that those added packages can pick up files that would normally be
5598 included in the default package.</para>
5599 </glossdef>
5600 </glossentry>
5601
5602 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
5603 <glossdef>
5604 <para>
5605 This variable, which is set in the
5606 <filename>local.conf</filename> configuration file found in
5607 the <filename>conf</filename> folder of the
5608 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
5609 specifies the package manager the OpenEmbedded build system
5610 uses when packaging data.
5611 </para>
5612
5613 <para>
5614 You can provide one or more of the following arguments for
5615 the variable:
5616 <literallayout class='monospaced'>
5617 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
5618 </literallayout>
5619 The build system uses only the first argument in the list
5620 as the package manager when creating your image or SDK.
5621 However, packages will be created using any additional
5622 packaging classes you specify.
5623 For example, if you use the following in your
5624 <filename>local.conf</filename> file:
5625 <literallayout class='monospaced'>
5626 PACKAGE_CLASSES ?= "package_ipk package_tar"
5627 </literallayout>
5628 The OpenEmbedded build system uses the IPK package manager
5629 to create your image or SDK as well as generating
5630 TAR packages.
5631 </para>
5632
5633 <para>
5634 You cannot specify the
5635 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
5636 class first in the list.
5637 Files using the <filename>.tar</filename> format cannot
5638 be used as a substitute packaging format
5639 for DEB, RPM, and IPK formatted files for your image or SDK.
5640 </para>
5641
5642 <para>
5643 For information on packaging and build performance effects
5644 as a result of the package manager in use, see the
5645 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
5646 section.
5647 </para>
5648 </glossdef>
5649 </glossentry>
5650
5651 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
5652 <glossdef>
5653 <para>
5654 Lists packages that should not be installed into an image.
5655 For example:
5656 <literallayout class='monospaced'>
5657 PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
5658 </literallayout>
5659 You can set this variable globally in your
5660 <filename>local.conf</filename> file or you can attach it to
5661 a specific image recipe by using the recipe name override:
5662 <literallayout class='monospaced'>
5663 PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
5664 </literallayout>
5665 </para>
5666
5667 <para>
5668 If you choose to not install
5669 a package using this variable and some other package is
5670 dependent on it (i.e. listed in a recipe's
5671 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5672 variable), the OpenEmbedded build system generates a fatal
5673 installation error.
5674 Because the build system halts the process with a fatal
5675 error, you can use the variable with an iterative
5676 development process to remove specific components from a
5677 system.
5678 </para>
5679
5680 <para>
5681 Support for this variable exists only when using the
5682 IPK and RPM packaging backend.
5683 Support does not exist for DEB.
5684 </para>
5685
5686 <para>
5687 See the
5688 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
5689 and the
5690 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
5691 variables for related information.
5692 </para>
5693 </glossdef>
5694 </glossentry>
5695
5696 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
5697 <glossdef>
5698 <para>Specifies the list of architectures compatible with the device CPU.
5699 This variable is useful when you build for several different devices that use
5700 miscellaneous processors such as XScale and ARM926-EJS).</para>
5701 </glossdef>
5702 </glossentry>
5703
5704 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
5705 <glossdef>
5706
5707 <para>
5708 The <filename>PACKAGE_GROUP</filename> variable has been
5709 renamed to
5710 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
5711 See the variable description for
5712 <filename>FEATURE_PACKAGES</filename> for information.
5713 </para>
5714
5715 <para>
5716 If if you use the <filename>PACKAGE_GROUP</filename>
5717 variable, the OpenEmbedded build system issues a warning
5718 message.
5719 </para>
5720 </glossdef>
5721 </glossentry>
5722
5723 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
5724 <glossdef>
5725 <para>
5726 The final list of packages passed to the package manager
5727 for installation into the image.
5728 </para>
5729
5730 <para>
5731 Because the package manager controls actual installation
5732 of all packages, the list of packages passed using
5733 <filename>PACKAGE_INSTALL</filename> is not the final list
5734 of packages that are actually installed.
5735 This variable is internal to the image construction
5736 code.
5737 Consequently, in general, you should use the
5738 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
5739 variable to specify packages for installation.
5740 The exception to this is when working with
5741 the
5742 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5743 image.
5744 When working with an initial RAM disk (initramfs)
5745 image, use the <filename>PACKAGE_INSTALL</filename>
5746 variable.
5747 </para>
5748 </glossdef>
5749 </glossentry>
5750
5751 <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
5752 <glossdef>
5753 <para>
5754 Specifies a list of functions run to pre-process the
5755 <link linkend='var-PKGD'><filename>PKGD</filename></link>
5756 directory prior to splitting the files out to individual
5757 packages.
5758 </para>
5759 </glossdef>
5760 </glossentry>
5761
5762 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
5763 <glossdef>
5764 <para>
5765 This variable provides a means of enabling or disabling
5766 features of a recipe on a per-recipe basis.
5767 <filename>PACKAGECONFIG</filename> blocks are defined
5768 in recipes when you specify features and then arguments
5769 that define feature behaviors.
5770 Here is the basic block structure:
5771 <literallayout class='monospaced'>
5772 PACKAGECONFIG ??= "f1 f2 f3 ..."
5773 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
5774 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
5775 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
5776 </literallayout>
5777 The <filename>PACKAGECONFIG</filename>
5778 variable itself specifies a space-separated list of the
5779 features to enable.
5780 Following the features, you can determine the behavior of
5781 each feature by providing up to four order-dependent
5782 arguments, which are separated by commas.
5783 You can omit any argument you like but must retain the
5784 separating commas.
5785 The order is important and specifies the following:
5786 <orderedlist>
5787 <listitem><para>Extra arguments
5788 that should be added to the configure script
5789 argument list
5790 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
5791 if the feature is enabled.</para></listitem>
5792 <listitem><para>Extra arguments
5793 that should be added to <filename>EXTRA_OECONF</filename>
5794 if the feature is disabled.
5795 </para></listitem>
5796 <listitem><para>Additional build dependencies
5797 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
5798 that should be added if the feature is enabled.
5799 </para></listitem>
5800 <listitem><para>Additional runtime dependencies
5801 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5802 that should be added if the feature is enabled.
5803 </para></listitem>
5804 </orderedlist>
5805 </para>
5806
5807 <para>
5808 Consider the following
5809 <filename>PACKAGECONFIG</filename> block taken from the
5810 <filename>librsvg</filename> recipe.
5811 In this example the feature is <filename>croco</filename>,
5812 which has three arguments that determine the feature's
5813 behavior.
5814 <literallayout class='monospaced'>
5815 PACKAGECONFIG ??= "croco"
5816 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
5817 </literallayout>
5818 The <filename>--with-croco</filename> and
5819 <filename>libcroco</filename> arguments apply only if
5820 the feature is enabled.
5821 In this case, <filename>--with-croco</filename> is
5822 added to the configure script argument list and
5823 <filename>libcroco</filename> is added to
5824 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
5825 On the other hand, if the feature is disabled say through
5826 a <filename>.bbappend</filename> file in another layer, then
5827 the second argument <filename>--without-croco</filename> is
5828 added to the configure script rather than
5829 <filename>--with-croco</filename>.
5830 </para>
5831
5832 <para>
5833 The basic <filename>PACKAGECONFIG</filename> structure
5834 previously described holds true regardless of whether you
5835 are creating a block or changing a block.
5836 When creating a block, use the structure inside your
5837 recipe.
5838 </para>
5839
5840 <para>
5841 If you want to change an existing
5842 <filename>PACKAGECONFIG</filename> block, you can do so
5843 one of two ways:
5844 <itemizedlist>
5845 <listitem><para><emphasis>Append file:</emphasis>
5846 Create an append file named
5847 <filename>&lt;recipename&gt;.bbappend</filename> in your
5848 layer and override the value of
5849 <filename>PACKAGECONFIG</filename>.
5850 You can either completely override the variable:
5851 <literallayout class='monospaced'>
5852 PACKAGECONFIG="f4 f5"
5853 </literallayout>
5854 Or, you can just append the variable:
5855 <literallayout class='monospaced'>
5856 PACKAGECONFIG_append = " f4"
5857 </literallayout></para></listitem>
5858 <listitem><para><emphasis>Configuration file:</emphasis>
5859 This method is identical to changing the block
5860 through an append file except you edit your
5861 <filename>local.conf</filename> or
5862 <filename>&lt;mydistro&gt;.conf</filename> file.
5863 As with append files previously described,
5864 you can either completely override the variable:
5865 <literallayout class='monospaced'>
5866 PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
5867 </literallayout>
5868 Or, you can just amend the variable:
5869 <literallayout class='monospaced'>
5870 PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
5871 </literallayout></para></listitem>
5872 </itemizedlist>
5873 </para>
5874 </glossdef>
5875 </glossentry>
5876
5877 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
5878 <glossdef>
5879 <para>The list of packages to be created from the recipe.
5880 The default value is the following:
5881 <literallayout class='monospaced'>
5882 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
5883 </literallayout></para>
5884 </glossdef>
5885 </glossentry>
5886
5887 <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
5888 <glossdef>
5889 <para>
5890 Specifies a list of functions run to perform additional
5891 splitting of files into individual packages.
5892 Recipes can either prepend to this variable or prepend
5893 to the <filename>populate_packages</filename> function
5894 in order to perform additional package splitting.
5895 In either case, the function should set
5896 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
5897 <link linkend='var-FILES'><filename>FILES</filename></link>,
5898 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5899 and other packaging variables appropriately in order to
5900 perform the desired splitting.
5901 </para>
5902 </glossdef>
5903 </glossentry>
5904
5905 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
5906 <glossdef>
5907 <para>
5908 A promise that your recipe satisfies runtime dependencies
5909 for optional modules that are found in other recipes.
5910 <filename>PACKAGES_DYNAMIC</filename>
5911 does not actually satisfy the dependencies, it only states that
5912 they should be satisfied.
5913 For example, if a hard, runtime dependency
5914 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5915 of another package is satisfied
5916 at build time through the <filename>PACKAGES_DYNAMIC</filename>
5917 variable, but a package with the module name is never actually
5918 produced, then the other package will be broken.
5919 Thus, if you attempt to include that package in an image,
5920 you will get a dependency failure from the packaging system
5921 during the
5922 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
5923 task.
5924 </para>
5925 <para>
5926 Typically, if there is a chance that such a situation can
5927 occur and the package that is not created is valid
5928 without the dependency being satisfied, then you should use
5929 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
5930 (a soft runtime dependency) instead of
5931 <filename>RDEPENDS</filename>.
5932 </para>
5933
5934 <para>
5935 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
5936 variable when you are splitting packages, see the
5937 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
5938 in the Yocto Project Development Manual.
5939 </para>
5940 </glossdef>
5941 </glossentry>
5942
5943 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
5944 <glossdef>
5945 <para>
5946 Extra options passed to the <filename>make</filename>
5947 command during the
5948 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
5949 task in order to specify parallel compilation on the local
5950 build host.
5951 This variable is usually in the form "-j &lt;x&gt;",
5952 where x represents the maximum number of parallel threads
5953 <filename>make</filename> can run.
5954 </para>
5955
5956 <para>
5957 If your development host supports multiple cores, a good
5958 rule of thumb is to set this variable to twice the number
5959 of cores on the host.
5960 If you do not set <filename>PARALLEL_MAKE</filename>, it
5961 defaults to the number of cores your build system has.
5962 <note>
5963 Individual recipes might clear out this variable if
5964 the software being built has problems running its
5965 <filename>make</filename> process in parallel.
5966 </note>
5967 </para>
5968 </glossdef>
5969 </glossentry>
5970
5971 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
5972 <glossdef>
5973 <para>
5974 Extra options passed to the
5975 <filename>make install</filename> command during the
5976 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
5977 task in order to specify parallel installation.
5978 This variable defaults to the value of
5979 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
5980 <note>
5981 Individual recipes might clear out this variable if
5982 the software being built has problems running its
5983 <filename>make install</filename> process in parallel.
5984 </note>
5985 </para>
5986 </glossdef>
5987 </glossentry>
5988
5989 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
5990 <glossdef>
5991 <para>
5992 Determines the action to take when a patch fails.
5993 You can set this variable to one of two values: "noop" and
5994 "user".
5995 </para>
5996
5997 <para>
5998 The default value of "noop" causes the build to simply fail
5999 when the OpenEmbedded build system cannot successfully
6000 apply a patch.
6001 Setting the value to "user" causes the build system to
6002 launch a shell and places you in the right location so that
6003 you can manually resolve the conflicts.
6004 </para>
6005
6006 <para>
6007 Set this variable in your
6008 <filename>local.conf</filename> file.
6009 </para>
6010 </glossdef>
6011 </glossentry>
6012
6013 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
6014 <glossdef>
6015 <para>
6016 Specifies the utility used to apply patches for a recipe
6017 during the
6018 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
6019 task.
6020 You can specify one of three utilities: "patch", "quilt", or
6021 "git".
6022 The default utility used is "quilt" except for the
6023 quilt-native recipe itself.
6024 Because the quilt tool is not available at the
6025 time quilt-native is being patched, it uses "patch".
6026 </para>
6027
6028 <para>
6029 If you wish to use an alternative patching tool, set the
6030 variable in the recipe using one of the following:
6031 <literallayout class='monospaced'>
6032 PATCHTOOL = "patch"
6033 PATCHTOOL = "quilt"
6034 PATCHTOOL = "git"
6035 </literallayout>
6036 </para>
6037 </glossdef>
6038 </glossentry>
6039
6040 <glossentry id='var-PE'><glossterm>PE</glossterm>
6041 <glossdef>
6042 <para>
6043 The epoch of the recipe.
6044 By default, this variable is unset.
6045 The variable is used to make upgrades possible when the
6046 versioning scheme changes in some backwards incompatible
6047 way.
6048 </para>
6049 </glossdef>
6050 </glossentry>
6051
6052 <glossentry id='var-PF'><glossterm>PF</glossterm>
6053 <glossdef>
6054 <para>Specifies the recipe or package name and includes all version and revision
6055 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
6056 <filename>bash-4.2-r1/</filename>).
6057 This variable is comprised of the following:
6058 <literallayout class='monospaced'>
6059 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
6060 </literallayout></para>
6061 </glossdef>
6062 </glossentry>
6063
6064 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
6065 <glossdef>
6066 <para>
6067 When a recipe inherits the
6068 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
6069 class, this variable identifies packages that contain
6070 the pixbuf loaders used with
6071 <filename>gdk-pixbuf</filename>.
6072 By default, the <filename>pixbufcache</filename> class
6073 assumes that the loaders are in the recipe's main package
6074 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
6075 Use this variable if the loaders you need are in a package
6076 other than that main package.
6077 </para>
6078 </glossdef>
6079 </glossentry>
6080
6081 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
6082 <glossdef>
6083 <para>
6084 The name of the resulting package created by the
6085 OpenEmbedded build system.
6086 <note>
6087 When using the <filename>PKG</filename> variable, you
6088 must use a package name override.
6089 </note>
6090 For example, when the
6091 <link linkend='ref-classes-debian'><filename>debian</filename></link>
6092 class renames the output package, it does so by setting
6093 <filename>PKG_&lt;packagename&gt;</filename>.
6094 </para>
6095 </glossdef>
6096 </glossentry>
6097
6098 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
6099 <glossdef>
6100 <para>
6101 Points to the destination directory for files to be
6102 packaged before they are split into individual packages.
6103 This directory defaults to the following:
6104 <literallayout class='monospaced'>
6105 ${WORKDIR}/package
6106 </literallayout>
6107 Do not change this default.
6108 </para>
6109 </glossdef>
6110 </glossentry>
6111
6112 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
6113 <glossdef>
6114 <para>
6115 Points to a shared, global-state directory that holds data
6116 generated during the packaging process.
6117 During the packaging process, the
6118 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
6119 task packages data for each recipe and installs it into
6120 this temporary, shared area.
6121 This directory defaults to the following:
6122 <literallayout class='monospaced'>
6123 ${STAGING_DIR_HOST}/pkgdata
6124 </literallayout>
6125 Do not change this default.
6126 </para>
6127 </glossdef>
6128 </glossentry>
6129
6130 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
6131 <glossdef>
6132 <para>
6133 Points to the parent directory for files to be packaged
6134 after they have been split into individual packages.
6135 This directory defaults to the following:
6136 <literallayout class='monospaced'>
6137 ${WORKDIR}/packages-split
6138 </literallayout>
6139 Under this directory, the build system creates
6140 directories for each package specified in
6141 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
6142 Do not change this default.
6143 </para>
6144 </glossdef>
6145 </glossentry>
6146
6147 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
6148 <glossdef>
6149 <para>
6150 Points to a temporary work area used by the
6151 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
6152 task to write output from the
6153 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
6154 task.
6155 The <filename>PKGDESTWORK</filename> location defaults to
6156 the following:
6157 <literallayout class='monospaced'>
6158 ${WORKDIR}/pkgdata
6159 </literallayout>
6160 The <filename>do_packagedata</filename> task then packages
6161 the data in the temporary work area and installs it into a
6162 shared directory pointed to by
6163 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
6164 </para>
6165
6166 <para>
6167 Do not change this default.
6168 </para>
6169 </glossdef>
6170 </glossentry>
6171
6172 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
6173 <glossdef>
6174 <para>
6175 The epoch of the output package built by the
6176 OpenEmbedded build system.
6177 By default, <filename>PKGE</filename> is set to
6178 <link linkend='var-PE'><filename>PE</filename></link>.
6179 </para>
6180 </glossdef>
6181 </glossentry>
6182
6183 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
6184 <glossdef>
6185 <para>
6186 The revision of the output package built by the
6187 OpenEmbedded build system.
6188 By default, <filename>PKGR</filename> is set to
6189 <link linkend='var-PR'><filename>PR</filename></link>.
6190 </para>
6191 </glossdef>
6192 </glossentry>
6193
6194 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
6195 <glossdef>
6196 <para>
6197 The version of the output package built by the
6198 OpenEmbedded build system.
6199 By default, <filename>PKGV</filename> is set to
6200 <link linkend='var-PV'><filename>PV</filename></link>.
6201 </para>
6202 </glossdef>
6203 </glossentry>
6204
6205 <glossentry id='var-PN'><glossterm>PN</glossterm>
6206 <glossdef>
6207 <para>This variable can have two separate functions depending on the context: a recipe
6208 name or a resulting package name.</para>
6209 <para><filename>PN</filename> refers to a recipe name in the context of a file used
6210 by the OpenEmbedded build system as input to create a package.
6211 The name is normally extracted from the recipe file name.
6212 For example, if the recipe is named
6213 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
6214 will be "expat".</para>
6215 <para>
6216 The variable refers to a package name in the context of a file created or produced by the
6217 OpenEmbedded build system.</para>
6218 <para>If applicable, the <filename>PN</filename> variable also contains any special
6219 suffix or prefix.
6220 For example, using <filename>bash</filename> to build packages for the native
6221 machine, <filename>PN</filename> is <filename>bash-native</filename>.
6222 Using <filename>bash</filename> to build packages for the target and for Multilib,
6223 <filename>PN</filename> would be <filename>bash</filename> and
6224 <filename>lib64-bash</filename>, respectively.
6225 </para>
6226 </glossdef>
6227 </glossentry>
6228
6229 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
6230 <glossdef>
6231 <para>
6232 Lists recipes you do not want the OpenEmbedded build system
6233 to build.
6234 This variable works in conjunction with the
6235 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
6236 class, which the recipe must inherit globally.
6237 </para>
6238
6239 <para>
6240 To prevent a recipe from being built, inherit the class
6241 globally and use the variable in your
6242 <filename>local.conf</filename> file.
6243 Here is an example that prevents
6244 <filename>myrecipe</filename> from being built:
6245 <literallayout class='monospaced'>
6246 INHERIT += "blacklist"
6247 PNBLACKLIST[myrecipe] = "Not supported by our organization."
6248 </literallayout>
6249 </para>
6250 </glossdef>
6251 </glossentry>
6252
6253 <glossentry id='var-PR'><glossterm>PR</glossterm>
6254 <glossdef>
6255 <para>
6256 The revision of the recipe.
6257 The default value for this variable is "r0".
6258 </para>
6259 </glossdef>
6260 </glossentry>
6261
6262 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
6263 <glossdef>
6264 <para>
6265 If multiple recipes provide an item, this variable
6266 determines which recipe should be given preference.
6267 You should always suffix the variable with the name of the
6268 provided item, and you should set it to the
6269 <link linkend='var-PN'><filename>PN</filename></link>
6270 of the recipe to which you want to give precedence.
6271 Some examples:
6272 <literallayout class='monospaced'>
6273 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
6274 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
6275 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
6276 </literallayout>
6277 </para>
6278 </glossdef>
6279 </glossentry>
6280
6281 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
6282 <glossdef>
6283 <para>
6284 If there are multiple versions of recipes available, this
6285 variable determines which recipe should be given preference.
6286 You must always suffix the variable with the
6287 <link linkend='var-PN'><filename>PN</filename></link>
6288 you want to select, and you should set the
6289 <link linkend='var-PV'><filename>PV</filename></link>
6290 accordingly for precedence.
6291 You can use the "<filename>%</filename>" character as a
6292 wildcard to match any number of characters, which can be
6293 useful when specifying versions that contain long revision
6294 numbers that could potentially change.
6295 Here are two examples:
6296 <literallayout class='monospaced'>
6297 PREFERRED_VERSION_python = "2.7.3"
6298 PREFERRED_VERSION_linux-yocto = "3.10%"
6299 </literallayout>
6300 </para>
6301 </glossdef>
6302 </glossentry>
6303
6304 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
6305 <glossdef>
6306 <para>
6307 Specifies additional paths from which the OpenEmbedded
6308 build system gets source code.
6309 When the build system searches for source code, it first
6310 tries the local download directory.
6311 If that location fails, the build system tries locations
6312 defined by <filename>PREMIRRORS</filename>, the upstream
6313 source, and then locations specified by
6314 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
6315 in that order.
6316 </para>
6317
6318 <para>
6319 Assuming your distribution
6320 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
6321 is "poky", the default value for
6322 <filename>PREMIRRORS</filename> is defined in the
6323 <filename>conf/distro/poky.conf</filename> file in the
6324 <filename>meta-yocto</filename> Git repository.
6325 </para>
6326
6327 <para>
6328 Typically, you could add a specific server for the
6329 build system to attempt before any others by adding
6330 something like the following to the
6331 <filename>local.conf</filename> configuration file in the
6332 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
6333 <literallayout class='monospaced'>
6334 PREMIRRORS_prepend = "\
6335 git://.*/.* http://www.yoctoproject.org/sources/ \n \
6336 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
6337 http://.*/.* http://www.yoctoproject.org/sources/ \n \
6338 https://.*/.* http://www.yoctoproject.org/sources/ \n"
6339 </literallayout>
6340 These changes cause the build system to intercept
6341 Git, FTP, HTTP, and HTTPS requests and direct them to
6342 the <filename>http://</filename> sources mirror.
6343 You can use <filename>file://</filename> URLs to point
6344 to local directories or network shares as well.
6345 </para>
6346 </glossdef>
6347 </glossentry>
6348
6349 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
6350 <glossdef>
6351
6352 <para>
6353 The <filename>PRINC</filename> variable has been deprecated
6354 and triggers a warning if detected during a build.
6355 For
6356 <link linkend='var-PR'><filename>PR</filename></link>
6357 increments on changes, use the PR service instead.
6358 You can find out more about this service in the
6359 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
6360 section in the Yocto Project Development Manual.
6361 </para>
6362<!--
6363
6364 <para>
6365 Causes the
6366 <link linkend='var-PR'><filename>PR</filename></link>
6367 variable of <filename>.bbappend</filename> files to
6368 dynamically increment.
6369 This increment minimizes the impact of layer ordering.
6370 </para>
6371
6372 <para>
6373 In order to ensure multiple <filename>.bbappend</filename>
6374 files can co-exist,
6375 <filename>PRINC</filename> should be self-referencing.
6376 This variable defaults to 0.
6377 </para>
6378
6379 <para>
6380 Following is an example that increments
6381 <filename>PR</filename> by two:
6382 <literallayout class='monospaced'>
6383 PRINC := "${@int(PRINC) + 2}"
6384 </literallayout>
6385 It is advisable not to use strings such as ".= '.1'" with the variable because
6386 this usage is very sensitive to layer ordering.
6387 You should avoid explicit assignments as they cannot
6388 adequately represent multiple
6389 <filename>.bbappend</filename> files.
6390 </para>
6391-->
6392 </glossdef>
6393 </glossentry>
6394
6395 <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
6396 <glossdef>
6397 <para>
6398 Specifies libraries installed within a recipe that
6399 should be ignored by the OpenEmbedded build system's
6400 shared library resolver.
6401 This variable is typically used when software being
6402 built by a recipe has its own private versions of a
6403 library normally provided by another recipe.
6404 In this case, you would not want the package containing
6405 the private libraries to be set as a dependency on other
6406 unrelated packages that should instead depend on the
6407 package providing the standard version of the library.
6408 </para>
6409
6410 <para>
6411 Libraries specified in this variable should be specified
6412 by their file name.
6413 For example, from the Firefox recipe in meta-browser:
6414 <literallayout class='monospaced'>
6415 PRIVATE_LIBS = "libmozjs.so \
6416 libxpcom.so \
6417 libnspr4.so \
6418 libxul.so \
6419 libmozalloc.so \
6420 libplc4.so \
6421 libplds4.so"
6422 </literallayout>
6423 </para>
6424 </glossdef>
6425 </glossentry>
6426
6427 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
6428 <glossdef>
6429 <para>
6430 A list of aliases by which a particular recipe can be
6431 known.
6432 By default, a recipe's own
6433 <filename><link linkend='var-PN'>PN</link></filename>
6434 is implicitly already in its <filename>PROVIDES</filename>
6435 list.
6436 If a recipe uses <filename>PROVIDES</filename>, the
6437 additional aliases are synonyms for the recipe and can
6438 be useful satisfying dependencies of other recipes during
6439 the build as specified by
6440 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
6441 </para>
6442
6443 <para>
6444 Consider the following example
6445 <filename>PROVIDES</filename> statement from a recipe
6446 file <filename>libav_0.8.11.bb</filename>:
6447 <literallayout class='monospaced'>
6448 PROVIDES += "libpostproc"
6449 </literallayout>
6450 The <filename>PROVIDES</filename> statement results in
6451 the "libav" recipe also being known as "libpostproc".
6452 </para>
6453 </glossdef>
6454 </glossentry>
6455
6456 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
6457 <glossdef>
6458 <para>
6459 The network based
6460 <link linkend='var-PR'><filename>PR</filename></link>
6461 service host and port.
6462 </para>
6463
6464 <para>
6465 The <filename>conf/local.conf.sample.extended</filename>
6466 configuration file in the
6467 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
6468 shows how the <filename>PRSERV_HOST</filename> variable is
6469 set:
6470 <literallayout class='monospaced'>
6471 PRSERV_HOST = "localhost:0"
6472 </literallayout>
6473 You must set the variable if you want to automatically
6474 start a local
6475 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
6476 You can set <filename>PRSERV_HOST</filename> to other
6477 values to use a remote PR service.
6478 </para>
6479 </glossdef>
6480 </glossentry>
6481
6482 <glossentry id='var-PV'><glossterm>PV</glossterm>
6483 <glossdef>
6484 <para>
6485 The version of the recipe.
6486 The version is normally extracted from the recipe filename.
6487 For example, if the recipe is named
6488 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
6489 will be "2.0.1".
6490 <filename>PV</filename> is generally not overridden within
6491 a recipe unless it is building an unstable (i.e. development) version from a source code repository
6492 (e.g. Git or Subversion).
6493 </para>
6494 </glossdef>
6495 </glossentry>
6496
6497 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
6498 <glossdef>
6499 <para>
6500 When used by recipes that inherit the
6501 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
6502 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
6503 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
6504 or
6505 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
6506 classes, denotes the Application Binary Interface (ABI)
6507 currently in use for Python.
6508 By default, the ABI is "m".
6509 You do not have to set this variable as the OpenEmbedded
6510 build system sets it for you.
6511 </para>
6512
6513 <para>
6514 The OpenEmbedded build system uses the ABI to construct
6515 directory names used when installing the Python headers
6516 and libraries in sysroot
6517 (e.g. <filename>.../python3.3m/...</filename>).
6518 </para>
6519
6520 <para>
6521 Recipes that inherit the
6522 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
6523 class during cross-builds also use this variable to
6524 locate the headers and libraries of the appropriate Python
6525 that the extension is targeting.
6526 </para>
6527 </glossdef>
6528 </glossentry>
6529
6530 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
6531 <glossdef>
6532 <para>
6533 When used by recipes that inherit the
6534 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
6535 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
6536 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
6537 or
6538 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
6539 classes, specifies the major Python version being built.
6540 For Python 2.x, <filename>PYTHON_PN</filename> would
6541 be "python2". For Python 3.x, the variable would be
6542 "python3".
6543 You do not have to set this variable as the
6544 OpenEmbedded build system automatically sets it for you.
6545 </para>
6546
6547 <para>
6548 The variable allows recipes to use common infrastructure
6549 such as the following:
6550 <literallayout class='monospaced'>
6551 DEPENDS += "${PYTHON_PN}-native"
6552 </literallayout>
6553 In the previous example, the version of the dependency
6554 is <filename>PYTHON_PN</filename>.
6555 </para>
6556 </glossdef>
6557 </glossentry>
6558
6559 </glossdiv>
6560
6561 <glossdiv id='var-glossary-q'><title>Q</title>
6562
6563 <glossentry id='var-QMAKE_PROFILES'><glossterm>QMAKE_PROFILES</glossterm>
6564 <glossdef>
6565 <para>
6566 Specifies your own subset of <filename>.pro</filename>
6567 files to be built for use with
6568 <filename>qmake</filename>.
6569 If you do not set this variable, all
6570 <filename>.pro</filename> files in the directory pointed to
6571 by <link linkend='var-S'><filename>S</filename></link>
6572 will be built by default.
6573 </para>
6574
6575 <para>
6576 This variable is used with recipes that inherit the
6577 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
6578 class or other classes that inherit
6579 <filename>qmake_base</filename>.
6580 </para>
6581 </glossdef>
6582 </glossentry>
6583
6584 </glossdiv>
6585
6586 <glossdiv id='var-glossary-r'><title>R</title>
6587
6588 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
6589 <glossdef>
6590 <para>
6591 The list of packages that conflict with packages.
6592 Note that packages will not be installed if conflicting
6593 packages are not first removed.
6594 </para>
6595
6596 <para>
6597 Like all package-controlling variables, you must always use
6598 them in conjunction with a package name override.
6599 Here is an example:
6600 <literallayout class='monospaced'>
6601 RCONFLICTS_${PN} = "another-conflicting-package-name"
6602 </literallayout>
6603 </para>
6604
6605 <para>
6606 BitBake, which the OpenEmbedded build system uses, supports
6607 specifying versioned dependencies.
6608 Although the syntax varies depending on the packaging
6609 format, BitBake hides these differences from you.
6610 Here is the general syntax to specify versions with
6611 the <filename>RCONFLICTS</filename> variable:
6612 <literallayout class='monospaced'>
6613 RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6614 </literallayout>
6615 For <filename>operator</filename>, you can specify the
6616 following:
6617 <literallayout class='monospaced'>
6618 =
6619 &lt;
6620 &gt;
6621 &lt;=
6622 &gt;=
6623 </literallayout>
6624 For example, the following sets up a dependency on version
6625 1.2 or greater of the package <filename>foo</filename>:
6626 <literallayout class='monospaced'>
6627 RCONFLICTS_${PN} = "foo (>= 1.2)"
6628 </literallayout>
6629 </para>
6630 </glossdef>
6631 </glossentry>
6632
6633 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
6634 <glossdef>
6635 <para>
6636 Lists a package's runtime dependencies (i.e. other packages)
6637 that must be installed in order for the built package to run
6638 correctly.
6639 If a package in this list cannot be found during the build,
6640 you will get a build error.
6641 </para>
6642
6643 <para>
6644 When you use the <filename>RDEPENDS</filename> variable
6645 in a recipe, you are essentially stating that the recipe's
6646 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
6647 task depends on the existence of a specific package.
6648 Consider this simple example for two recipes named "a" and
6649 "b" that produce similarly named IPK packages.
6650 In this example, the <filename>RDEPENDS</filename>
6651 statement appears in the "a" recipe:
6652 <literallayout class='monospaced'>
6653 RDEPENDS_${PN} = "b"
6654 </literallayout>
6655 Here, the dependency is such that the
6656 <filename>do_build</filename> task for recipe "a" depends
6657 on the
6658 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
6659 task of recipe "b".
6660 This means the package file for "b" must be available when
6661 the output for recipe "a" has been completely built.
6662 More importantly, package "a" will be marked as depending
6663 on package "b" in a manner that is understood by the
6664 package manager.
6665 </para>
6666
6667 <para>
6668 The names of the packages you list within
6669 <filename>RDEPENDS</filename> must be the names of other
6670 packages - they cannot be recipe names.
6671 Although package names and recipe names usually match,
6672 the important point here is that you are
6673 providing package names within the
6674 <filename>RDEPENDS</filename> variable.
6675 For an example of the default list of packages created from
6676 a recipe, see the
6677 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
6678 variable.
6679 </para>
6680
6681 <para>
6682 Because the <filename>RDEPENDS</filename> variable applies
6683 to packages being built, you should always use the variable
6684 in a form with an attached package name.
6685 For example, suppose you are building a development package
6686 that depends on the <filename>perl</filename> package.
6687 In this case, you would use the following
6688 <filename>RDEPENDS</filename> statement:
6689 <literallayout class='monospaced'>
6690 RDEPENDS_${PN}-dev += "perl"
6691 </literallayout>
6692 In the example, the development package depends on
6693 the <filename>perl</filename> package.
6694 Thus, the <filename>RDEPENDS</filename> variable has the
6695 <filename>${PN}-dev</filename> package name as part of the
6696 variable.
6697 </para>
6698
6699 <para>
6700 The package name you attach to the
6701 <filename>RDEPENDS</filename> variable must appear
6702 as it would in the <filename>PACKAGES</filename>
6703 namespace before any renaming of the output package by
6704 classes like
6705 <link linkend='ref-classes-debian'><filename>debian.bbclass</filename></link>.
6706 </para>
6707
6708 <para>
6709 In many cases you do not need to explicitly add
6710 runtime dependencies using
6711 <filename>RDEPENDS</filename> since some automatic
6712 handling occurs:
6713 <itemizedlist>
6714 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
6715 a runtime package contains a shared library
6716 (<filename>.so</filename>), the build
6717 processes the library in order to determine other
6718 libraries to which it is dynamically linked.
6719 The build process adds these libraries to
6720 <filename>RDEPENDS</filename> when creating the runtime
6721 package.</para></listitem>
6722 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
6723 the package ships a <filename>pkg-config</filename>
6724 information file, the build process uses this file
6725 to add items to the <filename>RDEPENDS</filename>
6726 variable to create the runtime packages.
6727 </para></listitem>
6728 </itemizedlist>
6729 </para>
6730
6731 <para>
6732 BitBake, which the OpenEmbedded build system uses, supports
6733 specifying versioned dependencies.
6734 Although the syntax varies depending on the packaging
6735 format, BitBake hides these differences from you.
6736 Here is the general syntax to specify versions with
6737 the <filename>RDEPENDS</filename> variable:
6738 <literallayout class='monospaced'>
6739 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6740 </literallayout>
6741 For <filename>operator</filename>, you can specify the
6742 following:
6743 <literallayout class='monospaced'>
6744 =
6745 &lt;
6746 &gt;
6747 &lt;=
6748 &gt;=
6749 </literallayout>
6750 For example, the following sets up a dependency on version
6751 1.2 or greater of the package <filename>foo</filename>:
6752 <literallayout class='monospaced'>
6753 RDEPENDS_${PN} = "foo (>= 1.2)"
6754 </literallayout>
6755 </para>
6756
6757 <para>
6758 For information on build-time dependencies, see the
6759 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
6760 variable.
6761 </para>
6762 </glossdef>
6763 </glossentry>
6764
6765 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
6766 <glossdef>
6767 <para>
6768 When a recipe inherits the
6769 <filename>distro_features_check</filename> class, this
6770 variable identifies distribution features that must
6771 exist in the current configuration in order for the
6772 OpenEmbedded build system to build the recipe.
6773 In other words, if the
6774 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
6775 lists a feature that does not appear in
6776 <filename>DISTRO_FEATURES</filename> within the
6777 current configuration, an error occurs and the
6778 build stops.
6779 </para>
6780 </glossdef>
6781 </glossentry>
6782
6783 <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
6784 <glossdef>
6785 <para>
6786 Reclaims disk space by removing previously built
6787 versions of the same image from the
6788 <filename>images</filename> directory pointed to by the
6789 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
6790 variable.
6791 </para>
6792
6793 <para>
6794 Set this variable to "1" in your
6795 <filename>local.conf</filename> file to remove these
6796 images.
6797 </para>
6798 </glossdef>
6799 </glossentry>
6800
6801 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
6802 <glossdef>
6803 <para>
6804 With <filename>rm_work</filename> enabled, this
6805 variable specifies a list of recipes whose work directories
6806 should not be removed.
6807 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
6808 section for more details.
6809 </para>
6810 </glossdef>
6811 </glossentry>
6812
6813 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
6814 <glossdef>
6815 <para>
6816 Defines the root home directory.
6817 By default, this directory is set as follows in the
6818 BitBake configuration file:
6819 <literallayout class='monospaced'>
6820 ROOT_HOME ??= "/home/root"
6821 </literallayout>
6822 <note>
6823 This default value is likely used because some
6824 embedded solutions prefer to have a read-only root
6825 filesystem and prefer to keep writeable data in one
6826 place.
6827 </note>
6828 </para>
6829
6830 <para>
6831 You can override the default by setting the variable
6832 in any layer or in the <filename>local.conf</filename> file.
6833 Because the default is set using a "weak" assignment
6834 (i.e. "??="), you can use either of the following forms
6835 to define your override:
6836 <literallayout class='monospaced'>
6837 ROOT_HOME = "/root"
6838 ROOT_HOME ?= "/root"
6839 </literallayout>
6840 These override examples use <filename>/root</filename>,
6841 which is probably the most commonly used override.
6842 </para>
6843 </glossdef>
6844 </glossentry>
6845
6846 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
6847 <glossdef>
6848 <para>
6849 Indicates a filesystem image to include as the root
6850 filesystem.
6851 </para>
6852
6853 <para>
6854 The <filename>ROOTFS</filename> variable is an optional
6855 variable used with the
6856 <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link>
6857 class.
6858 </para>
6859 </glossdef>
6860 </glossentry>
6861
6862 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
6863 <glossdef>
6864 <para>
6865 Added by classes to run post processing commands once the
6866 OpenEmbedded build system has created the root filesystem.
6867 You can specify shell commands separated by semicolons:
6868 <literallayout class='monospaced'>
6869 ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
6870 </literallayout>
6871 If you need to pass the path to the root filesystem within
6872 the command, you can use
6873 <filename>${IMAGE_ROOTFS}</filename>, which points to
6874 the root filesystem image.
6875 See the
6876 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6877 variable for more information.
6878 </para>
6879 </glossdef>
6880 </glossentry>
6881
6882 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
6883 <glossdef>
6884 <para>
6885 A list of package name aliases that a package also provides.
6886 These aliases are useful for satisfying runtime dependencies
6887 of other packages both during the build and on the target
6888 (as specified by
6889 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
6890 <note>
6891 A package's own name is implicitly already in its
6892 <filename>RPROVIDES</filename> list.
6893 </note>
6894 </para>
6895 <para>
6896 As with all package-controlling variables, you must always
6897 use the variable in conjunction with a package name override.
6898 Here is an example:
6899 <literallayout class='monospaced'>
6900 RPROVIDES_${PN} = "widget-abi-2"
6901 </literallayout>
6902 </para>
6903 </glossdef>
6904 </glossentry>
6905
6906 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
6907 <glossdef>
6908 <para>
6909 A list of packages that extends the usability of a package
6910 being built.
6911 The package being built does not depend on this list of
6912 packages in order to successfully build, but needs them for
6913 the extended usability.
6914 To specify runtime dependencies for packages, see the
6915 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
6916 variable.
6917 </para>
6918
6919 <para>
6920 The OpenEmbedded build process automatically installs the
6921 list of packages as part of the built package.
6922 However, you can remove these packages later if you want.
6923 If, during the build, a package from the
6924 <filename>RRECOMMENDS</filename> list cannot be
6925 found, the build process continues without an error.
6926 </para>
6927
6928 <para>
6929 You can also prevent packages in the list from being
6930 installed by using several variables.
6931 See the
6932 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
6933 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
6934 and
6935 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
6936 variables for more information.
6937 </para>
6938
6939 <para>
6940 Because the <filename>RRECOMMENDS</filename> variable
6941 applies to packages being built, you should always attach
6942 an override to the variable to specify the particular
6943 package whose usability is being extended.
6944 For example, suppose you are building a development package
6945 that is extended to support wireless functionality.
6946 In this case, you would use the following:
6947 <literallayout class='monospaced'>
6948 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
6949 </literallayout>
6950 In the example, the package name
6951 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
6952 must appear as it would in the
6953 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
6954 namespace before any renaming of the output package by
6955 classes such as <filename>debian.bbclass</filename>.
6956 </para>
6957
6958 <para>
6959 BitBake, which the OpenEmbedded build system uses, supports
6960 specifying versioned recommends.
6961 Although the syntax varies depending on the packaging
6962 format, BitBake hides these differences from you.
6963 Here is the general syntax to specify versions with
6964 the <filename>RRECOMMENDS</filename> variable:
6965 <literallayout class='monospaced'>
6966 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6967 </literallayout>
6968 For <filename>operator</filename>, you can specify the
6969 following:
6970 <literallayout class='monospaced'>
6971 =
6972 &lt;
6973 &gt;
6974 &lt;=
6975 &gt;=
6976 </literallayout>
6977 For example, the following sets up a recommend on version
6978 1.2 or greater of the package <filename>foo</filename>:
6979 <literallayout class='monospaced'>
6980 RRECOMMENDS_${PN} = "foo (>= 1.2)"
6981 </literallayout>
6982 </para>
6983 </glossdef>
6984 </glossentry>
6985
6986 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
6987 <glossdef>
6988 <para>
6989 A list of packages replaced by a package.
6990 The package manager uses this variable to determine which
6991 package should be installed to replace other package(s)
6992 during an upgrade.
6993 In order to also have the other package(s) removed at the
6994 same time, you must add the name of the other
6995 package to the
6996 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
6997 </para>
6998 <para>
6999 As with all package-controlling variables, you must use
7000 this variable in conjunction with a package name
7001 override.
7002 Here is an example:
7003 <literallayout class='monospaced'>
7004 RREPLACES_${PN} = "other-package-being-replaced"
7005 </literallayout>
7006 </para>
7007
7008 <para>
7009 BitBake, which the OpenEmbedded build system uses, supports
7010 specifying versioned replacements.
7011 Although the syntax varies depending on the packaging
7012 format, BitBake hides these differences from you.
7013 Here is the general syntax to specify versions with
7014 the <filename>RREPLACES</filename> variable:
7015 <literallayout class='monospaced'>
7016 RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
7017 </literallayout>
7018 For <filename>operator</filename>, you can specify the
7019 following:
7020 <literallayout class='monospaced'>
7021 =
7022 &lt;
7023 &gt;
7024 &lt;=
7025 &gt;=
7026 </literallayout>
7027 For example, the following sets up a replacement using
7028 version 1.2 or greater of the package
7029 <filename>foo</filename>:
7030 <literallayout class='monospaced'>
7031 RREPLACES_${PN} = "foo (>= 1.2)"
7032 </literallayout>
7033 </para>
7034 </glossdef>
7035 </glossentry>
7036
7037 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
7038 <glossdef>
7039 <para>
7040 A list of additional packages that you can suggest for
7041 installation by the package manager at the time a package
7042 is installed.
7043 Not all package managers support this functionality.
7044 </para>
7045 <para>
7046 As with all package-controlling variables, you must always
7047 use this variable in conjunction with a package name
7048 override.
7049 Here is an example:
7050 <literallayout class='monospaced'>
7051 RSUGGESTS_${PN} = "useful-package another-package"
7052 </literallayout>
7053 </para>
7054 </glossdef>
7055 </glossentry>
7056
7057 </glossdiv>
7058
7059 <glossdiv id='var-glossary-s'><title>S</title>
7060
7061 <glossentry id='var-S'><glossterm>S</glossterm>
7062 <glossdef>
7063 <para>
7064 The location in the
7065 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
7066 where unpacked recipe source code resides.
7067 This location is within the work directory
7068 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
7069 which is not static.
7070 The unpacked source location depends on the recipe name
7071 (<filename><link linkend='var-PN'>PN</link></filename>) and
7072 recipe version
7073 (<filename><link linkend='var-PV'>PV</link></filename>) as
7074 follows:
7075 <literallayout class='monospaced'>
7076 ${WORKDIR}/${PN}-${PV}
7077 </literallayout>
7078 As an example, assume a
7079 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
7080 top-level folder named <filename>poky</filename> and a
7081 default Build Directory at <filename>poky/build</filename>.
7082 In this case, the work directory the build system uses
7083 to keep the unpacked recipe for <filename>db</filename>
7084 is the following:
7085 <literallayout class='monospaced'>
7086 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
7087 </literallayout>
7088 </para>
7089 </glossdef>
7090 </glossentry>
7091
7092 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
7093 <glossdef>
7094 <para>
7095 A list of the host distribution identifiers that the
7096 build system has been tested against.
7097 Identifiers consist of the host distributor ID
7098 followed by the release,
7099 as reported by the <filename>lsb_release</filename> tool
7100 or as read from <filename>/etc/lsb-release</filename>.
7101 Separate the list items with explicit newline
7102 characters (<filename>\n</filename>).
7103 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
7104 and the current value of
7105 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
7106 does not appear in the list, then the build system reports
7107 a warning that indicates the current host distribution has
7108 not been tested as a build host.
7109 </para>
7110 </glossdef>
7111 </glossentry>
7112
7113 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
7114 <glossdef>
7115 <para>
7116 The target architecture for the SDK.
7117 Typically, you do not directly set this variable.
7118 Instead, use
7119 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
7120 </para>
7121 </glossdef>
7122 </glossentry>
7123
7124 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
7125 <glossdef>
7126 <para>
7127 The directory set up and used by the
7128 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
7129 to which the SDK is deployed.
7130 The <filename>populate_sdk_base</filename> class defines
7131 <filename>SDK_DEPLOY</filename> as follows:
7132 <literallayout class='monospaced'>
7133 SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk"
7134 </literallayout>
7135 </para>
7136 </glossdef>
7137 </glossentry>
7138
7139 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
7140 <glossdef>
7141 <para>
7142 The parent directory used by the OpenEmbedded build system
7143 when creating SDK output.
7144 The
7145 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
7146 class defines the variable as follows:
7147 <literallayout class='monospaced'>
7148 SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"
7149 </literallayout>
7150 <note>
7151 The <filename>SDK_DIR</filename> directory is a
7152 temporary directory as it is part of
7153 <filename>WORKDIR</filename>.
7154 The final output directory is
7155 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
7156 </note>
7157 </para>
7158 </glossdef>
7159 </glossentry>
7160
7161 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
7162 <glossdef>
7163 <para>
7164 The base name for SDK output files.
7165 The name is derived from the
7166 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
7167 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
7168 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
7169 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
7170 and
7171 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
7172 variables:
7173 <literallayout class='monospaced'>
7174 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
7175 </literallayout>
7176 </para>
7177 </glossdef>
7178 </glossentry>
7179
7180 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
7181 <glossdef>
7182 <para>
7183 The location used by the OpenEmbedded build system when
7184 creating SDK output.
7185 The
7186 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
7187 class defines the variable as follows:
7188 <literallayout class='monospaced'>
7189 SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"
7190 </literallayout>
7191 <note>
7192 The <filename>SDK_OUTPUT</filename> directory is a
7193 temporary directory as it is part of
7194 <filename>WORKDIR</filename> by way of
7195 <filename>SDK_DIR</filename>.
7196 The final output directory is
7197 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
7198 </note>
7199
7200 </para>
7201 </glossdef>
7202 </glossentry>
7203
7204 <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
7205 <glossdef>
7206 <para>
7207 Specifies a list of architectures compatible with
7208 the SDK machine.
7209 This variable is set automatically and should not
7210 normally be hand-edited.
7211 Entries are separated using spaces and listed in order
7212 of priority.
7213 The default value for
7214 <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
7215 ${SDK_ARCH}-${SDKPKGSUFFIX}".
7216 </para>
7217 </glossdef>
7218 </glossentry>
7219
7220 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
7221 <glossdef>
7222 <para>Equivalent to
7223 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
7224 However, this variable applies to the SDK generated from an
7225 image using the following command:
7226 <literallayout class='monospaced'>
7227 $ bitbake -c populate_sdk imagename
7228 </literallayout>
7229 </para>
7230 </glossdef>
7231 </glossentry>
7232
7233 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
7234 <glossdef>
7235 <para>
7236 The machine for which the Application Development Toolkit
7237 (ADT) or SDK is built.
7238 In other words, the SDK or ADT is built such that it
7239 runs on the target you specify with the
7240 <filename>SDKMACHINE</filename> value.
7241 The value points to a corresponding
7242 <filename>.conf</filename> file under
7243 <filename>conf/machine-sdk/</filename>.
7244 </para>
7245
7246 <para>
7247 You can use "i686" and "x86_64" as possible values
7248 for this variable. The variable defaults to "i686"
7249 and is set in the local.conf file in the Build Directory.
7250 <literallayout class='monospaced'>
7251 SDKMACHINE ?= "i686"
7252 </literallayout>
7253 <note>
7254 You cannot set the <filename>SDKMACHINE</filename>
7255 variable in your distribution configuration file.
7256 If you do, the configuration will not take affect.
7257 </note>
7258 </para>
7259 </glossdef>
7260 </glossentry>
7261
7262 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
7263 <glossdef>
7264 <para>
7265 Defines the path offered to the user for installation
7266 of the SDK that is generated by the OpenEmbedded build
7267 system.
7268 The path appears as the default location for installing
7269 the SDK when you run the SDK's installation script.
7270 You can override the offered path when you run the
7271 script.
7272 </para>
7273 </glossdef>
7274 </glossentry>
7275
7276 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
7277 <glossdef>
7278 <para>The section in which packages should be categorized.
7279 Package management utilities can make use of this variable.</para>
7280 </glossdef>
7281 </glossentry>
7282
7283 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
7284 <glossdef>
7285 <para>
7286 Specifies the optimization flags passed to the C compiler
7287 when building for the target.
7288 The flags are passed through the default value of the
7289 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
7290 variable.
7291 </para>
7292
7293 <para>
7294 The <filename>SELECTED_OPTIMIZATION</filename> variable
7295 takes the value of
7296 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
7297 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
7298 If that is the case, the value of
7299 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
7300 </para>
7301 </glossdef>
7302 </glossentry>
7303
7304 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
7305 <glossdef>
7306 <para>
7307 Defines a serial console (TTY) to enable using getty.
7308 Provide a value that specifies the baud rate followed by
7309 the TTY device name separated by a space.
7310 You cannot specify more than one TTY device:
7311 <literallayout class='monospaced'>
7312 SERIAL_CONSOLE = "115200 ttyS0"
7313 </literallayout>
7314 <note>
7315 The <filename>SERIAL_CONSOLE</filename> variable
7316 is deprecated.
7317 Please use the
7318 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
7319 variable.
7320 </note>
7321 </para>
7322 </glossdef>
7323 </glossentry>
7324
7325 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
7326 <glossdef>
7327 <para>
7328 Defines the serial consoles (TTYs) to enable using getty.
7329 Provide a value that specifies the baud rate followed by
7330 the TTY device name separated by a semicolon.
7331 Use spaces to separate multiple devices:
7332 <literallayout class='monospaced'>
7333 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
7334 </literallayout>
7335 </para>
7336 </glossdef>
7337 </glossentry>
7338
7339 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
7340 <glossdef>
7341 <para>
7342 Similar to
7343 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
7344 except the device is checked for existence before attempting
7345 to enable it.
7346 This variable is currently only supported with SysVinit
7347 (i.e. not with systemd).
7348 </para>
7349 </glossdef>
7350 </glossentry>
7351
7352 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
7353 <glossdef>
7354 <para>
7355 A list of recipe dependencies that should not be used to
7356 determine signatures of tasks from one recipe when they
7357 depend on tasks from another recipe.
7358 For example:
7359 <literallayout class='monospaced'>
7360 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
7361 </literallayout>
7362 In this example, <filename>intone</filename> depends on
7363 <filename>mplayer2</filename>.
7364 </para>
7365
7366 <para>
7367 Use of this variable is one mechanism to remove dependencies
7368 that affect task signatures and thus force rebuilds when a
7369 recipe changes.
7370 <note><title>Caution</title>
7371 If you add an inappropriate dependency for a recipe
7372 relationship, the software might break during
7373 runtime if the interface of the second recipe was
7374 changed after the first recipe had been built.
7375 </note>
7376 </para>
7377 </glossdef>
7378 </glossentry>
7379
7380 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
7381 <glossdef>
7382 <para>
7383 A list of recipes that are completely stable and will
7384 never change.
7385 The ABI for the recipes in the list are presented by
7386 output from the tasks run to build the recipe.
7387 Use of this variable is one way to remove dependencies from
7388 one recipe on another that affect task signatures and
7389 thus force rebuilds when the recipe changes.
7390 <note><title>Caution</title>
7391 If you add an inappropriate variable to this list,
7392 the software might break at runtime if the
7393 interface of the recipe was changed after the other
7394 had been built.
7395 </note>
7396 </para>
7397 </glossdef>
7398 </glossentry>
7399
7400 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
7401 <glossdef>
7402 <para>
7403 Specifies the number of bits for the target system CPU.
7404 The value should be either "32" or "64".
7405 </para>
7406 </glossdef>
7407 </glossentry>
7408
7409 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
7410 <glossdef>
7411 <para>
7412 Specifies the endian byte order of the target system.
7413 The value should be either "le" for little-endian or "be" for big-endian.
7414 </para>
7415 </glossdef>
7416 </glossentry>
7417
7418 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
7419 <glossdef>
7420 <para>
7421 Groups together machines based upon the same family
7422 of SOC (System On Chip).
7423 You typically set this variable in a common
7424 <filename>.inc</filename> file that you include in the
7425 configuration files of all the machines.
7426 <note>
7427 You must include
7428 <filename>conf/machine/include/soc-family.inc</filename>
7429 for this variable to appear in
7430 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
7431 </note>
7432 </para>
7433 </glossdef>
7434 </glossentry>
7435
7436 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
7437 <glossdef>
7438 <para>
7439 Defines the suffix for shared libraries used on the
7440 target platform.
7441 By default, this suffix is ".so.*" for all Linux-based
7442 systems and is defined in the
7443 <filename>meta/conf/bitbake.conf</filename> configuration
7444 file.
7445 </para>
7446
7447 <para>
7448 You will see this variable referenced in the default values
7449 of <filename>FILES_${PN}</filename>.
7450 </para>
7451 </glossdef>
7452 </glossentry>
7453
7454 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
7455 <glossdef>
7456 <para>
7457 Defines the suffix for the development symbolic link
7458 (symlink) for shared libraries on the target platform.
7459 By default, this suffix is ".so" for Linux-based
7460 systems and is defined in the
7461 <filename>meta/conf/bitbake.conf</filename> configuration
7462 file.
7463 </para>
7464
7465 <para>
7466 You will see this variable referenced in the default values
7467 of <filename>FILES_${PN}-dev</filename>.
7468 </para>
7469 </glossdef>
7470 </glossentry>
7471
7472 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
7473 <glossdef>
7474 <para>
7475 Defines your own
7476 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
7477 from which to first fetch source before attempting to fetch
7478 from the upstream specified in
7479 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
7480 </para>
7481
7482 <para>
7483 To use this variable, you must globally inherit the
7484 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
7485 class and then provide the URL to your mirrors.
7486 Here is an example:
7487 <literallayout class='monospaced'>
7488 INHERIT += "own-mirrors"
7489 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
7490 </literallayout>
7491 <note>
7492 You can specify only a single URL in
7493 <filename>SOURCE_MIRROR_URL</filename>.
7494 </note>
7495 </para>
7496 </glossdef>
7497 </glossentry>
7498
7499 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
7500 <glossdef>
7501 <para>
7502 Maps commonly used license names to their SPDX counterparts
7503 found in <filename>meta/files/common-licenses/</filename>.
7504 For the default <filename>SPDXLICENSEMAP</filename>
7505 mappings, see the
7506 <filename>meta/conf/licenses.conf</filename> file.
7507 </para>
7508
7509 <para>
7510 For additional information, see the
7511 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
7512 variable.
7513 </para>
7514 </glossdef>
7515 </glossentry>
7516
7517 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
7518 <glossdef>
7519 <para>
7520 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
7521 OpenEmbedded build system to create variants of recipes or packages.
7522 The list specifies the prefixes to strip off during certain circumstances
7523 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
7524 </para>
7525 </glossdef>
7526 </glossentry>
7527
7528 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
7529 <glossdef>
7530 <para>The list of source files - local or remote.
7531 This variable tells the OpenEmbedded build system which bits
7532 to pull in for the build and how to pull them in.
7533 For example, if the recipe or append file only needs to
7534 fetch a tarball from the Internet, the recipe or
7535 append file uses a single <filename>SRC_URI</filename>
7536 entry.
7537 On the other hand, if the recipe or append file needs to
7538 fetch a tarball, apply two patches, and include a custom
7539 file, the recipe or append file would include four
7540 instances of the variable.</para>
7541 <para>The following list explains the available URI protocols:
7542 <itemizedlist>
7543 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
7544 Fetches files, which are usually files shipped with
7545 the
7546 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
7547 from the local machine.
7548 The path is relative to the
7549 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
7550 variable.
7551 Thus, the build system searches, in order, from the
7552 following directories, which are assumed to be a
7553 subdirectories of the directory in which the
7554 recipe file (<filename>.bb</filename>) or
7555 append file (<filename>.bbappend</filename>)
7556 resides:
7557 <itemizedlist>
7558 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
7559 The base recipe name without any special
7560 suffix or version numbers.
7561 </para></listitem>
7562 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
7563 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
7564 The base recipe name and version but without
7565 any special package name suffix.
7566 </para></listitem>
7567 <listitem><para><emphasis>files -</emphasis>
7568 Files within a directory, which is named
7569 <filename>files</filename> and is also
7570 alongside the recipe or append file.
7571 </para></listitem>
7572 </itemizedlist>
7573 <note>
7574 If you want the build system to pick up files
7575 specified through a
7576 <filename>SRC_URI</filename>
7577 statement from your append file, you need to be
7578 sure to extend the
7579 <filename>FILESPATH</filename>
7580 variable by also using the
7581 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
7582 variable from within your append file.
7583 </note>
7584 </para></listitem>
7585 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
7586 Bazaar revision control repository.</para></listitem>
7587 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
7588 Git revision control repository.</para></listitem>
7589 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
7590 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
7591 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
7592 a repo (Git) repository.</para></listitem>
7593 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
7594 an SVK revision control repository.</para></listitem>
7595 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
7596 the Internet using <filename>http</filename>.</para></listitem>
7597 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
7598 from the Internet using <filename>https</filename>.</para></listitem>
7599 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
7600 from the Internet using <filename>ftp</filename>.</para></listitem>
7601 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
7602 a CVS revision control repository.</para></listitem>
7603 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
7604 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
7605 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
7606 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
7607 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
7608 a secure shell.</para></listitem>
7609 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
7610 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
7611 </itemizedlist>
7612 </para>
7613 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
7614 Here are standard options:
7615 <itemizedlist>
7616 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
7617 the patch or not.
7618 The default action is to apply the patch.</para></listitem>
7619 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
7620 striplevel to use when applying the patch.
7621 The default level is 1.</para></listitem>
7622 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
7623 the directory in which the patch should be applied.
7624 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
7625 </para></listitem>
7626 </itemizedlist>
7627 </para>
7628 <para>Here are options specific to recipes building code from a revision control system:
7629 <itemizedlist>
7630 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
7631 Apply the patch only if
7632 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
7633 is equal to or greater than <filename>mindate</filename>.
7634 </para></listitem>
7635 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
7636 Apply the patch only if <filename>SRCDATE</filename>
7637 is not later than <filename>mindate</filename>.
7638 </para></listitem>
7639 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
7640 Apply the patch only if <filename>SRCREV</filename>
7641 is equal to or greater than <filename>minrev</filename>.
7642 </para></listitem>
7643 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
7644 Apply the patch only if <filename>SRCREV</filename>
7645 is not later than <filename>maxrev</filename>.
7646 </para></listitem>
7647 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
7648 Apply the patch only if <filename>SRCREV</filename>
7649 is equal to <filename>rev</filename>.
7650 </para></listitem>
7651 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
7652 Apply the patch only if <filename>SRCREV</filename>
7653 is not equal to <filename>rev</filename>.
7654 </para></listitem>
7655 </itemizedlist>
7656 </para>
7657 <para>Here are some additional options worth mentioning:
7658 <itemizedlist>
7659 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
7660 whether or not to unpack the file if it is an archive.
7661 The default action is to unpack the file.</para></listitem>
7662 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
7663 (or extracts its contents) into the specified
7664 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
7665 This option is useful for unusual tarballs or other archives that
7666 do not have their files already in a subdirectory within the archive.
7667 </para></listitem>
7668 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
7669 name to be used for association with <filename>SRC_URI</filename> checksums
7670 when you have more than one file specified in <filename>SRC_URI</filename>.
7671 </para></listitem>
7672 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
7673 the filename used when storing the downloaded file.</para></listitem>
7674 </itemizedlist>
7675 </para>
7676 </glossdef>
7677 </glossentry>
7678
7679 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
7680 <glossdef>
7681 <para></para>
7682 <para>
7683 By default, the OpenEmbedded build system automatically detects whether
7684 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
7685 contains files that are machine-specific.
7686 If so, the build system automatically changes
7687 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
7688 Setting this variable to "0" disables this behavior.
7689 </para>
7690 </glossdef>
7691 </glossentry>
7692
7693 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
7694 <glossdef>
7695 <para>
7696 The date of the source code used to build the package.
7697 This variable applies only if the source was fetched from a Source Code Manager (SCM).
7698 </para>
7699 </glossdef>
7700 </glossentry>
7701
7702 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
7703 <glossdef>
7704 <para>
7705 Returns the version string of the current package.
7706 This string is used to help define the value of
7707 <link linkend='var-PV'><filename>PV</filename></link>.
7708 </para>
7709
7710 <para>
7711 The <filename>SRCPV</filename> variable is defined in the
7712 <filename>meta/conf/bitbake.conf</filename> configuration
7713 file in the
7714 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
7715 as follows:
7716 <literallayout class='monospaced'>
7717 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7718 </literallayout>
7719 </para>
7720
7721 <para>
7722 Recipes that need to define <filename>PV</filename> do so
7723 with the help of the <filename>SRCPV</filename>.
7724 For example, the <filename>ofono</filename> recipe
7725 (<filename>ofono_git.bb</filename>) located in
7726 <filename>meta/recipes-connectivity</filename> in the
7727 Source Directory defines <filename>PV</filename> as
7728 follows:
7729 <literallayout class='monospaced'>
7730 PV = "0.12-git${SRCPV}"
7731 </literallayout>
7732 </para>
7733 </glossdef>
7734 </glossentry>
7735
7736 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
7737 <glossdef>
7738 <para>
7739 The revision of the source code used to build the package.
7740 This variable applies to Subversion, Git, Mercurial and Bazaar
7741 only.
7742 Note that if you wish to build a fixed revision and you wish
7743 to avoid performing a query on the remote repository every time
7744 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
7745 full revision identifier and not just a tag.
7746 </para>
7747 </glossdef>
7748 </glossentry>
7749
7750 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
7751 <glossdef>
7752 <para>The directory for the shared state cache.</para>
7753 </glossdef>
7754 </glossentry>
7755
7756 <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
7757 <glossdef>
7758 <para>
7759 If set to "1", allows fetches from
7760 mirrors that are specified in
7761 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
7762 to work even when fetching from the network has been
7763 disabled by setting <filename>BB_NO_NETWORK</filename>
7764 to "1".
7765 Using the
7766 <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
7767 variable is useful if you have set
7768 <filename>SSTATE_MIRRORS</filename> to point to an
7769 internal server for your shared state cache, but
7770 you want to disable any other fetching from the network.
7771 </para>
7772 </glossdef>
7773 </glossentry>
7774
7775 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
7776 <glossdef>
7777 <para>
7778 Configures the OpenEmbedded build system to search other
7779 mirror locations for prebuilt cache data objects before
7780 building out the data.
7781 This variable works like fetcher
7782 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
7783 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
7784 and points to the cache locations to check for the shared
7785 objects.
7786 </para>
7787
7788 <para>
7789 You can specify a filesystem directory or a remote URL such
7790 as HTTP or FTP.
7791 The locations you specify need to contain the shared state
7792 cache (sstate-cache) results from previous builds.
7793 The sstate-cache you point to can also be from builds on
7794 other machines.
7795 </para>
7796
7797 <para>
7798 If a mirror uses the same structure as
7799 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
7800 you need to add
7801 "PATH" at the end as shown in the examples below.
7802 The build system substitutes the correct path within the
7803 directory structure.
7804 <literallayout class='monospaced'>
7805 SSTATE_MIRRORS ?= "\
7806 file://.* http://someserver.tld/share/sstate/PATH \n \
7807 file://.* file:///some/local/dir/sstate/PATH"
7808 </literallayout>
7809 </para>
7810 </glossdef>
7811 </glossentry>
7812
7813 <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
7814 <glossdef>
7815 <para>
7816 Specifies the path to the <filename>/lib</filename>
7817 subdirectory of the sysroot directory for the
7818 build host.
7819 </para>
7820 </glossdef>
7821 </glossentry>
7822
7823 <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
7824 <glossdef>
7825 <para>
7826 Specifies the path to the <filename>/lib</filename>
7827 subdirectory of the sysroot directory for the target
7828 for which the current recipe is being built
7829 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
7830 </para>
7831 </glossdef>
7832 </glossentry>
7833
7834 <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
7835 <glossdef>
7836 <para>
7837 Specifies the path to the
7838 <filename>/usr/bin</filename> subdirectory of the
7839 sysroot directory for the target for which the current
7840 recipe is being built
7841 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
7842 </para>
7843 </glossdef>
7844 </glossentry>
7845
7846 <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
7847 <glossdef>
7848 <para>
7849 Specifies the path to the directory containing binary
7850 configuration scripts.
7851 These scripts provide configuration information for
7852 other software that wants to make use of libraries or
7853 include files provided by the software associated with
7854 the script.
7855 <note>
7856 This style of build configuration has been largely
7857 replaced by <filename>pkg-config</filename>.
7858 Consequently, if <filename>pkg-config</filename>
7859 is supported by the library to which you are linking,
7860 it is recommended you use
7861 <filename>pkg-config</filename> instead of a
7862 provided configuration script.
7863 </note>
7864 </para>
7865 </glossdef>
7866 </glossentry>
7867
7868 <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
7869 <glossdef>
7870 <para>
7871 Specifies the path to the
7872 <filename>/usr/bin</filename> subdirectory of the
7873 sysroot directory for the build host.
7874 </para>
7875 </glossdef>
7876 </glossentry>
7877
7878 <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
7879 <glossdef>
7880 <para>
7881 Specifies the path to the <filename>/usr/share</filename>
7882 subdirectory of the sysroot directory for the target
7883 for which the current recipe is being built
7884 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
7885 </para>
7886 </glossdef>
7887 </glossentry>
7888
7889 <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
7890 <glossdef>
7891 <para>
7892 Specifies the path to the top-level sysroots directory
7893 (i.e.
7894 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>).
7895 <note>
7896 Recipes should never write files directly under
7897 this directory because the OpenEmbedded build system
7898 manages the directory automatically.
7899 Instead, files should be installed to
7900 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
7901 within your recipe's
7902 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
7903 task and then the OpenEmbedded build system will
7904 stage a subset of those files into the sysroot.
7905 </note>
7906 </para>
7907 </glossdef>
7908 </glossentry>
7909
7910 <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
7911 <glossdef>
7912 <para>
7913 Specifies the path to the primary sysroot directory for
7914 which the target is being built.
7915 Depending on the type of recipe and the build target, the
7916 recipe's value is as follows:
7917 <itemizedlist>
7918 <listitem><para>For recipes building for the target
7919 machine, the value is "${STAGING_DIR}/${MACHINE}".
7920 </para></listitem>
7921 <listitem><para>For <filename>native</filename>
7922 recipes building
7923 for the build host, the value is empty given the
7924 assumption that when building for the build host,
7925 the build host's own directories should be used.
7926 </para></listitem>
7927 <listitem><para>For <filename>nativesdk</filename>
7928 recipes that Build for the SDK, the value is
7929 "${STAGING_DIR}/${MULTIMACH_HOST_SYS}".
7930 </para></listitem>
7931 </itemizedlist>
7932 </para>
7933 </glossdef>
7934 </glossentry>
7935
7936 <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
7937 <glossdef>
7938 <para>
7939 Specifies the path to the <filename>/usr/share</filename>
7940 subdirectory of the sysroot directory for the build host.
7941 </para>
7942 </glossdef>
7943 </glossentry>
7944
7945
7946
7947 <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
7948 <glossdef>
7949 <para>
7950 Specifies the path to the sysroot directory for the
7951 build host.
7952 </para>
7953 </glossdef>
7954 </glossentry>
7955
7956 <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
7957 <glossdef>
7958 <para>
7959 Specifies the path to the sysroot directory for the
7960 target for which the current recipe is being built.
7961 In most cases, this path is the
7962 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
7963 </para>
7964
7965 <para>
7966 Some recipes build binaries that can run on the target
7967 system but those binaries in turn generate code for
7968 another different system (e.g. cross-canadian recipes).
7969 Using terminology from GNU, the primary system is referred
7970 to as the "HOST" and the secondary, or different, system is
7971 referred to as the "TARGET".
7972 Thus, the binaries run on the "HOST" system and
7973 and generate binaries for the "TARGET" system.
7974 <filename>STAGING_DIR_TARGET</filename> points to the
7975 sysroot used for the "TARGET" system.
7976 </para>
7977 </glossdef>
7978 </glossentry>
7979
7980 <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
7981 <glossdef>
7982 <para>
7983 Specifies the path to the <filename>/etc</filename>
7984 subdirectory of the sysroot directory for the
7985 build host.
7986 </para>
7987 </glossdef>
7988 </glossentry>
7989
7990 <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
7991 <glossdef>
7992 <para>
7993 Specifies the path to the <filename>/usr</filename>
7994 subdirectory of the sysroot directory for the target
7995 for which the current recipe is being built
7996 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
7997 </para>
7998 </glossdef>
7999 </glossentry>
8000
8001 <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
8002 <glossdef>
8003 <para>
8004 Specifies the path to the
8005 <filename>/usr/include</filename> subdirectory of the
8006 sysroot directory for the target for which the current
8007 recipe being built
8008 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
8009 </para>
8010 </glossdef>
8011 </glossentry>
8012
8013 <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
8014 <glossdef>
8015 <para>
8016 Specifies the path to the <filename>/usr/include</filename>
8017 subdirectory of the sysroot directory for the build host.
8018 </para>
8019 </glossdef>
8020 </glossentry>
8021
8022 <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
8023 <glossdef>
8024 <para>
8025 Specifies the path to the <filename>/usr/lib</filename>
8026 subdirectory of the sysroot directory for the target for
8027 which the current recipe is being built
8028 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
8029 </para>
8030 </glossdef>
8031 </glossentry>
8032
8033 <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
8034 <glossdef>
8035 <para>
8036 Specifies the path to the <filename>/usr/lib</filename>
8037 subdirectory of the sysroot directory for the build host.
8038 </para>
8039 </glossdef>
8040 </glossentry>
8041
8042 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
8043 <glossdef>
8044 <para>
8045 The directory with kernel headers that are required to build out-of-tree
8046 modules.
8047 </para>
8048 </glossdef>
8049 </glossentry>
8050
8051 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
8052 <glossdef>
8053 <para>
8054 Specifies the base path used to create recipe stamp files.
8055 The path to an actual stamp file is constructed by evaluating this
8056 string and then appending additional information.
8057 Currently, the default assignment for <filename>STAMP</filename>
8058 as set in the <filename>meta/conf/bitbake.conf</filename> file
8059 is:
8060 <literallayout class='monospaced'>
8061 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
8062 </literallayout>
8063 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
8064 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
8065 <link linkend='var-PN'><filename>PN</filename></link>,
8066 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
8067 <link linkend='var-PV'><filename>PV</filename></link>, and
8068 <link linkend='var-PR'><filename>PR</filename></link> for related variable
8069 information.
8070 </para>
8071 </glossdef>
8072 </glossentry>
8073
8074 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
8075 <glossdef>
8076 <para>
8077 Specifies the base directory in which the OpenEmbedded
8078 build system places stamps.
8079 The default directory is
8080 <filename>${TMPDIR}/stamps</filename>.
8081 </para>
8082 </glossdef>
8083 </glossentry>
8084
8085 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
8086 <glossdef>
8087 <para>The short (72 characters or less) summary of the binary package for packaging
8088 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
8089 <filename>dpkg</filename>.
8090 By default, <filename>SUMMARY</filename> is used to define
8091 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
8092 variable if <filename>DESCRIPTION</filename> is not set
8093 in the recipe.
8094 </para>
8095 </glossdef>
8096 </glossentry>
8097
8098 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
8099 <glossdef>
8100 <para>
8101 Specifies the kernel boot default console.
8102 If you want to use a console other than the default,
8103 set this variable in your recipe as follows where "X" is
8104 the console number you want to use:
8105 <literallayout class='monospaced'>
8106 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
8107 </literallayout>
8108 </para>
8109
8110 <para>
8111 The
8112 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8113 class initially sets this variable to null but then checks
8114 for a value later.
8115 </para>
8116 </glossdef>
8117 </glossentry>
8118
8119 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
8120 <glossdef>
8121 <para>
8122 Lists additional options to add to the syslinux file.
8123 You need to set this variable in your recipe.
8124 If you want to list multiple options, separate the options
8125 with a semicolon character (<filename>;</filename>).
8126 </para>
8127
8128 <para>
8129 The
8130 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8131 class uses this variable to create a set of options.
8132 </para>
8133 </glossdef>
8134 </glossentry>
8135
8136 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
8137 <glossdef>
8138 <para>
8139 Specifies the alternate serial port or turns it off.
8140 To turn off serial, set this variable to an empty string
8141 in your recipe.
8142 The variable's default value is set in the
8143 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8144 as follows:
8145 <literallayout class='monospaced'>
8146 SYSLINUX_SERIAL ?= "0 115200"
8147 </literallayout>
8148 The class checks for and uses the variable as needed. </para>
8149 </glossdef>
8150 </glossentry>
8151
8152 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
8153 <glossdef>
8154 <para>
8155 An <filename>.LSS</filename> file used as the background
8156 for the VGA boot menu when you are using the boot menu.
8157 You need to set this variable in your recipe.
8158 </para>
8159
8160 <para>
8161 The
8162 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8163 class checks for this variable and if found, the
8164 OpenEmbedded build system installs the splash screen.
8165 </para>
8166 </glossdef>
8167 </glossentry>
8168
8169 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
8170 <glossdef>
8171 <para>
8172 Specifies the alternate console=tty... kernel boot argument.
8173 The variable's default value is set in the
8174 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8175 as follows:
8176 <literallayout class='monospaced'>
8177 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
8178 </literallayout>
8179 The class checks for and uses the variable as needed.
8180 </para>
8181 </glossdef>
8182 </glossentry>
8183
8184 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
8185 <glossdef>
8186 <para>
8187 A list of functions to execute after files are staged into
8188 the sysroot.
8189 These functions are usually used to apply additional
8190 processing on the staged files, or to stage additional
8191 files.
8192 </para>
8193 </glossdef>
8194 </glossentry>
8195
8196 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
8197 <glossdef>
8198 <para>
8199 For recipes that inherit the
8200 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
8201 class, this variable specifies whether the service you have
8202 specified in
8203 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
8204 should be started automatically or not.
8205 By default, the service is enabled to automatically start
8206 at boot time.
8207 The default setting is in the
8208 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
8209 class as follows:
8210 <literallayout class='monospaced'>
8211 SYSTEMD_AUTO_ENABLE ??= "enable"
8212 </literallayout>
8213 You can disable the service by setting the variable to
8214 "disable".
8215 </para>
8216 </glossdef>
8217 </glossentry>
8218
8219 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
8220 <glossdef>
8221 <para>
8222 For recipes that inherit the
8223 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
8224 class, this variable locates the systemd unit files when
8225 they are not found in the main recipe's package.
8226 By default, the
8227 <filename>SYSTEMD_PACKAGES</filename> variable is set
8228 such that the systemd unit files are assumed to reside in
8229 the recipes main package:
8230 <literallayout class='monospaced'>
8231 SYSTEMD_PACKAGES ?= "${PN}"
8232 </literallayout>
8233 If these unit files are not in this recipe's main
8234 package, you need to use
8235 <filename>SYSTEMD_PACKAGES</filename> to list the package
8236 or packages in which the build system can find the systemd
8237 unit files.
8238 </para>
8239 </glossdef>
8240 </glossentry>
8241
8242 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
8243 <glossdef>
8244 <para>
8245 For recipes that inherit the
8246 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
8247 class, this variable specifies the systemd service name for
8248 a package.
8249 </para>
8250
8251 <para>
8252 When you specify this file in your recipe, use a package
8253 name override to indicate the package to which the value
8254 applies.
8255 Here is an example from the connman recipe:
8256 <literallayout class='monospaced'>
8257 SYSTEMD_SERVICE_${PN} = "connman.service"
8258 </literallayout>
8259 </para>
8260 </glossdef>
8261 </glossentry>
8262
8263 </glossdiv>
8264
8265 <glossdiv id='var-glossary-t'><title>T</title>
8266
8267 <glossentry id='var-T'><glossterm>T</glossterm>
8268 <glossdef>
8269 <para>This variable points to a directory were BitBake places
8270 temporary files, which consist mostly of task logs and
8271 scripts, when building a particular recipe.
8272 The variable is typically set as follows:
8273 <literallayout class='monospaced'>
8274 T = "${WORKDIR}/temp"
8275 </literallayout>
8276 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
8277 is the directory into which BitBake unpacks and builds the
8278 recipe.
8279 The default <filename>bitbake.conf</filename> file sets this variable.</para>
8280 <para>The <filename>T</filename> variable is not to be confused with
8281 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
8282 which points to the root of the directory tree where BitBake
8283 places the output of an entire build.
8284 </para>
8285 </glossdef>
8286 </glossentry>
8287
8288 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
8289 <glossdef>
8290 <para>
8291 The target machine's architecture.
8292 The OpenEmbedded build system supports many
8293 architectures.
8294 Here is an example list of architectures supported.
8295 This list is by no means complete as the architecture
8296 is configurable:
8297 <literallayout class='monospaced'>
8298 arm
8299 i586
8300 x86_64
8301 powerpc
8302 powerpc64
8303 mips
8304 mipsel
8305 </literallayout>
8306 For additional information on machine architectures, see
8307 the
8308 <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
8309 variable.
8310 </para>
8311 </glossdef>
8312 </glossentry>
8313
8314 <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
8315 <glossdef>
8316 <para>
8317 Specifies architecture-specific assembler flags for the
8318 target system.
8319 <filename>TARGET_AS_ARCH</filename> is initialized from
8320 <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
8321 by default in the BitBake configuration file
8322 (<filename>meta/conf/bitbake.conf</filename>):
8323 <literallayout class='monospaced'>
8324 TARGET_AS_ARCH = "${TUNE_ASARGS}"
8325 </literallayout>
8326 </para>
8327 </glossdef>
8328 </glossentry>
8329
8330 <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
8331 <glossdef>
8332 <para>
8333 Specifies architecture-specific C compiler flags for the
8334 target system.
8335 <filename>TARGET_CC_ARCH</filename> is initialized from
8336 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
8337 by default.
8338 <note>
8339 It is a common workaround to append
8340 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
8341 to <filename>TARGET_CC_ARCH</filename>
8342 in recipes that build software for the target that
8343 would not otherwise respect the exported
8344 <filename>LDFLAGS</filename> variable.
8345 </note>
8346 </para>
8347 </glossdef>
8348 </glossentry>
8349
8350 <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
8351 <glossdef>
8352 <para>
8353 This is a specific kernel compiler flag for a CPU or
8354 Application Binary Interface (ABI) tune.
8355 The flag is used rarely and only for cases where a
8356 userspace
8357 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
8358 is not compatible with the kernel compilation.
8359 The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
8360 allows the kernel (and associated modules) to use a
8361 different configuration.
8362 See the
8363 <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
8364 file in the
8365 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
8366 for an example.
8367 </para>
8368 </glossdef>
8369 </glossentry>
8370
8371 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
8372 <glossdef>
8373 <para>
8374 Specifies the flags to pass to the C compiler when building
8375 for the target.
8376 When building in the target context,
8377 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
8378 is set to the value of this variable by default.
8379 </para>
8380
8381 <para>
8382 Additionally, the SDK's environment setup script sets
8383 the
8384 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
8385 variable in the environment to the
8386 <filename>TARGET_CFLAGS</filename> value so that
8387 executables built using the SDK also have the flags
8388 applied.
8389 </para>
8390 </glossdef>
8391 </glossentry>
8392
8393 <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
8394 <glossdef>
8395 <para>
8396 Specifies the flags to pass to the C pre-processor
8397 (i.e. to both the C and the C++ compilers) when building
8398 for the target.
8399 When building in the target context,
8400 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
8401 is set to the value of this variable by default.
8402 </para>
8403
8404 <para>
8405 Additionally, the SDK's environment setup script sets
8406 the
8407 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
8408 variable in the environment to the
8409 <filename>TARGET_CPPFLAGS</filename> value so that
8410 executables built using the SDK also have the flags
8411 applied.
8412 </para>
8413 </glossdef>
8414 </glossentry>
8415
8416 <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
8417 <glossdef>
8418 <para>
8419 Specifies the flags to pass to the C++ compiler when
8420 building for the target.
8421 When building in the target context,
8422 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
8423 is set to the value of this variable by default.
8424 </para>
8425
8426 <para>
8427 Additionally, the SDK's environment setup script sets
8428 the
8429 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
8430 variable in the environment to the
8431 <filename>TARGET_CXXFLAGS</filename> value so that
8432 executables built using the SDK also have the flags
8433 applied.
8434 </para>
8435 </glossdef>
8436 </glossentry>
8437
8438 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
8439 <glossdef>
8440 <para>Specifies the method for handling FPU code.
8441 For FPU-less targets, which include most ARM CPUs, the variable must be
8442 set to "soft".
8443 If not, the kernel emulation gets used, which results in a performance penalty.</para>
8444 </glossdef>
8445 </glossentry>
8446
8447 <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
8448 <glossdef>
8449 <para>
8450 Specifies architecture-specific linker flags for the
8451 target system.
8452 <filename>TARGET_LD_ARCH</filename> is initialized from
8453 <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
8454 by default in the BitBake configuration file
8455 (<filename>meta/conf/bitbake.conf</filename>):
8456 <literallayout class='monospaced'>
8457 TARGET_LD_ARCH = "${TUNE_LDARGS}"
8458 </literallayout>
8459 </para>
8460 </glossdef>
8461 </glossentry>
8462
8463 <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
8464 <glossdef>
8465 <para>
8466 Specifies the flags to pass to the linker when building
8467 for the target.
8468 When building in the target context,
8469 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
8470 is set to the value of this variable by default.
8471 </para>
8472
8473 <para>
8474 Additionally, the SDK's environment setup script sets
8475 the
8476 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
8477 variable in the environment to the
8478 <filename>TARGET_LDFLAGS</filename> value so that
8479 executables built using the SDK also have the flags
8480 applied.
8481 </para>
8482 </glossdef>
8483 </glossentry>
8484
8485 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
8486 <glossdef>
8487 <para>Specifies the target's operating system.
8488 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
8489 to "linux-uclibc" for <filename>uclibc</filename>.
8490 For ARM/EABI targets, there are also "linux-gnueabi" and
8491 "linux-uclibc-gnueabi" values possible.</para>
8492 </glossdef>
8493 </glossentry>
8494
8495 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
8496 <glossdef>
8497 <para>
8498 Specifies the GNU standard C library (<filename>libc</filename>)
8499 variant to use during the build process.
8500 This variable replaces <filename>POKYLIBC</filename>, which is no longer
8501 supported.
8502 </para>
8503 <para>
8504 You can select "eglibc" or "uclibc".
8505 <note>
8506 This release of the Yocto Project does not support the
8507 <filename>glibc</filename> implementation of <filename>libc</filename>.
8508 </note>
8509 </para>
8510 </glossdef>
8511 </glossentry>
8512
8513 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
8514 <glossdef>
8515 <para>
8516 Specifies the toolchain selector.
8517 <filename>TCMODE</filename> controls the characteristics
8518 of the generated packages and images by telling the
8519 OpenEmbedded build system which toolchain profile to use.
8520 By default, the OpenEmbedded build system builds its own
8521 internal toolchain.
8522 The variable's default value is "default", which uses
8523 that internal toolchain.
8524 <note>
8525 If <filename>TCMODE</filename> is set to a value
8526 other than "default", then it is your responsibility
8527 to ensure that the toolchain is compatible with the
8528 default toolchain.
8529 Using older or newer versions of these components
8530 might cause build problems.
8531 See the
8532 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
8533 for the specific components with which the toolchain
8534 must be compatible.
8535 </note>
8536 </para>
8537
8538 <para>
8539 With additional layers, it is possible to use a pre-compiled
8540 external toolchain.
8541 One example is the Sourcery G++ Toolchain.
8542 The support for this toolchain resides in the separate
8543 <filename>meta-sourcery</filename> layer at
8544 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
8545 You can use <filename>meta-sourcery</filename> as a
8546 template for adding support for other external toolchains.
8547 </para>
8548
8549 <para>
8550 The <filename>TCMODE</filename> variable points the build
8551 system to a file in
8552 <filename>conf/distro/include/tcmode-${TCMODE}.inc</filename>.
8553 Thus, for <filename>meta-sourcery</filename>,
8554 which has <filename>conf/distro/include/tcmode-external-sourcery.inc</filename>,
8555 you would set the variable as follows:
8556 <literallayout class='monospaced'>
8557 TCMODE ?= "external-sourcery"
8558 </literallayout>
8559 </para>
8560
8561 <para>
8562 The variable is similar to
8563 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
8564 which controls the variant of the GNU standard C library
8565 (<filename>libc</filename>) used during the build process:
8566 <filename>eglibc</filename> or <filename>uclibc</filename>.
8567 </para>
8568 </glossdef>
8569 </glossentry>
8570
8571 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
8572 <glossdef>
8573 <para>
8574 The location the OpenEmbedded build system uses to export
8575 tests when the
8576 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
8577 variable is set to "1".
8578 </para>
8579
8580 <para>
8581 The <filename>TEST_EXPORT_DIR</filename> variable defaults
8582 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
8583 </para>
8584 </glossdef>
8585 </glossentry>
8586
8587 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
8588 <glossdef>
8589 <para>
8590 Specifies to export the tests only.
8591 Set this variable to "1" if you do not want to run the
8592 tests but you want them to be exported in a manner that
8593 you to run them outside of the build system.
8594 </para>
8595 </glossdef>
8596 </glossentry>
8597
8598 <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
8599 <glossdef>
8600 <para>
8601 Automatically runs the series of automated tests for
8602 images when an image is successfully built.
8603 </para>
8604
8605 <para>
8606 These tests are written in Python making use of the
8607 <filename>unittest</filename> module, and the majority of
8608 them run commands on the target system over
8609 <filename>ssh</filename>.
8610 You can set this variable to "1" in your
8611 <filename>local.conf</filename> file in the
8612 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
8613 to have the OpenEmbedded build system automatically run
8614 these tests after an image successfully builds:
8615 <literallayout class='monospaced'>
8616 TEST_IMAGE = "1"
8617 </literallayout>
8618 For more information on enabling, running, and writing
8619 these tests, see the
8620 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
8621 section in the Yocto Project Development Manual and the
8622 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
8623 section.
8624 </para>
8625 </glossdef>
8626 </glossentry>
8627
8628 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
8629 <glossdef>
8630 <para>
8631 Holds the SSH log and the boot log for QEMU machines.
8632 The <filename>TEST_LOG_DIR</filename> variable defaults
8633 to <filename>"${WORKDIR}/testimage"</filename>.
8634 <note>
8635 Actual test results reside in the task log
8636 (<filename>log.do_testimage</filename>), which is in
8637 the <filename>${WORKDIR}/temp/</filename> directory.
8638 </note>
8639 </para>
8640 </glossdef>
8641 </glossentry>
8642
8643 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
8644 <glossdef>
8645 <para>
8646 The time in seconds allowed for an image to boot before
8647 automated runtime tests begin to run against an
8648 image.
8649 The default timeout period to allow the boot process to
8650 reach the login prompt is 500 seconds.
8651 You can specify a different value in the
8652 <filename>local.conf</filename> file.
8653 </para>
8654
8655 <para>
8656 For more information on testing images, see the
8657 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
8658 section in the Yocto Project Development Manual.
8659 </para>
8660 </glossdef>
8661 </glossentry>
8662
8663 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
8664 <glossdef>
8665 <para>
8666 The IP address of the build machine (host machine).
8667 This IP address is usually automatically detected.
8668 However, if detection fails, this variable needs to be set
8669 to the IP address of the build machine (i.e. where
8670 the build is taking place).
8671 <note>
8672 The <filename>TEST_SERVER_IP</filename> variable
8673 is only used for a small number of tests such as
8674 the "smart" test suite, which needs to download
8675 packages from <filename>DEPLOY_DIR/rpm</filename>.
8676 </note>
8677 </para>
8678 </glossdef>
8679 </glossentry>
8680
8681 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
8682 <glossdef>
8683 <para>
8684 Specifies the target controller to use when running tests
8685 against a test image.
8686 The default controller to use is "qemu":
8687 <literallayout class='monospaced'>
8688 TEST_TARGET = "qemu"
8689 </literallayout>
8690 A target controller is a class that defines how an
8691 image gets deployed on a target and how a target is started.
8692 A layer can extend the controllers by adding a module
8693 in the layer's <filename>/lib/oeqa/controllers</filename>
8694 directory and by inheriting the
8695 <filename>BaseTarget</filename> class, which is an abstract
8696 class that cannot be used as a value of
8697 <filename>TEST_TARGET</filename>.
8698 </para>
8699
8700 <para>
8701 You can provide the following arguments with
8702 <filename>TEST_TARGET</filename>:
8703 <itemizedlist>
8704 <listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>
8705 Boots a QEMU image and runs the tests.
8706 See the
8707 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
8708 section in the Yocto Project Development Manual for
8709 more information.
8710 </para></listitem>
8711 <listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>
8712 Runs the tests on target hardware that is already
8713 up and running.
8714 The hardware can be on the network or it can be
8715 a device running an image on QEMU.
8716 You must also set
8717 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
8718 when you use "simpleremote" or "SimpleRemoteTarget".
8719 <note>
8720 This argument is defined in
8721 <filename>meta/lib/oeqa/targetcontrol.py</filename>.
8722 The small caps names are kept for compatibility
8723 reasons.
8724 </note>
8725 </para></listitem>
8726 <listitem><para><emphasis>"GummibootTarget":</emphasis>
8727 Automatically deploys and runs tests on an
8728 EFI-enabled machine that has a master image
8729 installed.
8730 <note>
8731 This argument is defined in
8732 <filename>meta/lib/oeqa/controllers/masterimage.py</filename>.
8733 </note>
8734 </para></listitem>
8735 </itemizedlist>
8736 </para>
8737
8738 <para>
8739 For information on running tests on hardware, see the
8740 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
8741 section in the Yocto Project Development Manual.
8742 </para>
8743 </glossdef>
8744 </glossentry>
8745
8746 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
8747 <glossdef>
8748 <para>
8749 The IP address of your hardware under test.
8750 The <filename>TEST_TARGET_IP</filename> variable has no
8751 effect when
8752 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
8753 is set to "qemu".
8754 </para>
8755
8756 <para>
8757 When you specify the IP address, you can also include a
8758 port.
8759 Here is an example:
8760 <literallayout class='monospaced'>
8761 TEST_TARGET_IP = "192.168.1.4:2201"
8762 </literallayout>
8763 Specifying a port is useful when SSH is started on a
8764 non-standard port or in cases when your hardware under test
8765 is behind a firewall or network that is not directly
8766 accessible from your host and you need to do port address
8767 translation.
8768 </para>
8769 </glossdef>
8770 </glossentry>
8771
8772 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
8773 <glossdef>
8774 <para>
8775 An ordered list of tests (modules) to run against
8776 an image when performing automated runtime testing.
8777 </para>
8778
8779 <para>
8780 The OpenEmbedded build system provides a core set of tests
8781 that can be used against images.
8782 <note>
8783 Currently, there is only support for running these tests
8784 under QEMU.
8785 </note>
8786 Tests include <filename>ping</filename>,
8787 <filename>ssh</filename>, <filename>df</filename> among
8788 others.
8789 You can add your own tests to the list of tests by
8790 appending <filename>TEST_SUITES</filename> as follows:
8791 <literallayout class='monospaced'>
8792 TEST_SUITES_append = " mytest"
8793 </literallayout>
8794 Alternatively, you can provide the "auto" option to
8795 have all applicable tests run against the image.
8796 <literallayout class='monospaced'>
8797 TEST_SUITES_append = " auto"
8798 </literallayout>
8799 Using this option causes the build system to automatically
8800 run tests that are applicable to the image.
8801 Tests that are not applicable are skipped.
8802 </para>
8803
8804 <para>
8805 The order in which tests are run is important.
8806 Tests that depend on another test must appear later in the
8807 list than the test on which they depend.
8808 For example, if you append the list of tests with two
8809 tests (<filename>test_A</filename> and
8810 <filename>test_B</filename>) where
8811 <filename>test_B</filename> is dependent on
8812 <filename>test_A</filename>, then you must order the tests
8813 as follows:
8814 <literallayout class='monospaced'>
8815 TEST_SUITES = " test_A test_B"
8816 </literallayout>
8817 </para>
8818
8819 <para>
8820 For more information on testing images, see the
8821 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
8822 section in the Yocto Project Development Manual.
8823 </para>
8824 </glossdef>
8825 </glossentry>
8826
8827 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
8828 <glossdef>
8829 <para>
8830 The directory in which the file BitBake is currently
8831 parsing is located.
8832 Do not manually set this variable.
8833 </para>
8834 </glossdef>
8835 </glossentry>
8836
8837 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
8838 <glossdef>
8839 <para>
8840 This variable is the base directory the OpenEmbedded
8841 build system uses for all build output and intermediate
8842 files (other than the shared state cache).
8843 By default, the <filename>TMPDIR</filename> variable points
8844 to <filename>tmp</filename> within the
8845 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
8846 </para>
8847
8848 <para>
8849 If you want to establish this directory in a location other
8850 than the default, you can uncomment and edit the following
8851 statement in the
8852 <filename>conf/local.conf</filename> file in the
8853 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
8854 <literallayout class='monospaced'>
8855 #TMPDIR = "${TOPDIR}/tmp"
8856 </literallayout>
8857 An example use for this scenario is to set
8858 <filename>TMPDIR</filename> to a local disk, which does
8859 not use NFS, while having the Build Directory use NFS.
8860 </para>
8861
8862 <para>
8863 The filesystem used by <filename>TMPDIR</filename> must
8864 have standard filesystem semantics (i.e. mixed-case files
8865 are unique, POSIX file locking, and persistent inodes).
8866 Due to various issues with NFS and bugs in some
8867 implementations, NFS does not meet this minimum
8868 requirement.
8869 Consequently, <filename>TMPDIR</filename> cannot be on
8870 NFS.
8871 </para>
8872 </glossdef>
8873 </glossentry>
8874
8875 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
8876 <glossdef>
8877 <para>
8878 This variable lists packages the OpenEmbedded build system
8879 uses when building an SDK, which contains a
8880 cross-development environment.
8881 The packages specified by this variable are part of the
8882 toolchain set that runs on the
8883 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
8884 and each package should usually have the prefix
8885 "nativesdk-".
8886 When building an SDK using
8887 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
8888 a default list of packages is set in this variable, but
8889 you can add additional packages to the list.
8890 </para>
8891
8892 <para>
8893 For background information on cross-development toolchains
8894 in the Yocto Project development environment, see the
8895 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
8896 section.
8897 For information on setting up a cross-development
8898 environment, see the
8899 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
8900 section in the Yocto Project Application Developer's Guide.
8901 </para>
8902 </glossdef>
8903 </glossentry>
8904
8905 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
8906 <glossdef>
8907 <para>
8908 This variable lists packages the OpenEmbedded build system
8909 uses when it creates the target part of an SDK
8910 (i.e. the part built for the target hardware), which
8911 includes libraries and headers.
8912 </para>
8913
8914 <para>
8915 For background information on cross-development toolchains
8916 in the Yocto Project development environment, see the
8917 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
8918 section.
8919 For information on setting up a cross-development
8920 environment, see the
8921 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
8922 section in the Yocto Project Application Developer's Guide.
8923 </para>
8924 </glossdef>
8925 </glossentry>
8926
8927 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
8928 <glossdef>
8929 <para>
8930 The top-level
8931 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
8932 BitBake automatically sets this variable when you
8933 initialize your build environment using either
8934 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
8935 or
8936 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
8937 </para>
8938 </glossdef>
8939 </glossentry>
8940
8941 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
8942 <glossdef>
8943 <para>
8944 A sanitized version of
8945 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
8946 This variable is used where the architecture is needed in
8947 a value where underscores are not allowed, for example
8948 within package filenames.
8949 In this case, dash characters replace any underscore
8950 characters used in TARGET_ARCH.
8951 </para>
8952
8953 <para>
8954 Do not edit this variable.
8955 </para>
8956 </glossdef>
8957 </glossentry>
8958
8959 <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
8960 <glossdef>
8961 <para>
8962 The GNU canonical architecture for a specific architecture
8963 (i.e. <filename>arm</filename>,
8964 <filename>armeb</filename>,
8965 <filename>mips</filename>,
8966 <filename>mips64</filename>, and so forth).
8967 BitBake uses this value to setup configuration.
8968 </para>
8969
8970 <para>
8971 <filename>TUNE_ARCH</filename> definitions are specific to
8972 a given architecture.
8973 The definitions can be a single static definition, or
8974 can be dynamically adjusted.
8975 You can see details for a given CPU family by looking at
8976 the architecture's <filename>README</filename> file.
8977 For example, the
8978 <filename>meta/conf/machine/include/mips/README</filename>
8979 file in the
8980 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
8981 provides information for <filename>TUNE_ARCH</filename>
8982 specific to the <filename>mips</filename> architecture.
8983 </para>
8984
8985 <para>
8986 <filename>TUNE_ARCH</filename> is tied closely to
8987 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
8988 which defines the target machine's architecture.
8989 The BitBake configuration file
8990 (<filename>meta/conf/bitbake.conf</filename>) sets
8991 <filename>TARGET_ARCH</filename> as follows:
8992 <literallayout class='monospaced'>
8993 TARGET_ARCH = "${TUNE_ARCH}"
8994 </literallayout>
8995 </para>
8996
8997 <para>
8998 The following list, which is by no means complete since
8999 architectures are configurable, shows supported machine
9000 architectures:
9001 <literallayout class='monospaced'>
9002 arm
9003 i586
9004 x86_64
9005 powerpc
9006 powerpc64
9007 mips
9008 mipsel
9009 </literallayout>
9010 </para>
9011 </glossdef>
9012 </glossentry>
9013
9014 <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
9015 <glossdef>
9016 <para>
9017 Specifies architecture-specific assembler flags for
9018 the target system.
9019 The set of flags is based on the selected tune features.
9020 <filename>TUNE_ASARGS</filename> is set using
9021 the tune include files, which are typically under
9022 <filename>meta/conf/machine/include/</filename> and are
9023 influenced through <filename>TUNE_FEATURES</filename>.
9024 For example, the
9025 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
9026 file defines the flags for the x86 architecture as follows:
9027 <literallayout class='monospaced'>
9028 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
9029 </literallayout>
9030 <note>
9031 Board Support Packages (BSPs) can supply their own
9032 set of flags.
9033 </note>
9034 </para>
9035 </glossdef>
9036 </glossentry>
9037
9038 <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
9039 <glossdef>
9040 <para>
9041 Specifies architecture-specific C compiler flags for
9042 the target system.
9043 The set of flags is based on the selected tune features.
9044 <filename>TUNE_CCARGS</filename> is set using
9045 the tune include files, which are typically under
9046 <filename>meta/conf/machine/include/</filename> and are
9047 influenced through <filename>TUNE_FEATURES</filename>.
9048 <note>
9049 Board Support Packages (BSPs) can supply their own
9050 set of flags.
9051 </note>
9052 </para>
9053 </glossdef>
9054 </glossentry>
9055
9056 <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
9057 <glossdef>
9058 <para>
9059 Specifies architecture-specific linker flags for
9060 the target system.
9061 The set of flags is based on the selected tune features.
9062 <filename>TUNE_LDARGS</filename> is set using
9063 the tune include files, which are typically under
9064 <filename>meta/conf/machine/include/</filename> and are
9065 influenced through <filename>TUNE_FEATURES</filename>.
9066 For example, the
9067 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
9068 file defines the flags for the x86 architecture as follows:
9069 <literallayout class='monospaced'>
9070 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
9071 </literallayout>
9072 <note>
9073 Board Support Packages (BSPs) can supply their own
9074 set of flags.
9075 </note>
9076 </para>
9077 </glossdef>
9078 </glossentry>
9079
9080 <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
9081 <glossdef>
9082 <para>
9083 Features used to "tune" a compiler for optimal use
9084 given a specific processor.
9085 The features are defined within the tune files and allow
9086 arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
9087 dynamically generated based on the features.
9088 </para>
9089
9090 <para>
9091 The OpenEmbedded build system verifies the features
9092 to be sure they are not conflicting and that they are
9093 supported.
9094 </para>
9095
9096 <para>
9097 The BitBake configuration file
9098 (<filename>meta/conf/bitbake.conf</filename>) defines
9099 <filename>TUNE_FEATURES</filename> as follows:
9100 <literallayout class='monospaced'>
9101 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
9102 </literallayout>
9103 See the
9104 <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
9105 variable for more information.
9106 </para>
9107 </glossdef>
9108 </glossentry>
9109
9110 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
9111 <glossdef>
9112 <para>
9113 The package architecture understood by the packaging
9114 system to define the architecture, ABI, and tuning of
9115 output packages.
9116 </para>
9117 </glossdef>
9118 </glossentry>
9119
9120 <glossentry id='var-TUNE_PKGARCH_tune'><glossterm>TUNE_PKGARCH_tune</glossterm>
9121 <glossdef>
9122 <para>
9123 The CPU or Application Binary Interface (ABI) specific
9124 tuning of the
9125 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
9126 </para>
9127
9128 <para>
9129 These tune-specific package architectures are defined in
9130 the machine include files.
9131 Here is an example of the "core2-32" tuning as used
9132 in the
9133 <filename>meta/conf/machine/include/tune-core2.inc</filename>
9134 file:
9135 <literallayout class='monospaced'>
9136 TUNE_PKGARCH_tune-core2-32 = "core2-32"
9137 </literallayout>
9138 </para>
9139 </glossdef>
9140 </glossentry>
9141
9142 <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
9143 <glossdef>
9144 <para>
9145 An underlying Application Binary Interface (ABI) used by
9146 a particular tuning in a given toolchain layer.
9147 Providers that use prebuilt libraries can use the
9148 <filename>TUNEABI</filename>,
9149 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
9150 and
9151 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
9152 variables to check compatibility of tunings against their
9153 selection of libraries.
9154 </para>
9155
9156 <para>
9157 If <filename>TUNEABI</filename> is undefined, then every
9158 tuning is allowed.
9159 See the
9160 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
9161 class to see how the variable is used.
9162 </para>
9163 </glossdef>
9164 </glossentry>
9165
9166 <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
9167 <glossdef>
9168 <para>
9169 If set, the OpenEmbedded system ignores the
9170 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
9171 variable.
9172 Providers that use prebuilt libraries can use the
9173 <filename>TUNEABI_OVERRIDE</filename>,
9174 <filename>TUNEABI_WHITELIST</filename>,
9175 and
9176 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
9177 variables to check compatibility of a tuning against their
9178 selection of libraries.
9179 </para>
9180
9181 <para>
9182 See the
9183 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
9184 class to see how the variable is used.
9185 </para>
9186 </glossdef>
9187 </glossentry>
9188
9189 <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
9190 <glossdef>
9191 <para>
9192 A whitelist of permissible
9193 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
9194 values.
9195 If <filename>TUNEABI_WHITELIST</filename> is not set,
9196 all tunes are allowed.
9197 Providers that use prebuilt libraries can use the
9198 <filename>TUNEABI_WHITELIST</filename>,
9199 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
9200 and <filename>TUNEABI</filename> variables to check
9201 compatibility of a tuning against their selection of
9202 libraries.
9203 </para>
9204
9205 <para>
9206 See the
9207 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
9208 class to see how the variable is used.
9209 </para>
9210 </glossdef>
9211 </glossentry>
9212
9213 <glossentry id='var-TUNECONFLICT'><glossterm>TUNECONFLICT[&lt;feature&gt;]</glossterm>
9214 <glossdef>
9215 <para>
9216 Specifies CPU or Application Binary Interface (ABI)
9217 tuning features that conflict with &gt;feature&lt;.
9218 </para>
9219
9220 <para>
9221 Known tuning conflicts are specified in the machine include
9222 files in the
9223 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
9224 Here is an example from the
9225 <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
9226 include file that lists the "o32" and "n64" features as
9227 conflicting with the "n32" feature:
9228 <literallayout class='monospaced'>
9229 TUNECONFLICTS[n32] = "o32 n64"
9230 </literallayout>
9231 </para>
9232 </glossdef>
9233 </glossentry>
9234
9235 <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[&lt;feature&gt;]</glossterm>
9236 <glossdef>
9237 <para>
9238 Specifies a valid CPU or Application Binary Interface (ABI)
9239 tuning feature.
9240 The specified feature is stored as a flag.
9241 Valid features are specified in the machine include files
9242 (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
9243 Here is an example from that file:
9244 <literallayout class='monospaced'>
9245 TUNEVALID[bigendian] = "Enable big-endian mode."
9246 </literallayout>
9247 See the machine include files in the
9248 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
9249 for these features.
9250 </para>
9251 </glossdef>
9252 </glossentry>
9253
9254 </glossdiv>
9255
9256 <glossdiv id='var-glossary-u'><title>U</title>
9257
9258 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
9259 <glossdef>
9260 <para>
9261 Configures the
9262 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
9263 and can also define
9264 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
9265 for individual cases.
9266 </para>
9267
9268 <para>
9269 Following is an example from the
9270 <filename>meta-fsl-arm</filename> layer.
9271 <literallayout class='monospaced'>
9272 UBOOT_CONFIG ??= "sd"
9273 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
9274 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
9275 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
9276 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
9277 </literallayout>
9278 In this example, "sd" is selected as the configuration
9279 of the possible four for the
9280 <filename>UBOOT_MACHINE</filename>.
9281 The "sd" configuration defines "mx6qsabreauto_config"
9282 as the value for <filename>UBOOT_MACHINE</filename>, while
9283 the "sdcard" specifies the
9284 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
9285 image.
9286 </para>
9287
9288 <para>
9289 For more information on how the
9290 <filename>UBOOT_CONFIG</filename> is handled, see the
9291 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
9292 class.
9293 </para>
9294 </glossdef>
9295 </glossentry>
9296
9297 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
9298 <glossdef>
9299 <para>
9300 Specifies the entry point for the U-Boot image.
9301 During U-Boot image creation, the
9302 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
9303 as a command-line parameter to the
9304 <filename>uboot-mkimage</filename> utility.
9305 </para>
9306 </glossdef>
9307 </glossentry>
9308
9309 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
9310 <glossdef>
9311 <para>
9312 Specifies the load address for the U-Boot image.
9313 During U-Boot image creation, the
9314 <filename>UBOOT_LOADADDRESS</filename> variable is passed
9315 as a command-line parameter to the
9316 <filename>uboot-mkimage</filename> utility.
9317 </para>
9318 </glossdef>
9319 </glossentry>
9320
9321 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
9322 <glossdef>
9323 <para>
9324 Appends a string to the name of the local version of the
9325 U-Boot image.
9326 For example, assuming the version of the U-Boot image
9327 built was "2013.10, the full version string reported by
9328 U-Boot would be "2013.10-yocto" given the following
9329 statement:
9330 <literallayout class='monospaced'>
9331 UBOOT_LOCALVERSION = "-yocto"
9332 </literallayout>
9333 </para>
9334 </glossdef>
9335 </glossentry>
9336
9337 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
9338 <glossdef>
9339 <para>
9340 Specifies the value passed on the
9341 <filename>make</filename> command line when building
9342 a U-Boot image.
9343 The value indicates the target platform configuration.
9344 You typically set this variable from the machine
9345 configuration file (i.e.
9346 <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
9347 </para>
9348
9349 <para>
9350 Please see the "Selection of Processor Architecture and
9351 Board Type" section in the U-Boot README for valid values
9352 for this variable.
9353 </para>
9354 </glossdef>
9355 </glossentry>
9356
9357 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
9358 <glossdef>
9359 <para>
9360 Specifies the target called in the
9361 <filename>Makefile</filename>.
9362 The default target is "all".
9363 </para>
9364 </glossdef>
9365 </glossentry>
9366
9367 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
9368 <glossdef>
9369 <para>
9370 Points to the generated U-Boot extension.
9371 For example, <filename>u-boot.sb</filename> has a
9372 <filename>.sb</filename> extension.
9373 </para>
9374
9375 <para>
9376 The default U-Boot extension is
9377 <filename>.bin</filename>
9378 </para>
9379 </glossdef>
9380 </glossentry>
9381
9382 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
9383 <glossdef>
9384 <para>
9385 Specifies the target used for building U-Boot.
9386 The target is passed directly as part of the "make" command
9387 (e.g. SPL and AIS).
9388 If you do not specifically set this variable, the
9389 OpenEmbedded build process passes and uses "all" for the
9390 target during the U-Boot building process.
9391 </para>
9392 </glossdef>
9393 </glossentry>
9394
9395 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
9396 <glossdef>
9397 <para>
9398 A list of classes to globally inherit.
9399 These classes are used by the OpenEmbedded build system
9400 to enable extra features (e.g.
9401 <filename>buildstats</filename>,
9402 <filename>image-mklibs</filename>, and so forth).
9403 </para>
9404
9405 <para>
9406 The default list is set in your
9407 <filename>local.conf</filename> file:
9408 <literallayout class='monospaced'>
9409 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
9410 </literallayout>
9411 For more information, see
9412 <filename>meta-yocto/conf/local.conf.sample</filename> in
9413 the
9414 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
9415 </para>
9416 </glossdef>
9417 </glossentry>
9418
9419 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
9420 <glossdef>
9421 <para>
9422 Forces the OpenEmbedded build system to produce an error
9423 if the user identification (<filename>uid</filename>) and
9424 group identification (<filename>gid</filename>) values
9425 are not defined in <filename>files/passwd</filename>
9426 and <filename>files/group</filename> files.
9427 </para>
9428
9429 <para>
9430 The default behavior for the build system is to dynamically
9431 apply <filename>uid</filename> and
9432 <filename>gid</filename> values.
9433 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
9434 variable is by default not set.
9435 If you plan on using statically assigned
9436 <filename>gid</filename> and <filename>uid</filename>
9437 values, you should set
9438 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
9439 your <filename>local.conf</filename> file as
9440 follows:
9441 <literallayout class='monospaced'>
9442 USERADD_ERROR_DYNAMIC = "1"
9443 </literallayout>
9444 Overriding the default behavior implies you are going to
9445 also take steps to set static <filename>uid</filename> and
9446 <filename>gid</filename> values through use of the
9447 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
9448 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
9449 and
9450 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
9451 variables.
9452 </para>
9453 </glossdef>
9454 </glossentry>
9455
9456 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
9457 <glossdef>
9458 <para>
9459 Specifies a password file to use for obtaining static
9460 group identification (<filename>gid</filename>) values
9461 when the OpenEmbedded build system adds a group to the
9462 system during package installation.
9463 </para>
9464
9465 <para>
9466 When applying static group identification
9467 (<filename>gid</filename>) values, the OpenEmbedded build
9468 system looks in
9469 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
9470 for a <filename>files/group</filename> file and then applies
9471 those <filename>uid</filename> values.
9472 Set the variable as follows in your
9473 <filename>local.conf</filename> file:
9474 <literallayout class='monospaced'>
9475 USERADD_GID_TABLES = "files/group"
9476 </literallayout>
9477 </para>
9478
9479 <note>
9480 Setting the
9481 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
9482 variable to "useradd-staticids" causes the build system
9483 to use static <filename>gid</filename> values.
9484 </note>
9485 </glossdef>
9486 </glossentry>
9487
9488 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
9489 <glossdef>
9490 <para>
9491 Specifies a password file to use for obtaining static
9492 user identification (<filename>uid</filename>) values
9493 when the OpenEmbedded build system adds a user to the
9494 system during package installation.
9495 </para>
9496
9497 <para>
9498 When applying static user identification
9499 (<filename>uid</filename>) values, the OpenEmbedded build
9500 system looks in
9501 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
9502 for a <filename>files/passwd</filename> file and then applies
9503 those <filename>uid</filename> values.
9504 Set the variable as follows in your
9505 <filename>local.conf</filename> file:
9506 <literallayout class='monospaced'>
9507 USERADD_UID_TABLES = "files/passwd"
9508 </literallayout>
9509 </para>
9510
9511 <note>
9512 Setting the
9513 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
9514 variable to "useradd-staticids" causes the build system
9515 to use static <filename>uid</filename> values.
9516 </note>
9517 </glossdef>
9518 </glossentry>
9519
9520 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
9521 <glossdef>
9522 <para>
9523 When a recipe inherits the
9524 <filename>useradd</filename> class, this variable
9525 specifies the individual packages within the recipe that
9526 require users and/or groups to be added.
9527 </para>
9528
9529 <para>
9530 You must set this variable if the recipe inherits the
9531 class.
9532 For example, the following enables adding a user for the
9533 main package in a recipe:
9534 <literallayout class='monospaced'>
9535 USERADD_PACKAGES = "${PN}"
9536 </literallayout>
9537 <note>
9538 If follows that if you are going to use the
9539 <filename>USERADD_PACKAGES</filename> variable,
9540 you need to set one or more of the
9541 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
9542 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
9543 or
9544 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
9545 variables.
9546 </note>
9547 </para>
9548
9549 </glossdef>
9550 </glossentry>
9551
9552 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
9553 <glossdef>
9554 <para>
9555 When a recipe inherits the
9556 <filename>useradd</filename> class, this variable
9557 specifies for a package what parameters should be passed
9558 to the <filename>useradd</filename> command
9559 if you wish to add a user to the system when the package
9560 is installed.
9561 </para>
9562
9563 <para>
9564 Here is an example from the <filename>dbus</filename>
9565 recipe:
9566 <literallayout class='monospaced'>
9567 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
9568 --no-create-home --shell /bin/false \
9569 --user-group messagebus"
9570 </literallayout>
9571 For information on the standard Linux shell command
9572 <filename>useradd</filename>, see
9573 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
9574 </para>
9575 </glossdef>
9576 </glossentry>
9577
9578 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
9579 <glossdef>
9580 <para>
9581 When set to "useradd-staticids", causes the
9582 OpenEmbedded build system to base all user and group
9583 additions on a static
9584 <filename>passwd</filename> and
9585 <filename>group</filename> files found in
9586 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
9587 </para>
9588
9589 <para>
9590 To use static user identification (<filename>uid</filename>)
9591 and group identification (<filename>gid</filename>)
9592 values, set the variable
9593 as follows in your <filename>local.conf</filename> file:
9594 <literallayout class='monospaced'>
9595 USERADDEXTENSION = "useradd-staticids"
9596 </literallayout>
9597 <note>
9598 Setting this variable to use static
9599 <filename>uid</filename> and <filename>gid</filename>
9600 values causes the OpenEmbedded build system to employ
9601 the
9602 <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link>
9603 class.
9604 </note>
9605 </para>
9606
9607 <para>
9608 If you use static <filename>uid</filename> and
9609 <filename>gid</filename> information, you must also
9610 specify the <filename>files/passwd</filename> and
9611 <filename>files/group</filename> files by setting the
9612 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
9613 and
9614 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
9615 variables.
9616 Additionally, you should also set the
9617 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
9618 variable.
9619 </para>
9620 </glossdef>
9621 </glossentry>
9622
9623 </glossdiv>
9624
9625<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
9626<!-- </glossdiv>-->
9627
9628 <glossdiv id='var-glossary-w'><title>W</title>
9629
9630 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
9631 <glossdef>
9632 <para>
9633 Specifies the quality assurance checks whose failures are
9634 reported as warnings by the OpenEmbedded build system.
9635 You set this variable in your distribution configuration
9636 file.
9637 For a list of the checks you can control with this variable,
9638 see the
9639 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
9640 section.
9641 </para>
9642 </glossdef>
9643 </glossentry>
9644
9645 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
9646 <glossdef>
9647 <para>
9648 The pathname of the work directory in which the OpenEmbedded
9649 build system builds a recipe.
9650 This directory is located within the
9651 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
9652 directory structure and is specific to the recipe being
9653 built and the system for which it is being built.
9654 </para>
9655
9656 <para>
9657 The <filename>WORKDIR</filename> directory is defined as
9658 follows:
9659 <literallayout class='monospaced'>
9660 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
9661 </literallayout>
9662 The actual directory depends on several things:
9663 <itemizedlist>
9664 <listitem><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>:
9665 The top-level build output directory</listitem>
9666 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
9667 The target system identifier</listitem>
9668 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
9669 The recipe name</listitem>
9670 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
9671 The epoch - (if
9672 <link linkend='var-PE'><filename>PE</filename></link>
9673 is not specified, which is usually the case for most
9674 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
9675 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
9676 The recipe version</listitem>
9677 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
9678 The recipe revision</listitem>
9679 </itemizedlist>
9680 </para>
9681
9682 <para>
9683 As an example, assume a Source Directory top-level folder
9684 name <filename>poky</filename>, a default Build Directory at
9685 <filename>poky/build</filename>, and a
9686 <filename>qemux86-poky-linux</filename> machine target
9687 system.
9688 Furthermore, suppose your recipe is named
9689 <filename>foo_1.3.0-r0.bb</filename>.
9690 In this case, the work directory the build system uses to
9691 build the package would be as follows:
9692 <literallayout class='monospaced'>
9693 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
9694 </literallayout>
9695 </para>
9696 </glossdef>
9697 </glossentry>
9698
9699 </glossdiv>
9700
9701<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
9702<!-- </glossdiv>-->
9703
9704<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
9705<!-- </glossdiv>-->
9706
9707<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
9708<!-- </glossdiv>-->
9709
9710</glossary>
9711</chapter>
9712<!--
9713vim: expandtab tw=80 ts=4
9714-->
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..686b48a
--- /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 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>:</emphasis>
96 A comprehensive guide to the BitBake tool.
97 In the
98 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
99 you can find the BitBake User Manual in the
100 <filename>bitbake/doc/bitbake-user-manual</filename> directory.
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..8bba42b
--- /dev/null
+++ b/documentation/ref-manual/technical-details.xml
@@ -0,0 +1,1419 @@
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-preferences'>Preferences</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, the
446 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
447 and
448 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
449 task outputs are still valid.
450 However, with a per-recipe approach, the build would not include the
451 <filename>.deb</filename> files.
452 Consequently, you would have to invalidate the whole build and rerun it.
453 Rerunning everything is not the best solution.
454 Also, in this case, the core must be "taught" much about specific tasks.
455 This methodology does not scale well and does not allow users to easily add new tasks
456 in layers or as external recipes without touching the packaged-staging core.
457 </para>
458 </section>
459
460 <section id='checksums'>
461 <title>Checksums (Signatures)</title>
462
463 <para>
464 The shared state code uses a checksum, which is a unique signature of a task's
465 inputs, to determine if a task needs to be run again.
466 Because it is a change in a task's inputs that triggers a rerun, the process
467 needs to detect all the inputs to a given task.
468 For shell tasks, this turns out to be fairly easy because
469 the build process generates a "run" shell script for each task and
470 it is possible to create a checksum that gives you a good idea of when
471 the task's data changes.
472 </para>
473
474 <para>
475 To complicate the problem, there are things that should not be included in
476 the checksum.
477 First, there is the actual specific build path of a given task -
478 the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
479 It does not matter if the work directory changes because it should not
480 affect the output for target packages.
481 Also, the build process has the objective of making native or cross packages relocatable.
482 The checksum therefore needs to exclude <filename>WORKDIR</filename>.
483 The simplistic approach for excluding the work directory is to set
484 <filename>WORKDIR</filename> to some fixed value and create the checksum
485 for the "run" script.
486 </para>
487
488 <para>
489 Another problem results from the "run" scripts containing functions that
490 might or might not get called.
491 The incremental build solution contains code that figures out dependencies
492 between shell functions.
493 This code is used to prune the "run" scripts down to the minimum set,
494 thereby alleviating this problem and making the "run" scripts much more
495 readable as a bonus.
496 </para>
497
498 <para>
499 So far we have solutions for shell scripts.
500 What about Python tasks?
501 The same approach applies even though these tasks are more difficult.
502 The process needs to figure out what variables a Python function accesses
503 and what functions it calls.
504 Again, the incremental build solution contains code that first figures out
505 the variable and function dependencies, and then creates a checksum for the data
506 used as the input to the task.
507 </para>
508
509 <para>
510 Like the <filename>WORKDIR</filename> case, situations exist where dependencies
511 should be ignored.
512 For these cases, you can instruct the build process to ignore a dependency
513 by using a line like the following:
514 <literallayout class='monospaced'>
515 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
516 </literallayout>
517 This example ensures that the
518 <link linkend='var-PACKAGE_ARCHS'><filename>PACKAGE_ARCHS</filename></link>
519 variable does not
520 depend on the value of
521 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
522 even if it does reference it.
523 </para>
524
525 <para>
526 Equally, there are cases where we need to add dependencies BitBake is not able to find.
527 You can accomplish this by using a line like the following:
528 <literallayout class='monospaced'>
529 PACKAGE_ARCHS[vardeps] = "MACHINE"
530 </literallayout>
531 This example explicitly adds the <filename>MACHINE</filename> variable as a
532 dependency for <filename>PACKAGE_ARCHS</filename>.
533 </para>
534
535 <para>
536 Consider a case with in-line Python, for example, where BitBake is not
537 able to figure out dependencies.
538 When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
539 produces output when it discovers something for which it cannot figure out
540 dependencies.
541 The Yocto Project team has currently not managed to cover those dependencies
542 in detail and is aware of the need to fix this situation.
543 </para>
544
545 <para>
546 Thus far, this section has limited discussion to the direct inputs into a task.
547 Information based on direct inputs is referred to as the "basehash" in the
548 code.
549 However, there is still the question of a task's indirect inputs - the
550 things that were already built and present in the
551 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
552 The checksum (or signature) for a particular task needs to add the hashes
553 of all the tasks on which the particular task depends.
554 Choosing which dependencies to add is a policy decision.
555 However, the effect is to generate a master checksum that combines the basehash
556 and the hashes of the task's dependencies.
557 </para>
558
559 <para>
560 At the code level, there are a variety of ways both the basehash and the
561 dependent task hashes can be influenced.
562 Within the BitBake configuration file, we can give BitBake some extra information
563 to help it construct the basehash.
564 The following statement effectively results in a list of global variable
565 dependency excludes - variables never included in any checksum:
566 <literallayout class='monospaced'>
567 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
568 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
569 USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
570 PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
571 CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
572 </literallayout>
573 The previous example excludes
574 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
575 since that variable is actually constructed as a path within
576 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
577 the whitelist.
578 </para>
579
580 <para>
581 The rules for deciding which hashes of dependent tasks to include through
582 dependency chains are more complex and are generally accomplished with a
583 Python function.
584 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
585 of this and also illustrates how you can insert your own policy into the system
586 if so desired.
587 This file defines the two basic signature generators <filename>OE-Core</filename>
588 uses: "OEBasic" and "OEBasicHash".
589 By default, there is a dummy "noop" signature handler enabled in BitBake.
590 This means that behavior is unchanged from previous versions.
591 <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
592 through this setting in the <filename>bitbake.conf</filename> file:
593 <literallayout class='monospaced'>
594 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
595 </literallayout>
596 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
597 "OEBasic" version but adds the task hash to the stamp files.
598 This results in any
599 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
600 change that changes the task hash, automatically
601 causing the task to be run again.
602 This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
603 values, and changes to Metadata automatically ripple across the build.
604 </para>
605
606 <para>
607 It is also worth noting that the end result of these signature generators is to
608 make some dependency and hash information available to the build.
609 This information includes:
610 <itemizedlist>
611 <listitem><para><filename>BB_BASEHASH_task-&lt;taskname&gt;</filename>:
612 The base hashes for each task in the recipe.
613 </para></listitem>
614 <listitem><para><filename>BB_BASEHASH_&lt;filename:taskname&gt;</filename>:
615 The base hashes for each dependent task.
616 </para></listitem>
617 <listitem><para><filename>BBHASHDEPS_&lt;filename:taskname&gt;</filename>:
618 The task dependencies for each task.
619 </para></listitem>
620 <listitem><para><filename>BB_TASKHASH</filename>:
621 The hash of the currently running task.
622 </para></listitem>
623 </itemizedlist>
624 </para>
625 </section>
626
627 <section id='shared-state'>
628 <title>Shared State</title>
629
630 <para>
631 Checksums and dependencies, as discussed in the previous section, solve half the
632 problem of supporting a shared state.
633 The other part of the problem is being able to use checksum information during the build
634 and being able to reuse or rebuild specific components.
635 </para>
636
637 <para>
638 The
639 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
640 class is a relatively generic implementation of how to "capture"
641 a snapshot of a given task.
642 The idea is that the build process does not care about the source of a task's output.
643 Output could be freshly built or it could be downloaded and unpacked from
644 somewhere - the build process does not need to worry about its origin.
645 </para>
646
647 <para>
648 There are two types of output, one is just about creating a directory
649 in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
650 A good example is the output of either
651 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
652 or
653 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
654 The other type of output occurs when a set of data is merged into a shared directory
655 tree such as the sysroot.
656 </para>
657
658 <para>
659 The Yocto Project team has tried to keep the details of the
660 implementation hidden in <filename>sstate</filename> class.
661 From a user's perspective, adding shared state wrapping to a task
662 is as simple as this
663 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
664 example taken from the
665 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
666 class:
667 <literallayout class='monospaced'>
668 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
669 SSTATETASKS += "do_deploy"
670 do_deploy[sstate-name] = "deploy"
671 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
672 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
673
674 python do_deploy_setscene () {
675 sstate_setscene(d)
676 }
677 addtask do_deploy_setscene
678 do_deploy[dirs] = "${DEPLOYDIR} ${B}"
679 </literallayout>
680 In this example, we add some extra flags to the task, a name field ("deploy"), an
681 input directory where the task sends data, and the output
682 directory where the data from the task should eventually be copied.
683 We also add a <filename>_setscene</filename> variant of the task and add the task
684 name to the <filename>SSTATETASKS</filename> list.
685 </para>
686
687 <para>
688 If you have a directory whose contents you need to preserve, you can do this with
689 a line like the following:
690 <literallayout class='monospaced'>
691 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
692 </literallayout>
693 This method, as well as the following example, also works for multiple directories.
694 <literallayout class='monospaced'>
695 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
696 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
697 do_package[sstate-lockfile] = "${PACKAGELOCK}"
698 </literallayout>
699 These methods also include the ability to take a lockfile when manipulating
700 shared state directory structures since some cases are sensitive to file
701 additions or removals.
702 </para>
703
704 <para>
705 Behind the scenes, the shared state code works by looking in
706 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
707 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
708 for shared state files.
709 Here is an example:
710 <literallayout class='monospaced'>
711 SSTATE_MIRRORS ?= "\
712 file://.* http://someserver.tld/share/sstate/PATH \n \
713 file://.* file:///some/local/dir/sstate/PATH"
714 </literallayout>
715 <note>
716 The shared state directory (<filename>SSTATE_DIR</filename>) is
717 organized into two-character subdirectories, where the subdirectory
718 names are based on the first two characters of the hash.
719 If the shared state directory structure for a mirror has the
720 same structure as <filename>SSTATE_DIR</filename>, you must
721 specify "PATH" as part of the URI to enable the build system
722 to map to the appropriate subdirectory.
723 </note>
724 </para>
725
726 <para>
727 The shared state package validity can be detected just by looking at the
728 filename since the filename contains the task checksum (or signature) as
729 described earlier in this section.
730 If a valid shared state package is found, the build process downloads it
731 and uses it to accelerate the task.
732 </para>
733
734 <para>
735 The build processes use the <filename>*_setscene</filename> tasks
736 for the task acceleration phase.
737 BitBake goes through this phase before the main execution code and tries
738 to accelerate any tasks for which it can find shared state packages.
739 If a shared state package for a task is available, the shared state
740 package is used.
741 This means the task and any tasks on which it is dependent are not
742 executed.
743 </para>
744
745 <para>
746 As a real world example, the aim is when building an IPK-based image,
747 only the
748 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
749 tasks would have their
750 shared state packages fetched and extracted.
751 Since the sysroot is not used, it would never get extracted.
752 This is another reason why a task-based approach is preferred over a
753 recipe-based approach, which would have to install the output from every task.
754 </para>
755 </section>
756
757 <section id='tips-and-tricks'>
758 <title>Tips and Tricks</title>
759
760 <para>
761 The code in the build system that supports incremental builds is not
762 simple code.
763 This section presents some tips and tricks that help you work around
764 issues related to shared state code.
765 </para>
766
767 <section id='debugging'>
768 <title>Debugging</title>
769
770 <para>
771 When things go wrong, debugging needs to be straightforward.
772 Because of this, the Yocto Project includes strong debugging
773 tools:
774 <itemizedlist>
775 <listitem><para>Whenever a shared state package is written out, so is a
776 corresponding <filename>.siginfo</filename> file.
777 This practice results in a pickled Python database of all
778 the metadata that went into creating the hash for a given shared state
779 package.</para></listitem>
780 <listitem><para>If you run BitBake with the <filename>--dump-signatures</filename>
781 (or <filename>-S</filename>) option, BitBake dumps out
782 <filename>.siginfo</filename> files in
783 the stamp directory for every task it would have executed instead of
784 building the specified target package.</para></listitem>
785 <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
786 can process <filename>.siginfo</filename> files.
787 If you specify one of these files, BitBake dumps out the dependency
788 information in the file.
789 If you specify two files, BitBake compares the two files and dumps out
790 the differences between the two.
791 This more easily helps answer the question of "What
792 changed between X and Y?"</para></listitem>
793 </itemizedlist>
794 </para>
795 </section>
796
797 <section id='invalidating-shared-state'>
798 <title>Invalidating Shared State</title>
799
800 <para>
801 The OpenEmbedded build system uses checksums and shared state
802 cache to avoid unnecessarily rebuilding tasks.
803 Collectively, this scheme is known as "shared state code."
804 </para>
805
806 <para>
807 As with all schemes, this one has some drawbacks.
808 It is possible that you could make implicit changes to your
809 code that the checksum calculations do not take into
810 account.
811 These implicit changes affect a task's output but do not trigger
812 the shared state code into rebuilding a recipe.
813 Consider an example during which a tool changes its output.
814 Assume that the output of <filename>rpmdeps</filename> changes.
815 The result of the change should be that all the
816 <filename>package</filename> and
817 <filename>package_write_rpm</filename> shared state cache
818 items become invalid.
819 However, because the change to the output is
820 external to the code and therefore implicit,
821 the associated shared state cache items do not become
822 invalidated.
823 In this case, the build process uses the cached items rather
824 than running the task again.
825 Obviously, these types of implicit changes can cause problems.
826 </para>
827
828 <para>
829 To avoid these problems during the build, you need to
830 understand the effects of any changes you make.
831 Realize that changes you make directly to a function
832 are automatically factored into the checksum calculation.
833 Thus, these explicit changes invalidate the associated area of
834 shared state cache.
835 However, you need to be aware of any implicit changes that
836 are not obvious changes to the code and could affect the output
837 of a given task.
838 </para>
839
840 <para>
841 When you identify an implicit change, you can easily take steps
842 to invalidate the cache and force the tasks to run.
843 The steps you can take are as simple as changing a function's
844 comments in the source code.
845 For example, to invalidate package shared state files, change
846 the comment statements of
847 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
848 or the comments of one of the functions it calls.
849 Even though the change is purely cosmetic, it causes the
850 checksum to be recalculated and forces the OpenEmbedded build
851 system to run the task again.
852 </para>
853
854 <note>
855 For an example of a commit that makes a cosmetic change to
856 invalidate shared state, see this
857 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
858 </note>
859 </section>
860 </section>
861</section>
862
863<section id='x32'>
864 <title>x32</title>
865
866 <para>
867 x32 is a processor-specific Application Binary Interface (psABI) for x86_64.
868 An ABI defines the calling conventions between functions in a processing environment.
869 The interface determines what registers are used and what the sizes are for various C data types.
870 </para>
871
872 <para>
873 Some processing environments prefer using 32-bit applications even when running
874 on Intel 64-bit platforms.
875 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
876 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
877 leaving the system underutilized.
878 Now consider the x86_64 psABI.
879 This ABI is newer and uses 64-bits for data sizes and program pointers.
880 The extra bits increase the footprint size of the programs, libraries,
881 and also increases the memory and file system size requirements.
882 Executing under the x32 psABI enables user programs to utilize CPU and system resources
883 more efficiently while keeping the memory footprint of the applications low.
884 Extra bits are used for registers but not for addressing mechanisms.
885 </para>
886
887 <section id='support'>
888 <title>Support</title>
889
890 <para>
891 This Yocto Project release supports the final specifications of x32
892 psABI.
893 Support for x32 psABI exists as follows:
894 <itemizedlist>
895 <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
896 </para></listitem>
897 <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
898 <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
899 <filename>core-image-sato</filename> images.</para></listitem>
900 </itemizedlist>
901 </para>
902 </section>
903
904 <section id='completing-x32'>
905 <title>Completing x32</title>
906
907 <para>
908 Future Plans for the x32 psABI in the Yocto Project include the following:
909 <itemizedlist>
910 <listitem><para>Enhance and fix the few remaining recipes so they
911 work with and support x32 toolchains.</para></listitem>
912 <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
913 <listitem><para>Support larger images.</para></listitem>
914 </itemizedlist>
915 </para>
916 </section>
917
918 <section id='using-x32-right-now'>
919 <title>Using x32 Right Now</title>
920
921 <para>
922 Follow these steps to use the x32 spABI:
923 <itemizedlist>
924 <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
925 machines by editing the <filename>conf/local.conf</filename> like this:
926 <literallayout class='monospaced'>
927 MACHINE = "qemux86-64"
928 DEFAULTTUNE = "x86-64-x32"
929 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
930 or 'INVALID'), True) or 'lib'}"
931 #MACHINE = "genericx86"
932 #DEFAULTTUNE = "core2-64-x32"
933 </literallayout></para></listitem>
934 <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
935 Here is an example:
936 <literallayout class='monospaced'>
937 $ bitbake core-image-sato
938 </literallayout></para></listitem>
939 <listitem><para>As usual, run your image using QEMU:
940 <literallayout class='monospaced'>
941 $ runqemu qemux86-64 core-image-sato
942 </literallayout></para></listitem>
943 </itemizedlist>
944 </para>
945 </section>
946</section>
947
948<section id="wayland">
949 <title>Wayland</title>
950
951 <para>
952 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink>
953 is a computer display server protocol that
954 provides a method for compositing window managers to communicate
955 directly with applications and video hardware and expects them to
956 communicate with input hardware using other libraries.
957 Using Wayland with supporting targets can result in better control
958 over graphics frame rendering than an application might otherwise
959 achieve.
960 </para>
961
962 <para>
963 The Yocto Project provides the Wayland protocol libraries and the
964 reference
965 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink>
966 compositor as part of its release.
967 This section describes what you need to do to implement Wayland and
968 use the compositor when building an image for a supporting target.
969 </para>
970
971 <section id="wayland-support">
972 <title>Support</title>
973
974 <para>
975 The Wayland protocol libraries and the reference Weston compositor
976 ship as integrated packages in the <filename>meta</filename> layer
977 of the
978 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
979 Specifically, you can find the recipes that build both Wayland
980 and Weston at <filename>meta/recipes-graphics/wayland</filename>.
981 </para>
982
983 <para>
984 You can build both the Wayland and Weston packages for use only
985 with targets that accept the
986 <ulink url='http://dri.freedesktop.org/wiki/'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
987 which is also known as Mesa DRI.
988 This implies that you cannot build and use the packages if your
989 target uses, for example, the
990 <trademark class='registered'>Intel</trademark> Embedded Media and
991 Graphics Driver (<trademark class='registered'>Intel</trademark>
992 EMGD) that overrides Mesa DRI.
993 </para>
994
995 <note>
996 Due to lack of EGL support, Weston 1.0.3 will not run directly on
997 the emulated QEMU hardware.
998 However, this version of Weston will run under X emulation without
999 issues.
1000 </note>
1001 </section>
1002
1003 <section id="enabling-wayland-in-an-image">
1004 <title>Enabling Wayland in an Image</title>
1005
1006 <para>
1007 To enable Wayland, you need to enable it to be built and enable
1008 it to be included in the image.
1009 </para>
1010
1011 <section id="enable-building">
1012 <title>Building</title>
1013
1014 <para>
1015 To cause Mesa to build the <filename>wayland-egl</filename>
1016 platform and Weston to build Wayland with Kernel Mode
1017 Setting
1018 (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
1019 support, include the "wayland" flag in the
1020 <link linkend="var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></link>
1021 statement in your <filename>local.conf</filename> file:
1022 <literallayout class='monospaced'>
1023 DISTRO_FEATURES_append = " wayland"
1024 </literallayout>
1025 </para>
1026
1027 <note>
1028 If X11 has been enabled elsewhere, Weston will build Wayland
1029 with X11 support
1030 </note>
1031 </section>
1032
1033 <section id="enable-installation-in-an-image">
1034 <title>Installing</title>
1035
1036 <para>
1037 To install the Wayland feature into an image, you must
1038 include the following
1039 <link linkend='var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></link>
1040 statement in your <filename>local.conf</filename> file:
1041 <literallayout class='monospaced'>
1042 CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
1043 </literallayout>
1044 </para>
1045 </section>
1046 </section>
1047
1048 <section id="running-weston">
1049 <title>Running Weston</title>
1050
1051 <para>
1052 To run Weston inside X11, enabling it as described earlier and
1053 building a Sato image is sufficient.
1054 If you are running your image under Sato, a Weston Launcher appears
1055 in the "Utility" category.
1056 </para>
1057
1058 <para>
1059 Alternatively, you can run Weston through the command-line
1060 interpretor (CLI), which is better suited for development work.
1061 To run Weston under the CLI, you need to do the following after
1062 your image is built:
1063 <orderedlist>
1064 <listitem><para>Run these commands to export
1065 <filename>XDG_RUNTIME_DIR</filename>:
1066 <literallayout class='monospaced'>
1067 mkdir -p /tmp/$USER-weston
1068 chmod 0700 /tmp/$USER-weston
1069 export XDG_RUNTIME_DIR=/tmp/$USER-weston
1070 </literallayout></para></listitem>
1071 <listitem><para>Launch Weston in the shell:
1072 <literallayout class='monospaced'>
1073 weston
1074 </literallayout></para></listitem>
1075 </orderedlist>
1076 </para>
1077 </section>
1078</section>
1079
1080<section id="licenses">
1081 <title>Licenses</title>
1082
1083 <para>
1084 This section describes the mechanism by which the OpenEmbedded build system
1085 tracks changes to licensing text.
1086 The section also describes how to enable commercially licensed recipes,
1087 which by default are disabled.
1088 </para>
1089
1090 <para>
1091 For information that can help you maintain compliance with various open
1092 source licensing during the lifecycle of the product, see the
1093 "<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
1094 in the Yocto Project Development Manual.
1095 </para>
1096
1097 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
1098 <title>Tracking License Changes</title>
1099
1100 <para>
1101 The license of an upstream project might change in the future.
1102 In order to prevent these changes going unnoticed, the
1103 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
1104 variable tracks changes to the license text. The checksums are validated at the end of the
1105 configure step, and if the checksums do not match, the build will fail.
1106 </para>
1107
1108 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
1109 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
1110
1111 <para>
1112 The <filename>LIC_FILES_CHKSUM</filename>
1113 variable contains checksums of the license text in the source code for the recipe.
1114 Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
1115 <literallayout class='monospaced'>
1116 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
1117 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
1118 file://licfile2.txt;endline=50;md5=zzzz \
1119 ..."
1120 </literallayout>
1121 </para>
1122
1123 <para>
1124 The build system uses the
1125 <filename><link linkend='var-S'>S</link></filename> variable as
1126 the default directory when searching files listed in
1127 <filename>LIC_FILES_CHKSUM</filename>.
1128 The previous example employs the default directory.
1129 </para>
1130
1131 <para>
1132 Consider this next example:
1133 <literallayout class='monospaced'>
1134 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
1135 md5=bb14ed3c4cda583abc85401304b5cd4e"
1136 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1137 </literallayout>
1138 </para>
1139
1140 <para>
1141 The first line locates a file in
1142 <filename>${S}/src/ls.c</filename>.
1143 The second line refers to a file in
1144 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
1145 </para>
1146 <para>
1147 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
1148 mandatory for all recipes, unless the
1149 <filename>LICENSE</filename> variable is set to "CLOSED".
1150 </para>
1151 </section>
1152
1153 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
1154 <title>Explanation of Syntax</title>
1155 <para>
1156 As mentioned in the previous section, the
1157 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
1158 important files that contain the license text for the source code.
1159 It is possible to specify a checksum for an entire file, or a specific section of a
1160 file (specified by beginning and ending line numbers with the "beginline" and "endline"
1161 parameters, respectively).
1162 The latter is useful for source files with a license notice header,
1163 README documents, and so forth.
1164 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
1165 first line of the file.
1166 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
1167 ends with the last line of the file.
1168 </para>
1169
1170 <para>
1171 The "md5" parameter stores the md5 checksum of the license text.
1172 If the license text changes in any way as compared to this parameter
1173 then a mismatch occurs.
1174 This mismatch triggers a build failure and notifies the developer.
1175 Notification allows the developer to review and address the license text changes.
1176 Also note that if a mismatch occurs during the build, the correct md5
1177 checksum is placed in the build log and can be easily copied to the recipe.
1178 </para>
1179
1180 <para>
1181 There is no limit to how many files you can specify using the
1182 <filename>LIC_FILES_CHKSUM</filename> variable.
1183 Generally, however, every project requires a few specifications for license tracking.
1184 Many projects have a "COPYING" file that stores the license information for all the source
1185 code files.
1186 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
1187 </para>
1188
1189 <tip>
1190 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
1191 error and displays the correct "md5" parameter value during the build.
1192 The correct parameter is also captured in the build log.
1193 </tip>
1194
1195 <tip>
1196 If the whole file contains only license text, you do not need to use the "beginline" and
1197 "endline" parameters.
1198 </tip>
1199 </section>
1200 </section>
1201
1202 <section id="enabling-commercially-licensed-recipes">
1203 <title>Enabling Commercially Licensed Recipes</title>
1204
1205 <para>
1206 By default, the OpenEmbedded build system disables
1207 components that have commercial or other special licensing
1208 requirements.
1209 Such requirements are defined on a
1210 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
1211 definition in the affected recipe.
1212 For instance, the
1213 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1214 recipe contains the following statement:
1215 <literallayout class='monospaced'>
1216 LICENSE_FLAGS = "commercial"
1217 </literallayout>
1218 Here is a slightly more complicated example that contains both an
1219 explicit recipe name and version (after variable expansion):
1220 <literallayout class='monospaced'>
1221 LICENSE_FLAGS = "license_${PN}_${PV}"
1222 </literallayout>
1223 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
1224 definition to be enabled and included in an image, it
1225 needs to have a matching entry in the global
1226 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
1227 typically defined in your <filename>local.conf</filename> file.
1228 For example, to enable
1229 the <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1230 package, you could add either the string
1231 "commercial_gst-plugins-ugly" or the more general string
1232 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
1233 See the
1234 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
1235 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
1236 Here is the example:
1237 <literallayout class='monospaced'>
1238 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
1239 </literallayout>
1240 Likewise, to additionally enable the package built from the recipe containing
1241 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
1242 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
1243 the following string would enable that package as well as
1244 the original <filename>gst-plugins-ugly</filename> package:
1245 <literallayout class='monospaced'>
1246 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
1247 </literallayout>
1248 As a convenience, you do not need to specify the complete license string
1249 in the whitelist for every package.
1250 You can use an abbreviated form, which consists
1251 of just the first portion or portions of the license string before
1252 the initial underscore character or characters.
1253 A partial string will match
1254 any license that contains the given string as the first
1255 portion of its license.
1256 For example, the following
1257 whitelist string will also match both of the packages
1258 previously mentioned as well as any other packages that have
1259 licenses starting with "commercial" or "license".
1260 <literallayout class='monospaced'>
1261 LICENSE_FLAGS_WHITELIST = "commercial license"
1262 </literallayout>
1263 </para>
1264
1265 <section id="license-flag-matching">
1266 <title>License Flag Matching</title>
1267
1268 <para>
1269 License flag matching allows you to control what recipes the
1270 OpenEmbedded build system includes in the build.
1271 Fundamentally, the build system attempts to match
1272 <filename>LICENSE_FLAGS</filename> strings found in
1273 recipes against <filename>LICENSE_FLAGS_WHITELIST</filename>
1274 strings found in the whitelist.
1275 A match causes the build system to include a recipe in the
1276 build, while failure to find a match causes the build system to
1277 exclude a recipe.
1278 </para>
1279
1280 <para>
1281 In general, license flag matching is simple.
1282 However, understanding some concepts will help you
1283 correctly and effectively use matching.
1284 </para>
1285
1286 <para>
1287 Before a flag
1288 defined by a particular recipe is tested against the
1289 contents of the whitelist, the expanded string
1290 <filename>_${PN}</filename> is appended to the flag.
1291 This expansion makes each <filename>LICENSE_FLAGS</filename>
1292 value recipe-specific.
1293 After expansion, the string is then matched against the
1294 whitelist.
1295 Thus, specifying
1296 <filename>LICENSE_FLAGS = "commercial"</filename>
1297 in recipe "foo", for example, results in the string
1298 <filename>"commercial_foo"</filename>.
1299 And, to create a match, that string must appear in the
1300 whitelist.
1301 </para>
1302
1303 <para>
1304 Judicious use of the <filename>LICENSE_FLAGS</filename>
1305 strings and the contents of the
1306 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
1307 allows you a lot of flexibility for including or excluding
1308 recipes based on licensing.
1309 For example, you can broaden the matching capabilities by
1310 using license flags string subsets in the whitelist.
1311 <note>When using a string subset, be sure to use the part of
1312 the expanded string that precedes the appended underscore
1313 character (e.g. <filename>usethispart_1.3</filename>,
1314 <filename>usethispart_1.4</filename>, and so forth).
1315 </note>
1316 For example, simply specifying the string "commercial" in
1317 the whitelist matches any expanded
1318 <filename>LICENSE_FLAGS</filename> definition that starts with
1319 the string "commercial" such as "commercial_foo" and
1320 "commercial_bar", which are the strings the build system
1321 automatically generates for hypothetical recipes named
1322 "foo" and "bar" assuming those recipes simply specify the
1323 following:
1324 <literallayout class='monospaced'>
1325 LICENSE_FLAGS = "commercial"
1326 </literallayout>
1327 Thus, you can choose to exhaustively
1328 enumerate each license flag in the whitelist and
1329 allow only specific recipes into the image, or
1330 you can use a string subset that causes a broader range of
1331 matches to allow a range of recipes into the image.
1332 </para>
1333
1334 <para>
1335 This scheme works even if the
1336 <filename>LICENSE_FLAGS</filename> string already
1337 has <filename>_${PN}</filename> appended.
1338 For example, the build system turns the license flag
1339 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
1340 match both the general "commercial" and the specific
1341 "commercial_1.2_foo" strings found in the whitelist, as
1342 expected.
1343 </para>
1344
1345 <para>
1346 Here are some other scenarios:
1347 <itemizedlist>
1348 <listitem><para>You can specify a versioned string in the
1349 recipe such as "commercial_foo_1.2" in a "foo" recipe.
1350 The build system expands this string to
1351 "commercial_foo_1.2_foo".
1352 Combine this license flag with a whitelist that has
1353 the string "commercial" and you match the flag along
1354 with any other flag that starts with the string
1355 "commercial".</para></listitem>
1356 <listitem><para>Under the same circumstances, you can
1357 use "commercial_foo" in the whitelist and the
1358 build system not only matches "commercial_foo_1.2" but
1359 also matches any license flag with the string
1360 "commercial_foo", regardless of the version.
1361 </para></listitem>
1362 <listitem><para>You can be very specific and use both the
1363 package and version parts in the whitelist (e.g.
1364 "commercial_foo_1.2") to specifically match a
1365 versioned recipe.</para></listitem>
1366 </itemizedlist>
1367 </para>
1368 </section>
1369
1370 <section id="other-variables-related-to-commercial-licenses">
1371 <title>Other Variables Related to Commercial Licenses</title>
1372
1373 <para>
1374 Other helpful variables related to commercial
1375 license handling exist and are defined in the
1376 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
1377 <literallayout class='monospaced'>
1378 COMMERCIAL_AUDIO_PLUGINS ?= ""
1379 COMMERCIAL_VIDEO_PLUGINS ?= ""
1380 COMMERCIAL_QT = ""
1381 </literallayout>
1382 If you want to enable these components, you can do so by making sure you have
1383 statements similar to the following
1384 in your <filename>local.conf</filename> configuration file:
1385 <literallayout class='monospaced'>
1386 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
1387 gst-plugins-ugly-mpegaudioparse"
1388 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
1389 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
1390 COMMERCIAL_QT ?= "qmmp"
1391 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
1392 </literallayout>
1393 Of course, you could also create a matching whitelist
1394 for those components using the more general "commercial"
1395 in the whitelist, but that would also enable all the
1396 other packages with <filename>LICENSE_FLAGS</filename> containing
1397 "commercial", which you may or may not want:
1398 <literallayout class='monospaced'>
1399 LICENSE_FLAGS_WHITELIST = "commercial"
1400 </literallayout>
1401 </para>
1402
1403 <para>
1404 Specifying audio and video plug-ins as part of the
1405 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
1406 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
1407 or commercial Qt components as part of
1408 the <filename>COMMERCIAL_QT</filename> statement (along
1409 with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
1410 plug-ins or components into built images, thus adding
1411 support for media formats or components.
1412 </para>
1413 </section>
1414 </section>
1415</section>
1416</chapter>
1417<!--
1418vim: expandtab tw=80 ts=4
1419-->
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
new file mode 100644
index 0000000..3c82d81
--- /dev/null
+++ b/documentation/ref-manual/usingpoky.xml
@@ -0,0 +1,891 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='usingpoky'>
6<title>Using the Yocto Project</title>
7
8 <para>
9 This chapter describes common usage for the Yocto Project.
10 The information is introductory in nature as other manuals in the Yocto Project
11 documentation set provide more details on how to use the Yocto Project.
12 </para>
13
14<section id='usingpoky-build'>
15 <title>Running a Build</title>
16
17 <para>
18 This section provides a summary of the build process and provides information
19 for less obvious aspects of the build process.
20 For general information on how to build an image using the OpenEmbedded build
21 system, see the
22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
23 section of the Yocto Project Quick Start.
24 </para>
25
26 <section id='build-overview'>
27 <title>Build Overview</title>
28
29 <para>
30 The first thing you need to do is set up the OpenEmbedded build
31 environment by sourcing an environment setup script
32 (i.e.
33 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
34 or
35 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
36 Here is an example:
37 <literallayout class='monospaced'>
38 $ source &OE_INIT_FILE; [&lt;build_dir&gt;]
39 </literallayout>
40 </para>
41
42 <para>
43 The <filename>build_dir</filename> argument is optional and specifies the directory the
44 OpenEmbedded build system uses for the build -
45 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
46 If you do not specify a Build Directory, it defaults to a directory
47 named <filename>build</filename> in your current working directory.
48 A common practice is to use a different Build Directory for different targets.
49 For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
50 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
51 </para>
52
53 <para>
54 Once the build environment is set up, you can build a target using:
55 <literallayout class='monospaced'>
56 $ bitbake &lt;target&gt;
57 </literallayout>
58 </para>
59
60 <para>
61 The <filename>target</filename> is the name of the recipe you want to build.
62 Common targets are the images in <filename>meta/recipes-core/images</filename>,
63 <filename>meta/recipes-sato/images</filename>, etc. all found in the
64 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
65 Or, the target can be the name of a recipe for a specific piece of software such as
66 BusyBox.
67 For more details about the images the OpenEmbedded build system supports, see the
68 "<link linkend="ref-images">Images</link>" chapter.
69 </para>
70
71 <note>
72 Building an image without GNU General Public License Version 3 (GPLv3) components
73 is supported for only minimal and base images.
74 See the "<link linkend='ref-images'>Images</link>" chapter for more information.
75 </note>
76 </section>
77
78 <section id='building-an-image-using-gpl-components'>
79 <title>Building an Image Using GPL Components</title>
80
81 <para>
82 When building an image using GPL components, you need to maintain your original
83 settings and not switch back and forth applying different versions of the GNU
84 General Public License.
85 If you rebuild using different versions of GPL, dependency errors might occur
86 due to some components not being rebuilt.
87 </para>
88 </section>
89</section>
90
91<section id='usingpoky-install'>
92 <title>Installing and Using the Result</title>
93
94 <para>
95 Once an image has been built, it often needs to be installed.
96 The images and kernels built by the OpenEmbedded build system are placed in the
97 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
98 <filename class="directory">tmp/deploy/images</filename>.
99 For information on how to run pre-built images such as <filename>qemux86</filename>
100 and <filename>qemuarm</filename>, see the
101 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
102 section in the Yocto Project Quick Start.
103 For information about how to install these images, see the documentation for your
104 particular board or machine.
105 </para>
106</section>
107
108<section id='usingpoky-debugging'>
109 <title>Debugging Build Failures</title>
110
111 <para>
112 The exact method for debugging build failures depends on the nature of
113 the problem and on the system's area from which the bug originates.
114 Standard debugging practices such as comparison against the last
115 known working version with examination of the changes and the
116 re-application of steps to identify the one causing the problem are
117 valid for the Yocto Project just as they are for any other system.
118 Even though it is impossible to detail every possible potential failure,
119 this section provides some general tips to aid in debugging.
120 </para>
121
122 <para>
123 A useful feature for debugging is the error reporting tool.
124 Configuring the Yocto Project to use this tool causes the
125 OpenEmbedded build system to produce error reporting commands as
126 part of the console output.
127 You can enter the commands after the build completes
128 to log error information
129 into a common database, that can help you figure out what might be
130 going wrong.
131 For information on how to enable and use this feature, see the
132 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>Using the Error Reporting Tool</ulink>"
133 section in the Yocto Project Development Manual.
134 </para>
135
136 <para>
137 For discussions on debugging, see the
138 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
139 and
140 "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working within Eclipse</ulink>"
141 sections in the Yocto Project Development Manual.
142 </para>
143
144 <note>
145 The remainder of this section presents many examples of the
146 <filename>bitbake</filename> command.
147 You can learn about BitBake by reading the
148 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
149 </note>
150
151
152 <section id='usingpoky-debugging-taskfailures'>
153 <title>Task Failures</title>
154
155 <para>The log file for shell tasks is available in
156 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
157 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
158 machine (<filename>qemux86</filename>) might be
159 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>.
160 To see what
161 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
162 runs to generate that log, look at the corresponding
163 <filename>run.do_taskname.pid</filename> file located in the same directory.
164 </para>
165
166 <para>
167 Presently, the output from Python tasks is sent directly to the console.
168 </para>
169 </section>
170
171 <section id='usingpoky-debugging-taskrunning'>
172 <title>Running Specific Tasks</title>
173
174 <para>
175 Any given package consists of a set of tasks.
176 The standard BitBake behavior in most cases is:
177 <filename>do_fetch</filename>,
178 <filename>do_unpack</filename>,
179 <filename>do_patch</filename>, <filename>do_configure</filename>,
180 <filename>do_compile</filename>, <filename>do_install</filename>,
181 <filename>do_package</filename>,
182 <filename>do_package_write</filename>, and
183 <filename>do_build</filename>.
184 The default task is <filename>do_build</filename> and any tasks
185 on which it depends build first.
186 Some tasks, such as <filename>do_devshell</filename>, are not part
187 of the default build chain.
188 If you wish to run a task that is not part of the default build
189 chain, you can use the <filename>-c</filename> option in BitBake.
190 Here is an example:
191 <literallayout class='monospaced'>
192 $ bitbake matchbox-desktop -c devshell
193 </literallayout>
194 </para>
195
196 <para>
197 If you wish to rerun a task, use the <filename>-f</filename> force
198 option.
199 For example, the following sequence forces recompilation after
200 changing files in the work directory.
201 <literallayout class='monospaced'>
202 $ bitbake matchbox-desktop
203 .
204 .
205 [make some changes to the source code in the work directory]
206 .
207 .
208 $ bitbake matchbox-desktop -c compile -f
209 $ bitbake matchbox-desktop
210 </literallayout>
211 </para>
212
213 <para>
214 This sequence first builds and then recompiles
215 <filename>matchbox-desktop</filename>.
216 The last command reruns all tasks (basically the packaging tasks)
217 after the compile.
218 BitBake recognizes that the <filename>do_compile</filename>
219 task was rerun and therefore understands that the other tasks
220 also need to be run again.
221 </para>
222
223 <para>
224 You can view a list of tasks in a given package by running the
225 <filename>do_listtasks</filename> task as follows:
226 <literallayout class='monospaced'>
227 $ bitbake matchbox-desktop -c listtasks
228 </literallayout>
229 The results appear as output to the console and are also in the
230 file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
231 </para>
232 </section>
233
234 <section id='usingpoky-debugging-dependencies'>
235 <title>Dependency Graphs</title>
236
237 <para>
238 Sometimes it can be hard to see why BitBake wants to build
239 other packages before building a given package you have specified.
240 The <filename>bitbake -g &lt;targetname&gt;</filename> command
241 creates the <filename>pn-buildlist</filename>,
242 <filename>pn-depends.dot</filename>,
243 <filename>package-depends.dot</filename>, and
244 <filename>task-depends.dot</filename> files in the current
245 directory.
246 These files show what will be built and the package and task
247 dependencies, which are useful for debugging problems.
248 You can use the
249 <filename>bitbake -g -u depexp &lt;targetname&gt;</filename>
250 command to display the results in a more human-readable form.
251 </para>
252 </section>
253
254 <section id='usingpoky-debugging-bitbake'>
255 <title>General BitBake Problems</title>
256
257 <para>
258 You can see debug output from BitBake by using the <filename>-D</filename> option.
259 The debug output gives more information about what BitBake
260 is doing and the reason behind it.
261 Each <filename>-D</filename> option you use increases the logging level.
262 The most common usage is <filename>-DDD</filename>.
263 </para>
264
265 <para>
266 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
267 BitBake chose a certain version of a package or why BitBake
268 picked a certain provider.
269 This command could also help you in a situation where you think BitBake did something
270 unexpected.
271 </para>
272 </section>
273
274 <section id='development-host-system-issues'>
275 <title>Development Host System Issues</title>
276
277 <para>
278 Sometimes issues on the host development system can cause your
279 build to fail.
280 Following are known, host-specific problems.
281 Be sure to always consult the
282 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
283 for a look at all release-related issues.
284 <itemizedlist>
285 <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>:
286 If your development host system has the unpatched
287 <filename>GNU Make 3.82</filename>,
288 the
289 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
290 task fails for <filename>eglibc-initial</filename> during
291 the build.</para>
292 <para>Typically, every distribution that ships
293 <filename>GNU Make 3.82</filename> as
294 the default already has the patched version.
295 However, some distributions, such as Debian, have
296 <filename>GNU Make 3.82</filename> as an option, which
297 is unpatched.
298 You will see this error on these types of distributions.
299 Switch to <filename>GNU Make 3.81</filename> or patch
300 your <filename>make</filename> to solve the problem.
301 </para></listitem>
302 </itemizedlist>
303 </para>
304 </section>
305
306 <section id='usingpoky-debugging-buildfile'>
307 <title>Building with No Dependencies</title>
308 <para>
309 To build a specific recipe (<filename>.bb</filename> file),
310 you can use the following command form:
311 <literallayout class='monospaced'>
312 $ bitbake -b &lt;somepath/somerecipe.bb&gt;
313 </literallayout>
314 This command form does not check for dependencies.
315 Consequently, you should use it
316 only when you know existing dependencies have been met.
317 <note>
318 You can also specify fragments of the filename.
319 In this case, BitBake checks for a unique match.
320 </note>
321 </para>
322 </section>
323
324 <section id='usingpoky-debugging-variables'>
325 <title>Variables</title>
326 <para>
327 You can use the <filename>-e</filename> BitBake option to
328 display the parsing environment for a configuration.
329 The following displays the general parsing environment:
330 <literallayout class='monospaced'>
331 $ bitbake -e
332 </literallayout>
333 This next example shows the parsing environment for a specific
334 recipe:
335 <literallayout class='monospaced'>
336 $ bitbake -e &lt;recipename&gt;
337 </literallayout>
338 </para>
339 </section>
340
341 <section id='recipe-logging-mechanisms'>
342 <title>Recipe Logging Mechanisms</title>
343 <para>
344 Best practices exist while writing recipes that both log build progress and
345 act on build conditions such as warnings and errors.
346 Both Python and Bash language bindings exist for the logging mechanism:
347 <itemizedlist>
348 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
349 supports several loglevels: <filename>bb.fatal</filename>,
350 <filename>bb.error</filename>, <filename>bb.warn</filename>,
351 <filename>bb.note</filename>, <filename>bb.plain</filename>,
352 and <filename>bb.debug</filename>.</para></listitem>
353 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
354 of loglevels exist and are accessed with a similar syntax:
355 <filename>bbfatal</filename>, <filename>bberror</filename>,
356 <filename>bbwarn</filename>, <filename>bbnote</filename>,
357 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
358 </itemizedlist>
359 </para>
360
361 <para>
362 For guidance on how logging is handled in both Python and Bash recipes, see the
363 <filename>logging.bbclass</filename> file in the
364 <filename>meta/classes</filename> folder of the
365 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
366 </para>
367
368 <section id='logging-with-python'>
369 <title>Logging With Python</title>
370 <para>
371 When creating recipes using Python and inserting code that handles build logs,
372 keep in mind the goal is to have informative logs while keeping the console as
373 "silent" as possible.
374 Also, if you want status messages in the log, use the "debug" loglevel.
375 </para>
376
377 <para>
378 Following is an example written in Python.
379 The code handles logging for a function that determines the
380 number of tasks needed to be run.
381 See the
382 "<link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>"
383 section for additional information:
384 <literallayout class='monospaced'>
385 python do_listtasks() {
386 bb.debug(2, "Starting to figure out the task list")
387 if noteworthy_condition:
388 bb.note("There are 47 tasks to run")
389 bb.debug(2, "Got to point xyz")
390 if warning_trigger:
391 bb.warn("Detected warning_trigger, this might be a problem later.")
392 if recoverable_error:
393 bb.error("Hit recoverable_error, you really need to fix this!")
394 if fatal_error:
395 bb.fatal("fatal_error detected, unable to print the task list")
396 bb.plain("The tasks present are abc")
397 bb.debug(2, "Finished figuring out the tasklist")
398 }
399 </literallayout>
400 </para>
401 </section>
402
403 <section id='logging-with-bash'>
404 <title>Logging With Bash</title>
405 <para>
406 When creating recipes using Bash and inserting code that handles build
407 logs, you have the same goals - informative with minimal console output.
408 The syntax you use for recipes written in Bash is similar to that of
409 recipes written in Python described in the previous section.
410 </para>
411
412 <para>
413 Following is an example written in Bash.
414 The code logs the progress of the <filename>do_my_function</filename> function.
415 <literallayout class='monospaced'>
416 do_my_function() {
417 bbdebug 2 "Running do_my_function"
418 if [ exceptional_condition ]; then
419 bbnote "Hit exceptional_condition"
420 fi
421 bbdebug 2 "Got to point xyz"
422 if [ warning_trigger ]; then
423 bbwarn "Detected warning_trigger, this might cause a problem later."
424 fi
425 if [ recoverable_error ]; then
426 bberror "Hit recoverable_error, correcting"
427 fi
428 if [ fatal_error ]; then
429 bbfatal "fatal_error detected"
430 fi
431 bbdebug 2 "Completed do_my_function"
432 }
433 </literallayout>
434 </para>
435 </section>
436 </section>
437
438 <section id='usingpoky-debugging-others'>
439 <title>Other Tips</title>
440
441 <para>
442 Here are some other tips that you might find useful:
443 <itemizedlist>
444 <listitem><para>When adding new packages, it is worth watching for
445 undesirable items making their way into compiler command lines.
446 For example, you do not want references to local system files like
447 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
448 </para></listitem>
449 <listitem><para>If you want to remove the <filename>psplash</filename>
450 boot splashscreen,
451 add <filename>psplash=false</filename> to the kernel command line.
452 Doing so prevents <filename>psplash</filename> from loading
453 and thus allows you to see the console.
454 It is also possible to switch out of the splashscreen by
455 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
456 </para></listitem>
457 </itemizedlist>
458 </para>
459 </section>
460</section>
461
462<section id='maintaining-build-output-quality'>
463 <title>Maintaining Build Output Quality</title>
464
465 <para>
466 Many factors can influence the quality of a build.
467 For example, if you upgrade a recipe to use a new version of an upstream software
468 package or you experiment with some new configuration options, subtle changes
469 can occur that you might not detect until later.
470 Consider the case where your recipe is using a newer version of an upstream package.
471 In this case, a new version of a piece of software might introduce an optional
472 dependency on another library, which is auto-detected.
473 If that library has already been built when the software is building,
474 the software will link to the built library and that library will be pulled
475 into your image along with the new software even if you did not want the
476 library.
477 </para>
478
479 <para>
480 The
481 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
482 class exists to help you maintain
483 the quality of your build output.
484 You can use the class to highlight unexpected and possibly unwanted
485 changes in the build output.
486 When you enable build history, it records information about the contents of
487 each package and image and then commits that information to a local Git
488 repository where you can examine the information.
489 </para>
490
491 <para>
492 The remainder of this section describes the following:
493 <itemizedlist>
494 <listitem><para>How you can enable and disable
495 build history</para></listitem>
496 <listitem><para>How to understand what the build history contains
497 </para></listitem>
498 <listitem><para>How to limit the information used for build history
499 </para></listitem>
500 <listitem><para>How to examine the build history from both a
501 command-line and web interface</para></listitem>
502 </itemizedlist>
503 </para>
504
505 <section id='enabling-and-disabling-build-history'>
506 <title>Enabling and Disabling Build History</title>
507
508 <para>
509 Build history is disabled by default.
510 To enable it, add the following <filename>INHERIT</filename>
511 statement and set the
512 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
513 variable to "1" at the end of your
514 <filename>conf/local.conf</filename> file found in the
515 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
516 <literallayout class='monospaced'>
517 INHERIT += "buildhistory"
518 BUILDHISTORY_COMMIT = "1"
519 </literallayout>
520 Enabling build history as previously described
521 causes the build process to collect build
522 output information and commit it to a local
523 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
524 <note>
525 Enabling build history increases your build times slightly,
526 particularly for images, and increases the amount of disk
527 space used during the build.
528 </note>
529 </para>
530
531 <para>
532 You can disable build history by removing the previous statements
533 from your <filename>conf/local.conf</filename> file.
534 </para>
535 </section>
536
537 <section id='understanding-what-the-build-history-contains'>
538 <title>Understanding What the Build History Contains</title>
539
540 <para>
541 Build history information is kept in
542 <filename>$</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>/buildhistory</filename>
543 in the Build Directory as defined by the
544 <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link>
545 variable.
546 The following is an example abbreviated listing:
547 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
548 </para>
549
550 <para>
551 At the top level, there is a <filename>metadata-revs</filename> file
552 that lists the revisions of the repositories for the layers enabled
553 when the build was produced.
554 The rest of the data splits into separate
555 <filename>packages</filename>, <filename>images</filename> and
556 <filename>sdk</filename> directories, the contents of which are
557 described below.
558 </para>
559
560 <section id='build-history-package-information'>
561 <title>Build History Package Information</title>
562
563 <para>
564 The history for each package contains a text file that has
565 name-value pairs with information about the package.
566 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
567 contains the following:
568 <literallayout class='monospaced'>
569 PV = 1.19.3
570 PR = r3
571 RDEPENDS = update-rc.d eglibc (>= 2.13)
572 RRECOMMENDS = busybox-syslog busybox-udhcpc
573 PKGSIZE = 564701
574 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
575 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
576 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
577 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
578 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
579 </literallayout>
580 Most of these name-value pairs correspond to variables used
581 to produce the package.
582 The exceptions are <filename>FILELIST</filename>, which is the
583 actual list of files in the package, and
584 <filename>PKGSIZE</filename>, which is the total size of files
585 in the package in bytes.
586 </para>
587
588 <para>
589 There is also a file corresponding to the recipe from which the
590 package came (e.g.
591 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
592 <literallayout class='monospaced'>
593 PV = 1.19.3
594 PR = r3
595 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
596 virtual/libc update-rc.d-native
597 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
598 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
599 busybox-staticdev busybox-locale
600 </literallayout>
601 </para>
602
603 <para>
604 Finally, for those recipes fetched from a version control
605 system (e.g., Git), a file exists that lists source revisions
606 that are specified in the recipe and lists the actual revisions
607 used during the build.
608 Listed and actual revisions might differ when
609 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
610 is set to
611 <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>.
612 Here is an example assuming
613 <filename>buildhistory/packages/emenlow-poky-linux/linux-yocto/latest_srcrev</filename>):
614 <literallayout class='monospaced'>
615 # SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
616 SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
617 # SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
618 SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
619 # SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
620 SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
621 </literallayout>
622 You can use the <filename>buildhistory-collect-srcrevs</filename>
623 command to collect the stored <filename>SRCREV</filename> values
624 from build history and report them in a format suitable for use in
625 global configuration (e.g., <filename>local.conf</filename>
626 or a distro include file) to override floating
627 <filename>AUTOREV</filename> values to a fixed set of revisions.
628 Here is some example output from this command:
629 <literallayout class='monospaced'>
630 # emenlow-poky-linux
631 SRCREV_machine_pn-linux-yocto = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
632 SRCREV_emgd_pn-linux-yocto = "caea08c988e0f41103bbe18eafca20348f95da02"
633 SRCREV_meta_pn-linux-yocto = "c2ed0f16fdec628242a682897d5d86df4547cf24"
634 # core2-poky-linux
635 SRCREV_pn-kmod = "62081c0f68905b22f375156d4532fd37fa5c8d33"
636 SRCREV_pn-blktrace = "d6918c8832793b4205ed3bfede78c2f915c23385"
637 SRCREV_pn-opkg = "649"
638 </literallayout>
639 <note>
640 Here are some notes on using the
641 <filename>buildhistory-collect-srcrevs</filename> command:
642 <itemizedlist>
643 <listitem><para>By default, only values where the
644 <filename>SRCREV</filename> was
645 not hardcoded (usually when <filename>AUTOREV</filename>
646 was used) are reported.
647 Use the <filename>-a</filename> option to see all
648 <filename>SRCREV</filename> values.
649 </para></listitem>
650 <listitem><para>The output statements might not have any effect
651 if overrides are applied elsewhere in the build system
652 configuration.
653 Use the <filename>-f</filename> option to add the
654 <filename>forcevariable</filename> override to each output line
655 if you need to work around this restriction.
656 </para></listitem>
657 <listitem><para>The script does apply special handling when
658 building for multiple machines.
659 However, the script does place a
660 comment before each set of values that specifies
661 which triplet to which they belong as shown above
662 (e.g., <filename>emenlow-poky-linux</filename>).
663 </para></listitem>
664 </itemizedlist>
665 </note>
666 </para>
667 </section>
668
669 <section id='build-history-image-information'>
670 <title>Build History Image Information</title>
671
672 <para>
673 The files produced for each image are as follows:
674 <itemizedlist>
675 <listitem><para><filename>image-files:</filename>
676 A directory containing selected files from the root
677 filesystem.
678 The files are defined by
679 <link linkend='var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></link>.
680 </para></listitem>
681 <listitem><para><filename>build-id:</filename>
682 Human-readable information about the build configuration
683 and metadata source revisions.</para></listitem>
684 <listitem><para><filename>*.dot:</filename>
685 Dependency graphs for the image that are
686 compatible with <filename>graphviz</filename>.
687 </para></listitem>
688 <listitem><para><filename>files-in-image.txt:</filename>
689 A list of files in the image with permissions,
690 owner, group, size, and symlink information.
691 </para></listitem>
692 <listitem><para><filename>image-info.txt:</filename>
693 A text file containing name-value pairs with information
694 about the image.
695 See the following listing example for more information.
696 </para></listitem>
697 <listitem><para><filename>installed-package-names.txt:</filename>
698 A list of installed packages by name only.</para></listitem>
699 <listitem><para><filename>installed-package-sizes.txt:</filename>
700 A list of installed packages ordered by size.
701 </para></listitem>
702 <listitem><para><filename>installed-packages.txt:</filename>
703 A list of installed packages with full package
704 filenames.</para></listitem>
705 </itemizedlist>
706 <note>
707 Installed package information is able to be gathered and
708 produced even if package management is disabled for the final
709 image.
710 </note>
711 </para>
712
713 <para>
714 Here is an example of <filename>image-info.txt</filename>:
715 <literallayout class='monospaced'>
716 DISTRO = poky
717 DISTRO_VERSION = 1.1+snapshot-20120207
718 USER_CLASSES = image-mklibs image-prelink
719 IMAGE_CLASSES = image_types
720 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
721 package-management ssh-server-dropbear package-management
722 IMAGE_LINGUAS = en-us en-gb
723 IMAGE_INSTALL = task-core-boot task-base-extended
724 BAD_RECOMMENDATIONS =
725 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
726 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
727 IMAGESIZE = 171816
728 </literallayout>
729 Other than <filename>IMAGESIZE</filename>, which is the
730 total size of the files in the image in Kbytes, the
731 name-value pairs are variables that may have influenced the
732 content of the image.
733 This information is often useful when you are trying to determine
734 why a change in the package or file listings has occurred.
735 </para>
736 </section>
737
738 <section id='using-build-history-to-gather-image-information-only'>
739 <title>Using Build History to Gather Image Information Only</title>
740
741 <para>
742 As you can see, build history produces image information,
743 including dependency graphs, so you can see why something
744 was pulled into the image.
745 If you are just interested in this information and not
746 interested in collecting specific package or SDK information,
747 you can enable writing only image information without
748 any history by adding the following to your
749 <filename>conf/local.conf</filename> file found in the
750 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
751 <literallayout class='monospaced'>
752 INHERIT += "buildhistory"
753 BUILDHISTORY_COMMIT = "0"
754 BUILDHISTORY_FEATURES = "image"
755 </literallayout>
756 Here, you set the
757 <link linkend='var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></link>
758 variable to use the image feature only.
759 </para>
760 </section>
761
762 <section id='build-history-sdk-information'>
763 <title>Build History SDK Information</title>
764 <para>
765 Build history collects similar information on the contents
766 of SDKs (e.g. <filename>meta-toolchain</filename>
767 or <filename>bitbake -c populate_sdk imagename</filename>)
768 as compared to information it collects for images.
769 The following list shows the files produced for each SDK:
770 <itemizedlist>
771 <listitem><para><filename>files-in-sdk.txt:</filename>
772 A list of files in the SDK with permissions,
773 owner, group, size, and symlink information.
774 This list includes both the host and target parts
775 of the SDK.
776 </para></listitem>
777 <listitem><para><filename>sdk-info.txt:</filename>
778 A text file containing name-value pairs with information
779 about the SDK.
780 See the following listing example for more information.
781 </para></listitem>
782 <listitem><para>The following information appears under
783 each of the <filename>host</filename>
784 and <filename>target</filename> directories
785 for the portions of the SDK that run on the host and
786 on the target, respectively:
787 <itemizedlist>
788 <listitem><para><filename>depends.dot:</filename>
789 Dependency graph for the SDK that is
790 compatible with <filename>graphviz</filename>.
791 </para></listitem>
792 <listitem><para><filename>installed-package-names.txt:</filename>
793 A list of installed packages by name only.
794 </para></listitem>
795 <listitem><para><filename>installed-package-sizes.txt:</filename>
796 A list of installed packages ordered by size.
797 </para></listitem>
798 <listitem><para><filename>installed-packages.txt:</filename>
799 A list of installed packages with full package
800 filenames.</para></listitem>
801 </itemizedlist>
802 </para></listitem>
803 </itemizedlist>
804 </para>
805
806 <para>
807 Here is an example of <filename>sdk-info.txt</filename>:
808 <literallayout class='monospaced'>
809 DISTRO = poky
810 DISTRO_VERSION = 1.3+snapshot-20130327
811 SDK_NAME = poky-eglibc-i686-arm
812 SDK_VERSION = 1.3+snapshot
813 SDKMACHINE =
814 SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
815 BAD_RECOMMENDATIONS =
816 SDKSIZE = 352712
817 </literallayout>
818 Other than <filename>SDKSIZE</filename>, which is the
819 total size of the files in the SDK in Kbytes, the
820 name-value pairs are variables that might have influenced the
821 content of the SDK.
822 This information is often useful when you are trying to
823 determine why a change in the package or file listings
824 has occurred.
825 </para>
826 </section>
827
828 <section id='examining-build-history-information'>
829 <title>Examining Build History Information</title>
830
831 <para>
832 You can examine build history output from the command line or
833 from a web interface.
834 </para>
835
836 <para>
837 To see any changes that have occurred (assuming you have
838 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT = "1"</filename></link>),
839 you can simply
840 use any Git command that allows you to view the history of
841 a repository.
842 Here is one method:
843 <literallayout class='monospaced'>
844 $ git log -p
845 </literallayout>
846 You need to realize, however, that this method does show
847 changes that are not significant (e.g. a package's size
848 changing by a few bytes).
849 </para>
850
851 <para>
852 A command-line tool called <filename>buildhistory-diff</filename>
853 does exist, though, that queries the Git repository and prints just
854 the differences that might be significant in human-readable form.
855 Here is an example:
856 <literallayout class='monospaced'>
857 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
858 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
859 /etc/anotherpkg.conf was added
860 /sbin/anotherpkg was added
861 * (installed-package-names.txt):
862 * anotherpkg was added
863 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
864 anotherpkg was added
865 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
866 * PR changed from "r0" to "r1"
867 * PV changed from "0.1.10" to "0.1.12"
868 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
869 * PR changed from "r0" to "r1"
870 * PV changed from "0.1.10" to "0.1.12"
871 </literallayout>
872 </para>
873
874 <para>
875 To see changes to the build history using a web interface, follow
876 the instruction in the <filename>README</filename> file here.
877 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
878 </para>
879
880 <para>
881 Here is a sample screenshot of the interface:
882 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
883 </para>
884 </section>
885 </section>
886</section>
887
888</chapter>
889<!--
890vim: expandtab tw=80 ts=4
891-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 09:08:56 +0000