summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-variables.xml
diff options
context:
space:
mode:
authorAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:46:05 +0100
committerAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:47:32 +0100
commit14b00ff23a912494edc7f146e668c40ca82b8508 (patch)
treef7f4e592ccb935bc312cfa0cfc3c0cbbe444970d /documentation/ref-manual/ref-variables.xml
downloadyocto-docs-master.tar.gz
initial commit of Enea Linux 3.1HEADmaster
Migrated from the internal git server on the dora-enea branch Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>
Diffstat (limited to 'documentation/ref-manual/ref-variables.xml')
-rw-r--r--documentation/ref-manual/ref-variables.xml5929
1 files changed, 5929 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
new file mode 100644
index 0000000..2b0e890
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,5929 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ALLOW_EMPTY'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FEED_DEPLOYDIR_BASE_URI'>F</link>
25<!-- <link linkend='var-glossary-g'>G</link> -->
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-IMAGE_BASENAME'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LAYERDEPENDS'>L</link>
31 <link linkend='var-MACHINE'>M</link>
32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_BINCONFIG_EXTRA_MANGLE'>O</link>
34 <link linkend='var-P'>P</link>
35<!-- <link linkend='var-glossary-q'>Q</link> -->
36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39 <link linkend='var-UBOOT_ENTRYPOINT'>U</link>
40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WARN_QA'>W</link>
42<!-- <link linkend='var-glossary-x'>X</link> -->
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
50 <glossdef>
51 <para>
52 Specifies if an output package should still be produced if it is empty.
53 By default, BitBake does not produce empty packages.
54 This default behavior can cause issues when there is an
55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
56 some other hard runtime requirement on the existence of the package.
57 </para>
58
59 <para>
60 Like all package-controlling variables, you must always use them in
61 conjunction with a package name override, as in:
62 <literallayout class='monospaced'>
63 ALLOW_EMPTY_${PN} = "1"
64 ALLOW_EMPTY_${PN}-dev = "1"
65 ALLOW_EMPTY_${PN}-staticdev = "1"
66 </literallayout>
67 </para>
68 </glossdef>
69 </glossentry>
70
71 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
72 <glossdef>
73 <para>
74 Lists commands in a package that need an alternative
75 binary naming scheme.
76 Sometimes the same command is provided in multiple packages.
77 When this occurs, the OpenEmbedded build system needs to
78 use the alternatives system to create a different binary
79 naming scheme so the commands can co-exist.
80 </para>
81
82 <para>
83 To use the variable, list out the package's commands
84 that also exist as part of another package.
85 For example, if the <filename>busybox</filename> package
86 has four commands that also exist as part of another
87 package, you identify them as follows:
88 <literallayout class='monospaced'>
89 ALTERNATIVE_busybox = "sh sed test bracket"
90 </literallayout>
91 For more information on the alternatives system, see the
92 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
93 section.
94 </para>
95 </glossdef>
96 </glossentry>
97
98 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
99 <glossdef>
100 <para>
101 Used by the alternatives system to map duplicated commands
102 to actual locations.
103 For example, if the <filename>bracket</filename> command
104 provided by the <filename>busybox</filename> package is
105 duplicated through another package, you must use the
106 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
107 specify the actual location:
108 <literallayout class='monospaced'>
109 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
110 </literallayout>
111 In this example, the binary for the
112 <filename>bracket</filename> command (i.e.
113 <filename>[</filename>) from the
114 <filename>busybox</filename> package resides in
115 <filename>/usr/bin/</filename>.
116 <note>
117 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
118 defined, it defaults to
119 <filename>${bindir}/&lt;name&gt;</filename>.
120 </note>
121 </para>
122
123 <para>
124 For more information on the alternatives system, see the
125 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
126 section.
127 </para>
128 </glossdef>
129 </glossentry>
130
131 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
132 <glossdef>
133 <para>
134 Used by the alternatives system to create default
135 priorities for duplicated commands.
136 You can use the variable to create a single default
137 regardless of the command name or package, a default for
138 specific duplicated commands regardless of the package, or
139 a default for specific commands tied to particular packages.
140 Here are the available syntax forms:
141 <literallayout class='monospaced'>
142 ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
143 ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
144 ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
145 </literallayout>
146 </para>
147
148 <para>
149 For more information on the alternatives system, see the
150 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
151 section.
152 </para>
153 </glossdef>
154 </glossentry>
155
156 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
157 <glossdef>
158 <para>
159 Used by the alternatives system to create default link
160 locations for duplicated commands.
161 You can use the variable to create a single default
162 location for all duplicated commands regardless of the
163 command name or package, a default for
164 specific duplicated commands regardless of the package, or
165 a default for specific commands tied to particular packages.
166 Here are the available syntax forms:
167 <literallayout class='monospaced'>
168 ALTERNATIVE_TARGET = "&lt;target&gt;"
169 ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
170 ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
171 </literallayout>
172 <note>
173 <para>
174 If <filename>ALTERNATIVE_TARGET</filename> is not
175 defined, it inherits the value from the
176 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
177 variable.
178 </para>
179
180 <para>
181 If <filename>ALTERNATIVE_LINK_NAME</filename> and
182 <filename>ALTERNATIVE_TARGET</filename> are the
183 same, the target for
184 <filename>ALTERNATIVE_TARGET</filename>
185 has "<filename>.{BPN}</filename>" appended to it.
186 </para>
187
188 <para>
189 Finally, if the file referenced has not been
190 renamed, the alternatives system will rename it to
191 avoid the need to rename alternative files in the
192 <filename>do_install</filename> task while
193 retaining support for the command if necessary.
194 </para>
195 </note>
196 </para>
197
198 <para>
199 For more information on the alternatives system, see the
200 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
201 section.
202 </para>
203 </glossdef>
204 </glossentry>
205
206 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
207 <glossdef>
208 <para>The email address used to contact the original author
209 or authors in order to send patches and forward bugs.</para>
210 </glossdef>
211 </glossentry>
212
213 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
214 <glossdef>
215 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
216 is set to the value of this variable, it specifies to use the latest
217 source revision in the repository.
218 Here is an example:
219 <literallayout class='monospaced'>
220 SRCREV = "${AUTOREV}"
221 </literallayout>
222 </para>
223 </glossdef>
224 </glossentry>
225
226 </glossdiv>
227
228 <glossdiv id='var-glossary-b'><title>B</title>
229
230 <glossentry id='var-B'><glossterm>B</glossterm>
231 <glossdef>
232 <para>
233 The directory within the
234 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
235 in which the OpenEmbedded build system places generated
236 objects during a recipe's build process.
237 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
238 directory, which is defined as:
239 <literallayout class='monospaced'>
240 S = "${WORKDIR}/${BP}/"
241 </literallayout>
242 You can separate the (<filename>S</filename>) directory
243 and the directory pointed to by the <filename>B</filename>
244 variable.
245 Most Autotools-based recipes support separating these
246 directories.
247 The build system defaults to using separate directories for
248 <filename>gcc</filename> and some kernel recipes.
249 </para>
250 </glossdef>
251 </glossentry>
252
253 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
254 <glossdef>
255 <para>
256 Lists "recommended-only" packages to not install.
257 Recommended-only packages are packages installed only
258 through the
259 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
260 variable.
261 You can prevent any of these "recommended" packages from
262 being installed by listing them with the
263 <filename>BAD_RECOMMENDATIONS</filename> variable:
264 <literallayout class='monospaced'>
265 BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
266 </literallayout>
267 You can set this variable globally in your
268 <filename>local.conf</filename> file or you can attach it to
269 a specific image recipe by using the recipe name override:
270 <literallayout class='monospaced'>
271 BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
272 </literallayout>
273 </para>
274
275 <para>
276 It is important to realize that if you choose to not install
277 packages using this variable and some other packages are
278 dependent on them (i.e. listed in a recipe's
279 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
280 variable), the OpenEmbedded build system ignores your
281 request and will install the packages to avoid dependency
282 errors.
283 </para>
284
285 <para>
286 Support for this variable exists only when using the
287 IPK and RPM packaging backend.
288 Support does not exist for DEB.
289 </para>
290
291 <para>
292 See the
293 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
294 and the
295 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
296 variables for related information.
297 </para>
298 </glossdef>
299 </glossentry>
300
301 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
302 <glossdef>
303 <para>
304 Defines how BitBake handles situations where an append
305 file (<filename>.bbappend</filename>) has no
306 corresponding recipe file (<filename>.bb</filename>).
307 This condition often occurs when layers get out of sync
308 (e.g. <filename>oe-core</filename> bumps a
309 recipe version and the old recipe no longer exists and the
310 other layer has not been updated to the new version
311 of the recipe yet).
312 </para>
313
314 <para>
315 The default fatal behavior is safest because it is
316 the sane reaction given something is out of sync.
317 It is important to realize when your changes are no longer
318 being applied.
319 </para>
320
321 <para>
322 You can change the default behavior by setting this
323 variable to "1" in the <filename>local.conf</filename>
324 file in the
325 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
326 as follows:
327 <literallayout class='monospaced'>
328 BB_DANGLINGAPPENDS_WARNONLY = "1"
329 </literallayout>
330 </para>
331 </glossdef>
332 </glossentry>
333
334 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
335 <glossdef>
336 <para>
337 Monitors disk space and available inodes during the build
338 and allows you to control the build based on these
339 parameters.
340 </para>
341
342 <para>
343 Disk space monitoring is disabled by default.
344 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
345 variable to your <filename>conf/local.conf</filename> file found in the
346 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
347 Use the following form:
348 <literallayout class='monospaced'>
349 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
350
351 where:
352
353 &lt;action&gt; is:
354 ABORT: Immediately abort the build when
355 a threshold is broken.
356 STOPTASKS: Stop the build after the currently
357 executing tasks have finished when
358 a threshold is broken.
359 WARN: Issue a warning but continue the
360 build when a threshold is broken.
361 Subsequent warnings are issued as
362 defined by the
363 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
364 which must be defined in the
365 conf/local.conf file.
366
367 &lt;dir&gt; is:
368 Any directory you choose. You can specify one or
369 more directories to monitor by separating the
370 groupings with a space. If two directories are
371 on the same device, only the first directory
372 is monitored.
373
374 &lt;threshold&gt; is:
375 Either the minimum available disk space,
376 the minimum number of free inodes, or
377 both. You must specify at least one. To
378 omit one or the other, simply omit the value.
379 Specify the threshold using G, M, K for Gbytes,
380 Mbytes, and Kbytes, respectively. If you do
381 not specify G, M, or K, Kbytes is assumed by
382 default. Do not use GB, MB, or KB.
383 </literallayout>
384 </para>
385
386 <para>
387 Here are some examples:
388 <literallayout class='monospaced'>
389 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
390 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
391 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
392 </literallayout>
393 The first example works only if you also provide
394 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
395 in the <filename>conf/local.conf</filename>.
396 This example causes the build system to immediately
397 abort when either the disk space in <filename>${TMPDIR}</filename> drops
398 below 1 Gbyte or the available free inodes drops below
399 100 Kbytes.
400 Because two directories are provided with the variable, the
401 build system also issue a
402 warning when the disk space in the
403 <filename>${SSTATE_DIR}</filename> directory drops
404 below 1 Gbyte or the number of free inodes drops
405 below 100 Kbytes.
406 Subsequent warnings are issued during intervals as
407 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
408 variable.
409 </para>
410
411 <para>
412 The second example stops the build after all currently
413 executing tasks complete when the minimum disk space
414 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
415 directory drops below 1 Gbyte.
416 No disk monitoring occurs for the free inodes in this case.
417 </para>
418
419 <para>
420 The final example immediately aborts the build when the
421 number of free inodes in the <filename>${TMPDIR}</filename> directory
422 drops below 100 Kbytes.
423 No disk space monitoring for the directory itself occurs
424 in this case.
425 </para>
426 </glossdef>
427 </glossentry>
428
429 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
430 <glossdef>
431 <para>
432 Defines the disk space and free inode warning intervals.
433 To set these intervals, define the variable in your
434 <filename>conf/local.conf</filename> file in the
435 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
436 </para>
437
438 <para>
439 If you are going to use the
440 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
441 also use the
442 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
443 and define its action as "WARN".
444 During the build, subsequent warnings are issued each time
445 disk space or number of free inodes further reduces by
446 the respective interval.
447 </para>
448
449 <para>
450 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
451 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
452 the "WARN" action, the disk monitoring interval defaults to
453 the following:
454 <literallayout class='monospaced'>
455 BB_DISKMON_WARNINTERVAL = "50M,5K"
456 </literallayout>
457 </para>
458
459 <para>
460 When specifying the variable in your configuration file,
461 use the following form:
462 <literallayout class='monospaced'>
463 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
464
465 where:
466
467 &lt;disk_space_interval&gt; is:
468 An interval of memory expressed in either
469 G, M, or K for Gbytes, Mbytes, or Kbytes,
470 respectively. You cannot use GB, MB, or KB.
471
472 &lt;disk_inode_interval&gt; is:
473 An interval of free inodes expressed in either
474 G, M, or K for Gbytes, Mbytes, or Kbytes,
475 respectively. You cannot use GB, MB, or KB.
476 </literallayout>
477 </para>
478
479 <para>
480 Here is an example:
481 <literallayout class='monospaced'>
482 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
483 BB_DISKMON_WARNINTERVAL = "50M,5K"
484 </literallayout>
485 These variables cause the OpenEmbedded build system to
486 issue subsequent warnings each time the available
487 disk space further reduces by 50 Mbytes or the number
488 of free inodes further reduces by 5 Kbytes in the
489 <filename>${SSTATE_DIR}</filename> directory.
490 Subsequent warnings based on the interval occur each time
491 a respective interval is reached beyond the initial warning
492 (i.e. 1 Gbytes and 100 Kbytes).
493 </para>
494 </glossdef>
495 </glossentry>
496
497 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
498 <glossdef>
499 <para>
500 Causes tarballs of the Git repositories to be placed in the
501 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
502 directory.
503 For performance reasons, creating and placing tarballs of
504 the Git repositories is not the default action by the
505 OpenEmbedded build system.
506 <literallayout class='monospaced'>
507 BB_GENERATE_MIRROR_TARBALLS = "1"
508 </literallayout>
509 Set this variable in your <filename>local.conf</filename>
510 file in the
511 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
512 </para>
513 </glossdef>
514 </glossentry>
515
516 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
517 <glossdef>
518 <para>The maximum number of tasks BitBake should run in parallel at any one time.
519 If your host development system supports multiple cores, a good rule of thumb
520 is to set this variable to twice the number of cores.</para>
521 </glossdef>
522 </glossentry>
523
524 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
525 <glossdef>
526 <para>
527 Allows you to extend a recipe so that it builds variants of the software.
528 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
529 which is a copy of Quilt built to run on the build system;
530 "crosses" such as <filename>gcc-cross</filename>,
531 which is a compiler built to run on the build machine but produces binaries
532 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
533 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
534 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
535 </para>
536
537 <para>
538 To build a different variant of the recipe with a minimal amount of code, it usually
539 is as simple as adding the following to your recipe:
540 <literallayout class='monospaced'>
541 BBCLASSEXTEND =+ "native nativesdk"
542 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
543 </literallayout>
544 </para>
545 </glossdef>
546 </glossentry>
547
548 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
549 <glossdef>
550 <para>Lists the names of configured layers.
551 These names are used to find the other <filename>BBFILE_*</filename>
552 variables.
553 Typically, each layer will append its name to this variable in its
554 <filename>conf/layer.conf</filename> file.
555 </para>
556 </glossdef>
557 </glossentry>
558
559 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
560 <glossdef>
561 <para>Variable that expands to match files from
562 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
563 in a particular layer.
564 This variable is used in the <filename>conf/layer.conf</filename> file and must
565 be suffixed with the name of the specific layer (e.g.
566 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
567 </glossdef>
568 </glossentry>
569
570 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
571 <glossdef>
572 <para>Assigns the priority for recipe files in each layer.</para>
573 <para>This variable is useful in situations where the same recipe appears in
574 more than one layer.
575 Setting this variable allows you to prioritize a
576 layer against other layers that contain the same recipe - effectively
577 letting you control the precedence for the multiple layers.
578 The precedence established through this variable stands regardless of a
579 recipe's version
580 (<link linkend='var-PV'><filename>PV</filename></link> variable).
581 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
582 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
583 lower precedence.</para>
584 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
585 precedence.
586 For example, the value 6 has a higher precedence than the value 5.
587 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
588 dependencies (see the
589 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
590 more information.
591 The default priority, if unspecified
592 for a layer with no dependencies, is the lowest defined priority + 1
593 (or 1 if no priorities are defined).</para>
594 <tip>
595 You can use the command <filename>bitbake-layers show-layers</filename> to list
596 all configured layers along with their priorities.
597 </tip>
598 </glossdef>
599 </glossentry>
600
601 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
602 <glossdef>
603 <para>List of recipe files used by BitBake to build software.</para>
604 </glossdef>
605 </glossentry>
606
607 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
608 <glossdef>
609 <para>Variable that controls how BitBake displays logs on build failure.</para>
610 </glossdef>
611 </glossentry>
612
613 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
614 <glossdef>
615 <para>Lists the layers to enable during the build.
616 This variable is defined in the <filename>bblayers.conf</filename> configuration
617 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
618 Here is an example:
619 <literallayout class='monospaced'>
620 BBLAYERS = " \
621 /home/scottrif/poky/meta \
622 /home/scottrif/poky/meta-yocto \
623 /home/scottrif/poky/meta-yocto-bsp \
624 /home/scottrif/poky/meta-mykernel \
625 "
626
627 BBLAYERS_NON_REMOVABLE ?= " \
628 /home/scottrif/poky/meta \
629 /home/scottrif/poky/meta-yocto \
630 "
631 </literallayout>
632 This example enables four layers, one of which is a custom, user-defined layer
633 named <filename>meta-mykernel</filename>.
634 </para>
635 </glossdef>
636 </glossentry>
637
638 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
639 <glossdef>
640 <para>Lists core layers that cannot be removed from the
641 <filename>bblayers.conf</filename> file during a build
642 using the
643 <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>.
644 <note>
645 When building an image outside of Hob, this variable
646 is ignored.
647 </note>
648 In order for BitBake to build your image using Hob, your
649 <filename>bblayers.conf</filename> file must include the
650 <filename>meta</filename> and <filename>meta-yocto</filename>
651 core layers.
652 Here is an example that shows these two layers listed in
653 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
654 <literallayout class='monospaced'>
655 BBLAYERS = " \
656 /home/scottrif/poky/meta \
657 /home/scottrif/poky/meta-yocto \
658 /home/scottrif/poky/meta-yocto-bsp \
659 /home/scottrif/poky/meta-mykernel \
660 "
661
662 BBLAYERS_NON_REMOVABLE ?= " \
663 /home/scottrif/poky/meta \
664 /home/scottrif/poky/meta-yocto \
665 "
666 </literallayout>
667 </para>
668 </glossdef>
669 </glossentry>
670
671 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
672 <glossdef>
673 <para>
674 Prevents BitBake from processing recipes and recipe
675 append files.
676 Use the <filename>BBMASK</filename> variable from within the
677 <filename>conf/local.conf</filename> file found
678 in the
679 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
680 </para>
681
682 <para>
683 You can use the <filename>BBMASK</filename> variable
684 to "hide" these <filename>.bb</filename> and
685 <filename>.bbappend</filename> files.
686 BitBake ignores any recipe or recipe append files that
687 match the expression.
688 It is as if BitBake does not see them at all.
689 Consequently, matching files are not parsed or otherwise
690 used by BitBake.</para>
691 <para>
692 The value you provide is passed to Python's regular
693 expression compiler.
694 The expression is compared against the full paths to
695 the files.
696 For complete syntax information, see Python's
697 documentation at
698 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
699 </para>
700
701 <para>
702 The following example uses a complete regular expression
703 to tell BitBake to ignore all recipe and recipe append
704 files in the <filename>meta-ti/recipes-misc/</filename>
705 directory:
706 <literallayout class='monospaced'>
707 BBMASK = "meta-ti/recipes-misc/"
708 </literallayout>
709 If you want to mask out multiple directories or recipes,
710 use the vertical bar to separate the regular expression
711 fragments.
712 This next example masks out multiple directories and
713 individual recipes:
714 <literallayout class='monospaced'>
715 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
716 BBMASK .= "|.*meta-oe/recipes-support/"
717 BBMASK .= "|.*openldap"
718 BBMASK .= "|.*opencv"
719 BBMASK .= "|.*lzma"
720 </literallayout>
721 Notice how the vertical bar is used to append the fragments.
722 <note>
723 When specifying a directory name, use the trailing
724 slash character to ensure you match just that directory
725 name.
726 </note>
727 </para>
728 </glossdef>
729 </glossentry>
730
731 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
732 <glossdef>
733 <para>
734 Used by BitBake to locate
735 <filename>.bbclass</filename> and configuration files.
736 This variable is analogous to the
737 <filename>PATH</filename> variable.
738 <note>
739 If you run BitBake from a directory outside of the
740 <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
741 you must be sure to set
742 <filename>BBPATH</filename> to point to the
743 Build Directory.
744 Set the variable as you would any environment variable
745 and then run BitBake:
746 <literallayout class='monospaced'>
747 $ BBPATH = "&lt;build_directory&gt;"
748 $ export BBPATH
749 $ bitbake &lt;target&gt;
750 </literallayout>
751 </note>
752 </para>
753 </glossdef>
754 </glossentry>
755
756 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
757 <glossdef>
758 <para>
759 Points to the server that runs memory-resident BitBake.
760 This variable is set by the
761 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
762 setup script and should not be hand-edited.
763 The variable is only used when you employ memory-resident
764 BitBake.
765 The setup script exports the value as follows:
766 <literallayout class='monospaced'>
767 export BBSERVER=localhost:$port
768 </literallayout>
769 For more information on how the
770 <filename>BBSERVER</filename> is used, see the
771 <filename>oe-init-build-env-memres</filename> script, which
772 is located in the
773 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
774 </para>
775 </glossdef>
776 </glossentry>
777
778 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
779 <glossdef>
780 <para>
781 When inheriting <filename>binconfig.bbclass</filename>
782 from a recipe, this variable specifies a wildcard for
783 configuration scripts that need editing.
784 The scripts are edited to correct any paths that have been
785 set up during compilation so that they are correct for
786 use when installed into the sysroot and called by the
787 build processes of other recipes.
788 </para>
789
790 <para>
791 For more information on how this variable works, see
792 <filename>meta/classes/binconfig.bbclass</filename> in the
793 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
794 You can also find general information on the class in the
795 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
796 section.
797 </para>
798 </glossdef>
799 </glossentry>
800
801 <glossentry id='var-BP'><glossterm>BP</glossterm>
802 <glossdef>
803 <para>The base recipe name and version but without any special
804 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
805 and so forth).
806 <filename>BP</filename> is comprised of the following:
807 <literallayout class="monospaced">
808 ${BPN}-${PV}
809 </literallayout></para>
810 </glossdef>
811 </glossentry>
812
813 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
814 <glossdef>
815 <para>The bare name of the recipe.
816 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
817 but removes common suffixes such as "-native" and "-cross" as well
818 as removes common prefixes such as multilib's "lib64-" and "lib32-".
819 The exact list of suffixes removed is specified by the
820 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
821 The exact list of prefixes removed is specified by the
822 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
823 Prefixes are removed for <filename>multilib</filename>
824 and <filename>nativesdk</filename> cases.</para>
825 </glossdef>
826 </glossentry>
827
828 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
829 <glossdef>
830 <para>
831 Points to the location of the
832 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
833 You can define this directory indirectly through the
834 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
835 and
836 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
837 scripts by passing in a Build Directory path when you run
838 the scripts.
839 If you run the scripts and do not provide a Build Directory
840 path, the <filename>BUILDDIR</filename> defaults to
841 <filename>build</filename> in the current directory.
842 </para>
843 </glossdef>
844 </glossentry>
845
846 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
847 <glossdef>
848 <para>
849 For the BusyBox recipe, specifies whether to split the
850 output executable file into two parts: one for features
851 that require <filename>setuid root</filename>, and one for
852 the remaining features (i.e. those that do not require
853 <filename>setuid root</filename>).
854 </para>
855
856 <para>
857 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
858 defaults to "1", which results in a single output
859 executable file.
860 Set the variable to "0" to split the output file.
861 </para>
862 </glossdef>
863 </glossentry>
864
865 </glossdiv>
866
867 <glossdiv id='var-glossary-c'><title>C</title>
868
869 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
870 <glossdef>
871 <para>
872 Flags passed to the C compiler for the target system.
873 This variable evaluates to the same as
874 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
875 </para>
876 </glossdef>
877 </glossentry>
878
879 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
880 <glossdef>
881 <para>A set of features common between
882 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
883 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
884 See the glossary descriptions for these variables for more information.</para>
885 </glossdef>
886 </glossentry>
887
888 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
889 <glossdef>
890 <para>
891 Points to <filename>meta/files/common-licenses</filename>
892 in the
893 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
894 which is where generic license files reside.
895 </para>
896 </glossdef>
897 </glossentry>
898
899 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
900 <glossdef>
901 <para>A regular expression that resolves to one or more hosts
902 (when the recipe is native) or one or more targets (when
903 the recipe is non-native) with which a recipe is compatible.
904 The regular expression is matched against
905 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
906 You can use the variable to stop recipes from being built
907 for classes of systems with which the recipes are not
908 compatible.
909 Stopping these builds is particularly useful with kernels.
910 The variable also helps to increase parsing speed
911 since the build system skips parsing recipes not
912 compatible with the current system.</para>
913 </glossdef>
914 </glossentry>
915
916 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
917 <glossdef>
918 <para>A regular expression that resolves to one or more
919 target machines with which a recipe is compatible.
920 The regular expression is matched against
921 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
922 You can use the variable to stop recipes from being built
923 for machines with which the recipes are not compatible.
924 Stopping these builds is particularly useful with kernels.
925 The variable also helps to increase parsing speed
926 since the build system skips parsing recipes not
927 compatible with the current machine.</para>
928 </glossdef>
929 </glossentry>
930
931 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
932 <glossdef>
933 <para>
934 Defines wildcards to match when installing a list of
935 complementary packages for all the packages explicitly
936 (or implicitly) installed in an image.
937 The resulting list of complementary packages is associated
938 with an item that can be added to
939 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
940 An example usage of this is the "dev-pkgs" item that when
941 added to <filename>IMAGE_FEATURES</filename> will
942 install -dev packages (containing headers and other
943 development files) for every package in the image.
944 </para>
945
946 <para>
947 To add a new feature item pointing to a wildcard, use a
948 variable flag to specify the feature item name and
949 use the value to specify the wildcard.
950 Here is an example:
951 <literallayout class='monospaced'>
952 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
953 </literallayout>
954 </para>
955 </glossdef>
956 </glossentry>
957
958 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
959 <glossdef>
960 <para>
961 Identifies editable or configurable files that are part of a package.
962 If the Package Management System (PMS) is being used to update
963 packages on the target system, it is possible that
964 configuration files you have changed after the original installation
965 and that you now want to remain unchanged are overwritten.
966 In other words, editable files might exist in the package that you do not
967 want reset as part of the package update process.
968 You can use the <filename>CONFFILES</filename> variable to list the files in the
969 package that you wish to prevent the PMS from overwriting during this update process.
970 </para>
971
972 <para>
973 To use the <filename>CONFFILES</filename> variable, provide a package name
974 override that identifies the resulting package.
975 Then, provide a space-separated list of files.
976 Here is an example:
977 <literallayout class='monospaced'>
978 CONFFILES_${PN} += "${sysconfdir}/file1 \
979 ${sysconfdir}/file2 ${sysconfdir}/file3"
980 </literallayout>
981 </para>
982
983 <para>
984 A relationship exists between the <filename>CONFFILES</filename> and
985 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
986 The files listed within <filename>CONFFILES</filename> must be a subset of
987 the files listed within <filename>FILES</filename>.
988 Because the configuration files you provide with <filename>CONFFILES</filename>
989 are simply being identified so that the PMS will not overwrite them,
990 it makes sense that
991 the files must already be included as part of the package through the
992 <filename>FILES</filename> variable.
993 </para>
994
995 <note>
996 When specifying paths as part of the <filename>CONFFILES</filename> variable,
997 it is good practice to use appropriate path variables.
998 For example, <filename>${sysconfdir}</filename> rather than
999 <filename>/etc</filename> or <filename>${bindir}</filename> rather
1000 than <filename>/usr/bin</filename>.
1001 You can find a list of these variables at the top of the
1002 <filename>meta/conf/bitbake.conf</filename> file in the
1003 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1004 </note>
1005 </glossdef>
1006 </glossentry>
1007
1008 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
1009 <glossdef>
1010 <para>
1011 A list of files that contains <filename>autoconf</filename> test results relevant
1012 to the current build.
1013 This variable is used by the Autotools utilities when running
1014 <filename>configure</filename>.
1015 </para>
1016 </glossdef>
1017 </glossentry>
1018
1019 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
1020 <glossdef>
1021 <para>
1022 Specifies the list of packages to be added to the image.
1023 You should only set this variable in the
1024 <filename>local.conf</filename> configuration file found
1025 in the
1026 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1027 </para>
1028
1029 <para>
1030 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
1031 </para>
1032 </glossdef>
1033 </glossentry>
1034
1035 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
1036 <glossdef>
1037 <para>
1038 Specifies the parent directory of the OpenEmbedded
1039 Core Metadata layer (i.e. <filename>meta</filename>).
1040 </para>
1041
1042 <para>
1043 It is an important distinction that
1044 <filename>COREBASE</filename> points to the parent of this
1045 layer and not the layer itself.
1046 Consider an example where you have cloned the Poky Git
1047 repository and retained the <filename>poky</filename>
1048 name for your local copy of the repository.
1049 In this case, <filename>COREBASE</filename> points to
1050 the <filename>poky</filename> folder because it is the
1051 parent directory of the <filename>poky/meta</filename>
1052 layer.
1053 </para>
1054 </glossdef>
1055 </glossentry>
1056
1057 </glossdiv>
1058
1059 <glossdiv id='var-glossary-d'><title>D</title>
1060
1061 <glossentry id='var-D'><glossterm>D</glossterm>
1062 <glossdef>
1063 <para>The destination directory.</para>
1064 </glossdef>
1065 </glossentry>
1066
1067 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
1068 <glossdef>
1069 <para>
1070 The date and time on which the current build started.
1071 The format is suitable for timestamps.
1072 </para>
1073 </glossdef>
1074 </glossentry>
1075
1076 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
1077 <glossdef>
1078 <para>
1079 Specifies to build packages with debugging information.
1080 This influences the value of the
1081 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
1082 variable.
1083 </para>
1084 </glossdef>
1085 </glossentry>
1086
1087 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
1088 <glossdef>
1089 <para>
1090 The options to pass in
1091 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1092 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
1093 a system for debugging.
1094 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1095 </para>
1096 </glossdef>
1097 </glossentry>
1098
1099 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1100 <glossdef>
1101 <para>
1102 Specifies a weak bias for recipe selection priority.
1103 </para>
1104 <para>
1105 The most common usage of this is variable is to set
1106 it to "-1" within a recipe for a development version of a
1107 piece of software.
1108 Using the variable in this way causes the stable version
1109 of the recipe to build by default in the absence of
1110 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1111 being used to build the development version.
1112 </para>
1113 <note>
1114 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1115 is weak and is overridden by
1116 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1117 if that variable is different between two layers
1118 that contain different versions of the same recipe.
1119 </note>
1120 </glossdef>
1121 </glossentry>
1122
1123 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1124 <glossdef>
1125 <para>
1126 Lists a recipe's build-time dependencies
1127 (i.e. other recipe files).
1128 The system ensures that all the dependencies listed
1129 have been built and have their contents in the appropriate
1130 sysroots before the recipe's configure task is executed.
1131 </para>
1132
1133 <para>
1134 Consider this simple example for two recipes named "a" and
1135 "b" that produce similarly named packages.
1136 In this example, the <filename>DEPENDS</filename>
1137 statement appears in the "a" recipe:
1138 <literallayout class='monospaced'>
1139 DEPENDS = "b"
1140 </literallayout>
1141 Here, the dependency is such that the
1142 <filename>do_configure</filename> task for recipe "a"
1143 depends on the <filename>do_populate_sysroot</filename>
1144 task of recipe "b".
1145 This means anything that recipe "b" puts into sysroot
1146 is available when recipe "a" is configuring itself.
1147 </para>
1148
1149 <para>
1150 For information on runtime dependencies, see the
1151 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1152 variable.
1153 </para>
1154 </glossdef>
1155 </glossentry>
1156
1157 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
1158 <glossdef>
1159 <para>
1160 Points to the general area that the OpenEmbedded build
1161 system uses to place images, packages, SDKs and other output
1162 files that are ready to be used outside of the build system.
1163 By default, this directory resides within the
1164 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1165 as <filename>${TMPDIR}/deploy</filename>.
1166 </para>
1167
1168 <para>
1169 For more information on the structure of the Build
1170 Directory, see
1171 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1172 section.
1173 For more detail on the contents of the
1174 <filename>deploy</filename> directory, see the
1175 "<link linkend='images-dev-environment'>Images</link>" and
1176 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1177 sections.
1178 </para>
1179 </glossdef>
1180 </glossentry>
1181
1182 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
1183 <glossdef>
1184 <para>
1185 Points to the area that the OpenEmbedded build system uses
1186 to place images and other associated output files that are
1187 ready to be deployed onto the target machine.
1188 The directory is machine-specific as it contains the
1189 <filename>${MACHINE}</filename> name.
1190 By default, this directory resides within the
1191 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1192 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
1193 </para>
1194
1195 <para>
1196 For more information on the structure of the Build
1197 Directory, see
1198 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1199 section.
1200 For more detail on the contents of the
1201 <filename>deploy</filename> directory, see the
1202 "<link linkend='images-dev-environment'>Images</link>" and
1203 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1204 sections.
1205 </para>
1206 </glossdef>
1207 </glossentry>
1208
1209 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1210 <glossdef>
1211 <para>The package description used by package managers.
1212 If not set, <filename>DESCRIPTION</filename> takes
1213 the value of the
1214 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
1215 variable.
1216 </para>
1217 </glossdef>
1218 </glossentry>
1219
1220 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
1221 <glossdef>
1222 <para>
1223 The short name of the distribution.
1224 This variable corresponds to a file with the
1225 extension <filename>.conf</filename>
1226 located in a <filename>conf/distro</filename> directory
1227 within the
1228 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
1229 that contains the distribution configuration.
1230 The value must not contain spaces, and is typically all lower-case.
1231 </para>
1232 <para>
1233 If the variable is blank, a set of default configuration
1234 will be used, which is specified
1235 within <filename>meta/conf/distro/defaultsetup.conf</filename>.
1236 </para>
1237 </glossdef>
1238 </glossentry>
1239
1240 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
1241 <glossdef>
1242 <para>
1243 Specifies a list of distro-specific packages to add to all images.
1244 This variable takes affect through
1245 <filename>packagegroup-base</filename> so the
1246 variable only really applies to the more full-featured
1247 images that include <filename>packagegroup-base</filename>.
1248 You can use this variable to keep distro policy out of
1249 generic images.
1250 As with all other distro variables, you set this variable
1251 in the distro <filename>.conf</filename> file.
1252 </para>
1253 </glossdef>
1254 </glossentry>
1255
1256 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
1257 <glossdef>
1258 <para>
1259 Specifies a list of distro-specific packages to add to all images
1260 if the packages exist.
1261 The packages might not exist or be empty (e.g. kernel modules).
1262 The list of packages are automatically installed but you can
1263 remove them.
1264 </para>
1265 </glossdef>
1266 </glossentry>
1267
1268 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
1269 <glossdef>
1270 <para>The features enabled for the distribution.
1271 For a list of supported features that ship with the
1272 Yocto Project, see the
1273 "<link linkend='ref-features-distro'>Distro</link>"
1274 section.
1275 </para>
1276 </glossdef>
1277 </glossentry>
1278
1279 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
1280 <glossdef>
1281 <para>Features to be added to
1282 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
1283 if not also present in
1284 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1285 </para>
1286
1287 <para>
1288 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1289 It is not intended to be user-configurable.
1290 It is best to just reference the variable to see which distro features are
1291 being backfilled for all distro configurations.
1292 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1293 more information.
1294 </para>
1295 </glossdef>
1296 </glossentry>
1297
1298 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
1299 <glossdef>
1300 <para>Features from
1301 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
1302 that should not be backfilled (i.e. added to
1303 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
1304 during the build.
1305 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
1306 more information.
1307 </para>
1308 </glossdef>
1309 </glossentry>
1310
1311 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
1312 <glossdef>
1313 <para>The long name of the distribution.</para>
1314 </glossdef>
1315 </glossentry>
1316
1317 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
1318 <glossdef>
1319 <para>Alias names used for the recipe in various Linux distributions.</para>
1320 <para>See the
1321 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
1322 a Package Name Alias</ulink>" section in the Yocto Project Development
1323 Manual for more information.</para>
1324 </glossdef>
1325 </glossentry>
1326
1327 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
1328 <glossdef>
1329 <para>The version of the distribution.</para>
1330 </glossdef>
1331 </glossentry>
1332
1333 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
1334 <glossdef>
1335 <para>
1336 This variable lists overrides specific to the current
1337 distribution.
1338 By default, the variable list includes the value of the
1339 <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
1340 variable.
1341 You can extend the variable to apply any variable overrides
1342 you want as part of the distribution and are not
1343 already in <filename>OVERRIDES</filename> through
1344 some other means.
1345 </para>
1346 </glossdef>
1347 </glossentry>
1348
1349 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1350 <glossdef>
1351 <para>
1352 The central download directory used by the build process to
1353 store downloads.
1354 By default, <filename>DL_DIR</filename> gets files
1355 suitable for mirroring for everything except Git
1356 repositories.
1357 If you want tarballs of Git repositories, use the
1358 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1359 variable.
1360 </para>
1361
1362 <para>
1363 You can set this directory by defining the
1364 <filename>DL_DIR</filename> variable in the
1365 <filename>conf/local.conf</filename> file.
1366 This directory is self-maintaining and you should not have
1367 to touch it.
1368 By default, the directory is <filename>downloads</filename>
1369 in the
1370 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1371 <literallayout class='monospaced'>
1372 #DL_DIR ?= "${TOPDIR}/downloads"
1373 </literallayout>
1374 To specify a different download directory, simply remove
1375 the comment from the line and provide your directory.
1376 </para>
1377
1378 <para>
1379 During a first build, the system downloads many different
1380 source code tarballs from various upstream projects.
1381 Downloading can take a while, particularly if your network
1382 connection is slow.
1383 Tarballs are all stored in the directory defined by
1384 <filename>DL_DIR</filename> and the build system looks there
1385 first to find source tarballs.
1386 <note>
1387 When wiping and rebuilding, you can preserve this
1388 directory to speed up this part of subsequent
1389 builds.
1390 </note>
1391 </para>
1392
1393 <para>
1394 You can safely share this directory between multiple builds
1395 on the same development machine.
1396 For additional information on how the build process gets
1397 source files when working behind a firewall or proxy server,
1398 see this specific question in the
1399 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
1400 chapter.
1401 </para>
1402 </glossdef>
1403
1404 </glossentry>
1405 </glossdiv>
1406
1407 <glossdiv id='var-glossary-e'><title>E</title>
1408
1409 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
1410 <glossdef>
1411 <para></para>
1412 <para>Variable that controls which locales for
1413 <filename>eglibc</filename> are generated during the
1414 build (useful if the target device has 64Mbytes
1415 of RAM or less).</para>
1416 </glossdef>
1417 </glossentry>
1418
1419 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
1420 <glossdef>
1421 <para>
1422 Specifies the quality assurance checks whose failures are
1423 reported as errors by the OpenEmbedded build system.
1424 You set this variable in your distribution configuration
1425 file.
1426 For a list of the checks you can control with this variable,
1427 see the
1428 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1429 section.
1430 </para>
1431 </glossdef>
1432 </glossentry>
1433
1434 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1435 <glossdef>
1436 <para>
1437 Directs BitBake to exclude a recipe from world builds (i.e.
1438 <filename>bitbake world</filename>).
1439 During world builds, BitBake locates, parses and builds all
1440 recipes found in every layer exposed in the
1441 <filename>bblayers.conf</filename> configuration file.
1442 </para>
1443
1444 <para>
1445 To exclude a recipe from a world build using this variable,
1446 set the variable to "1" in the recipe.
1447 </para>
1448
1449 <note>
1450 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1451 may still be built during a world build in order to satisfy
1452 dependencies of other recipes.
1453 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1454 only ensures that the recipe is not explicitly added
1455 to the list of build targets in a world build.
1456 </note>
1457 </glossdef>
1458 </glossentry>
1459
1460 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
1461 <glossdef>
1462 <para>
1463 Used with file and pathnames to create a prefix for a recipe's
1464 version based on the recipe's
1465 <link linkend='var-PE'><filename>PE</filename></link> value.
1466 If <filename>PE</filename> is set and greater than zero for a recipe,
1467 <filename>EXTENDPE</filename> becomes that value (e.g if
1468 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
1469 becomes "1_").
1470 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
1471 zero, <filename>EXTENDPE</filename> becomes "".</para>
1472 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
1473 variable for an example.
1474 </para>
1475 </glossdef>
1476 </glossentry>
1477
1478 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
1479 <glossdef>
1480 <para>
1481 The full package version specification as it appears on the
1482 final packages produced by a recipe.
1483 The variable's value is normally used to fix a runtime
1484 dependency to the exact same version of another package
1485 in the same recipe:
1486 <literallayout class='monospaced'>
1487 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
1488 </literallayout>
1489 </para>
1490
1491 <para>
1492 The dependency relationships are intended to force the
1493 package manager to upgrade these types of packages in
1494 lock-step.
1495 </para>
1496 </glossdef>
1497 </glossentry>
1498
1499 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
1500 <glossdef>
1501 <para>
1502 If <filename>externalsrc.bbclass</filename> is inherited,
1503 this variable points to the source tree, which is
1504 outside of the OpenEmbedded build system.
1505 When set, this variable sets the
1506 <link linkend='var-S'><filename>S</filename></link>
1507 variable, which is what the OpenEmbedded build system uses
1508 to locate unpacked recipe source code.
1509 </para>
1510
1511 <para>
1512 For more information on
1513 <filename>externalsrc.bbclass</filename>, see the
1514 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
1515 section.
1516 You can also find information on how to use this variable
1517 in the
1518 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
1519 section in the Yocto Project Development Manual.
1520 </para>
1521 </glossdef>
1522 </glossentry>
1523
1524 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
1525 <glossdef>
1526 <para>
1527 If <filename>externalsrc.bbclass</filename> is inherited,
1528 this variable points to the directory in which the recipe's
1529 source code is built,
1530 which is outside of the OpenEmbedded build system.
1531 When set, this variable sets the
1532 <link linkend='var-B'><filename>B</filename></link>
1533 variable, which is what the OpenEmbedded build system uses
1534 to locate the Build Directory.
1535 </para>
1536
1537 <para>
1538 For more information on
1539 <filename>externalsrc.bbclass</filename>, see the
1540 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
1541 section.
1542 You can also find information on how to use this variable
1543 in the
1544 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
1545 section in the Yocto Project Development Manual.
1546 </para>
1547 </glossdef>
1548 </glossentry>
1549
1550 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
1551 <glossdef>
1552 <para>
1553 The list of additional features to include in an image.
1554 Typically, you configure this variable in your
1555 <filename>local.conf</filename> file, which is found in the
1556 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1557 Although you can use this variable from within a recipe,
1558 best practices dictate that you do not.
1559 <note>
1560 To enable primary features from within the image
1561 recipe, use the
1562 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
1563 variable.
1564 </note>
1565 </para>
1566
1567 <para>
1568 Here are some examples of features you can add:
1569 <literallayout class='monospaced'>
1570"dbg-pkgs" - Adds -dbg packages for all installed packages
1571 including symbol information for debugging and
1572 profiling.
1573
1574"debug-tweaks" - Makes an image suitable for development.
1575 For example, ssh root access has a blank
1576 password. You should remove this feature
1577 before you produce a production image.
1578
1579"dev-pkgs" - Adds -dev packages for all installed packages.
1580 This is useful if you want to develop against
1581 the libraries in the image.
1582
1583"read-only-rootfs" - Creates an image whose root
1584 filesystem is read-only. See the
1585 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
1586 section in the Yocto Project
1587 Development Manual for more
1588 information
1589
1590"tools-debug" - Adds debugging tools such as gdb and
1591 strace.
1592
1593"tools-profile" - Adds profiling tools such as oprofile,
1594 exmap, lttng and valgrind (x86 only).
1595
1596"tools-sdk" - Adds development tools such as gcc, make,
1597 pkgconfig and so forth.
1598
1599"tools-testapps" - Adds useful testing tools such as
1600 ts_print, aplay, arecord and so
1601 forth.
1602
1603 </literallayout>
1604 </para>
1605
1606 <para>
1607 For a complete list of image features that ships with the
1608 Yocto Project, see the
1609 "<link linkend="ref-features-image">Images</link>"
1610 section.
1611 </para>
1612
1613 <para>
1614 For an example that shows how to customize your image by
1615 using this variable, see the
1616 "<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>"
1617 section in the Yocto Project Development Manual.
1618 </para>
1619 </glossdef>
1620 </glossentry>
1621
1622 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
1623 <glossdef>
1624 <para>A list of recipes to build that do not provide packages
1625 for installing into the root filesystem.
1626 </para>
1627 <para>Sometimes a recipe is required to build the final image but is not
1628 needed in the root filesystem.
1629 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
1630 list these recipes and thus specify the dependencies.
1631 A typical example is a required bootloader in a machine configuration.
1632 </para>
1633 <note>
1634 To add packages to the root filesystem, see the various
1635 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
1636 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
1637 variables.
1638 </note>
1639 </glossdef>
1640 </glossentry>
1641
1642 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
1643 <glossdef>
1644 <para>Additional <filename>cmake</filename> options.</para>
1645 </glossdef>
1646 </glossentry>
1647
1648 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
1649 <glossdef>
1650 <para>Additional <filename>configure</filename> script options.</para>
1651 </glossdef>
1652 </glossentry>
1653
1654 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
1655 <glossdef>
1656 <para>Additional GNU <filename>make</filename> options.</para>
1657 </glossdef>
1658 </glossentry>
1659
1660 </glossdiv>
1661
1662 <glossdiv id='var-glossary-f'><title>F</title>
1663
1664 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
1665 <glossdef>
1666 <para>
1667 Points to the base URL of the server and location within
1668 the document-root that provides the metadata and
1669 packages required by OPKG to support runtime package
1670 management of IPK packages.
1671 You set this variable in your
1672 <filename>local.conf</filename> file.
1673 </para>
1674
1675 <para>
1676 Consider the following example:
1677 <literallayout class='monospaced'>
1678 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
1679 </literallayout>
1680 This example assumes you are serving your packages over
1681 HTTP and your databases are located in a directory
1682 named <filename>BOARD-dir</filename>, which is underneath
1683 your HTTP server's document-root.
1684 In this case, the OpenEmbedded build system generates a set
1685 of configuration files for you in your target that work
1686 with the feed.
1687 </para>
1688 </glossdef>
1689 </glossentry>
1690
1691 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
1692 <glossdef>
1693 <para>
1694 The list of directories or files that are placed in packages.
1695 </para>
1696
1697 <para>
1698 To use the <filename>FILES</filename> variable, provide a package name
1699 override that identifies the resulting package.
1700 Then, provide a space-separated list of files or paths that identifies the
1701 files you want included as part of the resulting package.
1702 Here is an example:
1703 <literallayout class='monospaced'>
1704 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
1705 </literallayout>
1706 </para>
1707
1708 <note>
1709 When specifying paths as part of the <filename>FILES</filename> variable,
1710 it is good practice to use appropriate path variables.
1711 For example, use <filename>${sysconfdir}</filename> rather than
1712 <filename>/etc</filename>, or <filename>${bindir}</filename> rather
1713 than <filename>/usr/bin</filename>.
1714 You can find a list of these variables at the top of the
1715 <filename>meta/conf/bitbake.conf</filename> file in the
1716 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1717 </note>
1718
1719 <para>
1720 If some of the files you provide with the <filename>FILES</filename> variable
1721 are editable and you know they should not be
1722 overwritten during the package update process by the Package Management
1723 System (PMS), you can identify these files so that the PMS will not
1724 overwrite them.
1725 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
1726 variable for information on how to identify these files to the PMS.
1727 </para>
1728
1729 </glossdef>
1730 </glossentry>
1731
1732 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
1733 <glossdef>
1734 <para>
1735 Extends the search path the OpenEmbedded build system uses
1736 when looking for files and patches as it processes recipes
1737 and append files.
1738 The default directories BitBake uses when it processes
1739 recipes are initially defined by the
1740 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
1741 variable.
1742 You can extend <filename>FILESPATH</filename> variable
1743 by using <filename>FILESEXTRAPATHS</filename>.
1744 </para>
1745
1746 <para>
1747 Best practices dictate that you accomplish this by using
1748 <filename>FILESEXTRAPATHS</filename> from within a
1749 <filename>.bbappend</filename> file and that you prepend
1750 paths as follows:
1751 <literallayout class='monospaced'>
1752 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1753 </literallayout>
1754 In the above example, the build system first looks for files
1755 in a directory that has the same name as the corresponding
1756 append file.
1757 <note>
1758 <para>When extending <filename>FILESEXTRAPATHS</filename>,
1759 be sure to use the immediate expansion
1760 (<filename>:=</filename>) operator.
1761 Immediate expansion makes sure that BitBake evaluates
1762 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
1763 at the time the directive is encountered rather than at
1764 some later time when expansion might result in a
1765 directory that does not contain the files you need.
1766 </para>
1767 <para>Also, include the trailing separating colon
1768 character if you are prepending.
1769 The trailing colon character is necessary because you
1770 are directing BitBake to extend the path by prepending
1771 directories to the search path.</para>
1772 </note>
1773 Here is another common use:
1774 <literallayout class='monospaced'>
1775 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1776 </literallayout>
1777 In this example, the build system extends the
1778 <filename>FILESPATH</filename> variable to include a
1779 directory named <filename>files</filename> that is in the
1780 same directory as the corresponding append file.
1781 </para>
1782
1783 <para>
1784 Here is a final example that specifically adds three paths:
1785 <literallayout class='monospaced'>
1786 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
1787 </literallayout>
1788 </para>
1789
1790 <para>
1791 By prepending paths in <filename>.bbappend</filename>
1792 files, you allow multiple append files that reside in
1793 different layers but are used for the same recipe to
1794 correctly extend the path.
1795 </para>
1796 </glossdef>
1797 </glossentry>
1798
1799 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
1800 <glossdef>
1801 <para>
1802 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1803 used by the OpenEmbedded build system for creating
1804 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
1805 You can find more information on how overrides are handled
1806 in the BitBake Manual that is located at
1807 <filename>bitbake/doc/manual</filename> in the
1808 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1809 </para>
1810
1811 <para>
1812 By default, the <filename>FILESOVERRIDES</filename>
1813 variable is defined as:
1814 <literallayout class='monospaced'>
1815 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
1816 </literallayout>
1817
1818 <note>
1819 Do not hand-edit the <filename>FILESOVERRIDES</filename>
1820 variable.
1821 The values match up with expected overrides and are
1822 used in an expected manner by the build system.
1823 </note>
1824 </para>
1825 </glossdef>
1826 </glossentry>
1827
1828 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1829 <glossdef>
1830 <para>
1831 The default set of directories the OpenEmbedded build system
1832 uses when searching for patches and files.
1833 During the build process, BitBake searches each directory in
1834 <filename>FILESPATH</filename> in the specified order when
1835 looking for files and patches specified by each
1836 <filename>file://</filename> URI in a recipe.
1837 </para>
1838
1839 <para>
1840 The default value for the <filename>FILESPATH</filename>
1841 variable is defined in the <filename>base.bbclass</filename>
1842 class found in <filename>meta/classes</filename> in the
1843 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
1844 <literallayout class='monospaced'>
1845 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
1846 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
1847 </literallayout>
1848 <note>
1849 Do not hand-edit the <filename>FILESPATH</filename>
1850 variable.
1851 If you want the build system to look in directories
1852 other than the defaults, extend the
1853 <filename>FILESPATH</filename> variable by using the
1854 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
1855 variable.
1856 </note>
1857 Be aware that the default <filename>FILESPATH</filename>
1858 directories do not map to directories in custom layers
1859 where append files (<filename>.bbappend</filename>)
1860 are used.
1861 If you want the build system to find patches or files
1862 that reside with your append files, you need to extend
1863 the <filename>FILESPATH</filename> variable by using
1864 the
1865 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
1866 variable.
1867 </para>
1868 </glossdef>
1869 </glossentry>
1870
1871 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
1872 <glossdef>
1873 <para>Allows you to define your own file permissions settings table as part of
1874 your configuration for the packaging process.
1875 For example, suppose you need a consistent set of custom permissions for
1876 a set of groups and users across an entire work project.
1877 It is best to do this in the packages themselves but this is not always
1878 possible.
1879 </para>
1880 <para>
1881 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
1882 is located in the <filename>meta/files</filename> folder in the
1883 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1884 If you create your own file permissions setting table, you should place it in your
1885 layer or the distro's layer.
1886 </para>
1887 <para>
1888 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
1889 <filename>conf/local.conf</filename> file, which is found in the
1890 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
1891 point to your custom <filename>fs-perms.txt</filename>.
1892 You can specify more than a single file permissions setting table.
1893 The paths you specify to these files must be defined within the
1894 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
1895 </para>
1896 <para>
1897 For guidance on how to create your own file permissions settings table file,
1898 examine the existing <filename>fs-perms.txt</filename>.
1899 </para>
1900 </glossdef>
1901 </glossentry>
1902
1903 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
1904 <glossdef>
1905 <para>
1906 The options to pass in
1907 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1908 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
1909 when compiling an optimized system.
1910 This variable defaults to
1911 "-O2 -pipe ${DEBUG_FLAGS}".
1912 </para>
1913 </glossdef>
1914 </glossentry>
1915
1916 </glossdiv>
1917
1918<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
1919<!-- </glossdiv>-->
1920
1921 <glossdiv id='var-glossary-h'><title>H</title>
1922
1923 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1924 <glossdef>
1925 <para>Website where more information about the software the recipe is building
1926 can be found.</para>
1927 </glossdef>
1928 </glossentry>
1929
1930 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
1931 <glossdef>
1932 <para>
1933 Specifies the system, including the architecture and the
1934 operating system, for with the build is occurring
1935 in the context of the current
1936 recipe.
1937 The OpenEmbedded build system automatically sets this
1938 variable.
1939 You do not need to set the variable yourself.
1940 </para>
1941
1942 <para>
1943 Here are two examples:
1944 <itemizedlist>
1945 <listitem><para>Given a native recipe on a 32-bit
1946 x86 machine running Linux, the value is
1947 "i686-linux".
1948 </para></listitem>
1949 <listitem><para>Given a recipe being built for a
1950 little-endian MIPS target running Linux,
1951 the value might be "mipsel-linux".
1952 </para></listitem>
1953 </itemizedlist>
1954 </para>
1955 </glossdef>
1956 </glossentry>
1957
1958 </glossdiv>
1959
1960 <glossdiv id='var-glossary-i'><title>I</title>
1961
1962 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
1963 <glossdef>
1964 <para>
1965 The base name of image output files.
1966 This variable defaults to the recipe name
1967 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
1968 </para>
1969 </glossdef>
1970 </glossentry>
1971
1972 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
1973 <glossdef>
1974 <para>
1975 A list of classes that all images should inherit.
1976 You typically use this variable to specify the list of
1977 classes that register the different types of images
1978 the OpenEmbedded build system creates.
1979 </para>
1980
1981 <para>
1982 The default value for <filename>IMAGE_CLASSES</filename> is
1983 <filename>image_types</filename>.
1984 You can set this variable in your
1985 <filename>local.conf</filename> or in a distribution
1986 configuration file.
1987 </para>
1988
1989 <para>
1990 For more information, see
1991 <filename>meta/classes/image_types.bbclass</filename> in the
1992 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1993 </para>
1994 </glossdef>
1995 </glossentry>
1996
1997 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
1998 <glossdef>
1999 <para>
2000 The primary list of features to include in an image.
2001 Typically, you configure this variable in an image recipe.
2002 Although you can use this variable from your
2003 <filename>local.conf</filename> file, which is found in the
2004 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
2005 best practices dictate that you do not.
2006 <note>
2007 To enable extra features from outside the image recipe,
2008 use the
2009 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
2010 </note>
2011 For a list of image features that ships with the Yocto
2012 Project, see the
2013 "<link linkend="ref-features-image">Images</link>"
2014 section.
2015 </para>
2016
2017 <para>
2018 For an example that shows how to customize your image by
2019 using this variable, see the
2020 "<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>"
2021 section in the Yocto Project Development Manual.
2022 </para>
2023 </glossdef>
2024 </glossentry>
2025
2026 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
2027 <glossdef>
2028 <para>
2029 Specifies the formats the OpenEmbedded build system uses
2030 during the build when creating the root filesystem.
2031 For example, setting <filename>IMAGE_FSTYPES</filename>
2032 as follows causes the build system to create root
2033 filesystems using two formats: <filename>.ext3</filename>
2034 and <filename>.tar.bz2</filename>:
2035 <literallayout class='monospaced'>
2036 IMAGE_FSTYPES = "ext3 tar.bz2"
2037 </literallayout>
2038 For the complete list of supported image formats from which
2039 you can choose, see
2040 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
2041 </para>
2042 </glossdef>
2043 </glossentry>
2044
2045 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
2046 <glossdef>
2047 <para>
2048 Specifies the packages to install into an image.
2049 The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
2050 recipe and you should use it with care to avoid ordering issues.
2051 </para>
2052
2053 <para>
2054 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
2055 packages to install into an image through <filename>image.bbclass</filename>.
2056 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
2057 that can take
2058 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
2059 and turn these into auto-generated entries in
2060 <filename>IMAGE_INSTALL</filename> in addition to its default contents.
2061 </para>
2062
2063 <para>
2064 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
2065 operator from the <filename>/conf/local.conf</filename> file or from within
2066 an image recipe is not recommended as it can cause ordering issues.
2067 Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
2068 to a default value using the <filename>?=</filename> operator, using a
2069 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
2070 will result in unexpected behavior when used in
2071 <filename>conf/local.conf</filename>.
2072 Furthermore, the same operation from within an image recipe may or may not
2073 succeed depending on the specific situation.
2074 In both these cases, the behavior is contrary to how most users expect
2075 the <filename>+=</filename> operator to work.
2076 </para>
2077
2078 <para>
2079 When you use this variable, it is best to use it as follows:
2080 <literallayout class='monospaced'>
2081 IMAGE_INSTALL_append = " package-name"
2082 </literallayout>
2083 Be sure to include the space between the quotation character and the start of the
2084 package name or names.
2085 </para>
2086 </glossdef>
2087 </glossentry>
2088
2089 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
2090 <glossdef>
2091 <para>
2092 Specifies the list of locales to install into the image
2093 during the root filesystem construction process.
2094 The OpenEmbedded build system automatically splits locale
2095 files, which are used for localization, into separate
2096 packages.
2097 Setting the <filename>IMAGE_LINGUAS</filename> variable
2098 ensures that any locale packages that correspond to packages
2099 already selected for installation into the image are also
2100 installed.
2101 Here is an example:
2102 <literallayout class='monospaced'>
2103 IMAGE_LINGUAS = "pt-br de-de"
2104 </literallayout>
2105 In this example, the build system ensures any Brazilian
2106 Portuguese and German locale files that correspond to
2107 packages in the image are installed (i.e.
2108 <filename>*-locale-pt-br</filename>
2109 and <filename>*-locale-de-de</filename> as well as
2110 <filename>*-locale-pt</filename>
2111 and <filename>*-locale-de</filename>, since some software
2112 packages only provide locale files by language and not by
2113 country-specific language).
2114 </para>
2115 </glossdef>
2116 </glossentry>
2117
2118 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
2119 <glossdef>
2120 <para>
2121 The name of the output image files minus the extension.
2122 This variable is derived using the
2123 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
2124 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
2125 and
2126 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
2127 variables:
2128 <literallayout class='monospaced'>
2129 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
2130 </literallayout>
2131 </para>
2132 </glossdef>
2133 </glossentry>
2134
2135 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
2136 <glossdef>
2137 <para>
2138 Defines a multiplier that the build system applies to the initial image
2139 size for cases when the multiplier times the returned disk usage value
2140 for the image is greater than the sum of
2141 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
2142 and
2143 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
2144 The result of the multiplier applied to the initial image size creates
2145 free disk space in the image as overhead.
2146 By default, the build process uses a multiplier of 1.3 for this variable.
2147 This default value results in 30% free disk space added to the image when this
2148 method is used to determine the final generated image size.
2149 You should be aware that post install scripts and the package management
2150 system uses disk space inside this overhead area.
2151 Consequently, the multiplier does not produce an image with
2152 all the theoretical free disk space.
2153 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
2154 for information on how the build system determines the overall image size.
2155 </para>
2156
2157 <para>
2158 The default 30% free disk space typically gives the image enough room to boot
2159 and allows for basic post installs while still leaving a small amount of
2160 free disk space.
2161 If 30% free space is inadequate, you can increase the default value.
2162 For example, the following setting gives you 50% free space added to the image:
2163 <literallayout class='monospaced'>
2164 IMAGE_OVERHEAD_FACTOR = "1.5"
2165 </literallayout>
2166 </para>
2167
2168 <para>
2169 Alternatively, you can ensure a specific amount of free disk space is added
2170 to the image by using the
2171 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
2172 variable.
2173 </para>
2174 </glossdef>
2175 </glossentry>
2176
2177 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
2178 <glossdef>
2179 <para>
2180 Added by classes to run post processing commands once the
2181 OpenEmbedded build system has created the image.
2182 You can specify shell commands separated by semicolons:
2183 <literallayout class='monospaced'>
2184 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
2185 </literallayout>
2186 If you need to pass the path to the root filesystem within
2187 the command, you can use
2188 <filename>${IMAGE_ROOTFS}</filename>, which points to
2189 the root filesystem image.
2190 </para>
2191 </glossdef>
2192 </glossentry>
2193
2194 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
2195 <glossdef>
2196 <para>
2197 The location of the root filesystem while it is under
2198 construction (i.e. during <filename>do_rootfs</filename>).
2199 This variable is not configurable.
2200 Do not change it.
2201 </para>
2202 </glossdef>
2203 </glossentry>
2204
2205 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
2206 <glossdef>
2207 <para>
2208 Defines additional free disk space created in the image in Kbytes.
2209 By default, this variable is set to "0".
2210 This free disk space is added to the image after the build system determines
2211 the image size as described in
2212 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
2213 </para>
2214
2215 <para>
2216 This variable is particularly useful when you want to ensure that a
2217 specific amount of free disk space is available on a device after an image
2218 is installed and running.
2219 For example, to be sure 5 Gbytes of free disk space is available, set the
2220 variable as follows:
2221 <literallayout class='monospaced'>
2222 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
2223 </literallayout>
2224 </para>
2225
2226 <para>
2227 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
2228 of extra space with the line:
2229 <literallayout class='monospaced'>
2230 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
2231 </literallayout>
2232 </para>
2233 </glossdef>
2234 </glossentry>
2235
2236 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
2237 <glossdef>
2238 <para>
2239 Defines the size in Kbytes for the generated image.
2240 The OpenEmbedded build system determines the final size for the generated
2241 image using an algorithm that takes into account the initial disk space used
2242 for the generated image, a requested size for the image, and requested
2243 additional free disk space to be added to the image.
2244 Programatically, the build system determines the final size of the
2245 generated image as follows:
2246 <literallayout class='monospaced'>
2247 if (image-du * overhead) &lt; rootfs-size:
2248 internal-rootfs-size = rootfs-size + xspace
2249 else:
2250 internal-rootfs-size = (image-du * overhead) + xspace
2251
2252 where:
2253
2254 image-du = Returned value of the du command on
2255 the image.
2256
2257 overhead = IMAGE_OVERHEAD_FACTOR
2258
2259 rootfs-size = IMAGE_ROOTFS_SIZE
2260
2261 internal-rootfs-size = Initial root filesystem
2262 size before any modifications.
2263
2264 xspace = IMAGE_ROOTFS_EXTRA_SPACE
2265 </literallayout>
2266 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
2267 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
2268 variables for related information.
2269<!-- In the above example, <filename>overhead</filename> is defined by the
2270 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
2271 variable, <filename>xspace</filename> is defined by the
2272 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
2273 variable, and <filename>du</filename> is the results of the disk usage command
2274 on the initially generated image. -->
2275 </para>
2276 </glossdef>
2277 </glossentry>
2278
2279 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
2280 <glossdef>
2281 <para>
2282 Specifies the complete list of supported image types
2283 by default:
2284 <literallayout class='monospaced'>
2285 jffs2
2286 sum.jffs2
2287 cramfs
2288 ext2
2289 ext2.gz
2290 ext2.bz2
2291 ext3
2292 ext3.gz
2293 ext2.lzma
2294 btrfs
2295 live
2296 squashfs
2297 squashfs-xz
2298 ubi
2299 ubifs
2300 tar
2301 tar.gz
2302 tar.bz2
2303 tar.xz
2304 cpio
2305 cpio.gz
2306 cpio.xz
2307 cpio.lzma
2308 vmdk
2309 elf
2310 </literallayout>
2311 For more information on how these types of images, see
2312 <filename>meta/classes/image_types*.bbclass</filename>
2313 in the
2314 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2315 </para>
2316 </glossdef>
2317 </glossentry>
2318
2319 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
2320 <glossdef>
2321 <para>Helps define the recipe revision for recipes that share
2322 a common <filename>include</filename> file.
2323 You can think of this variable as part of the recipe revision
2324 as set from within an include file.</para>
2325 <para>Suppose, for example, you have a set of recipes that
2326 are used across several projects.
2327 And, within each of those recipes the revision
2328 (its <link linkend='var-PR'><filename>PR</filename></link>
2329 value) is set accordingly.
2330 In this case, when the revision of those recipes changes,
2331 the burden is on you to find all those recipes and
2332 be sure that they get changed to reflect the updated
2333 version of the recipe.
2334 In this scenario, it can get complicated when recipes
2335 that are used in many places and provide common functionality
2336 are upgraded to a new revision.</para>
2337 <para>A more efficient way of dealing with this situation is
2338 to set the <filename>INC_PR</filename> variable inside
2339 the <filename>include</filename> files that the recipes
2340 share and then expand the <filename>INC_PR</filename>
2341 variable within the recipes to help
2342 define the recipe revision.
2343 </para>
2344 <para>
2345 The following provides an example that shows how to use
2346 the <filename>INC_PR</filename> variable
2347 given a common <filename>include</filename> file that
2348 defines the variable.
2349 Once the variable is defined in the
2350 <filename>include</filename> file, you can use the
2351 variable to set the <filename>PR</filename> values in
2352 each recipe.
2353 You will notice that when you set a recipe's
2354 <filename>PR</filename> you can provide more granular
2355 revisioning by appending values to the
2356 <filename>INC_PR</filename> variable:
2357 <literallayout class='monospaced'>
2358recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
2359recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
2360recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
2361recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2362 </literallayout>
2363 The first line of the example establishes the baseline
2364 revision to be used for all recipes that use the
2365 <filename>include</filename> file.
2366 The remaining lines in the example are from individual
2367 recipes and show how the <filename>PR</filename> value
2368 is set.</para>
2369 </glossdef>
2370 </glossentry>
2371
2372 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
2373 <glossdef>
2374 <para>
2375 Specifies a space-separated list of license names
2376 (as they would appear in
2377 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
2378 that should be excluded from the build.
2379 Recipes that provide no alternatives to listed incompatible
2380 licenses are not built.
2381 Packages that are individually licensed with the specified
2382 incompatible licenses will be deleted.
2383 </para>
2384
2385 <note>
2386 This functionality is only regularly tested using
2387 the following setting:
2388 <literallayout class='monospaced'>
2389 INCOMPATIBLE_LICENSE = "GPLv3"
2390 </literallayout>
2391 Although you can use other settings, you might be required
2392 to remove dependencies on or provide alternatives to
2393 components that are required to produce a functional system
2394 image.
2395 </note>
2396 </glossdef>
2397 </glossentry>
2398
2399 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
2400 <glossdef>
2401 <para>
2402 Prevents the default dependencies, namely the C compiler
2403 and standard C library (libc), from being added to
2404 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
2405 This variable is usually used within recipes that do not
2406 require any compilation using the C compiler.
2407 </para>
2408
2409 <para>
2410 Set the variable to "1" to prevent the default dependencies
2411 from being added.
2412 </para>
2413 </glossdef>
2414 </glossentry>
2415
2416 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
2417 <glossdef>
2418 <para>
2419 If set to "1", causes the build to not strip binaries in resulting packages.
2420 </para>
2421 </glossdef>
2422 </glossentry>
2423
2424 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
2425 <glossdef>
2426 <para>
2427 Causes the named class to be inherited at
2428 this point during parsing.
2429 The variable is only valid in configuration files.
2430 </para>
2431 </glossdef>
2432 </glossentry>
2433
2434 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
2435 <glossdef>
2436 <para>
2437 Defines the format for the output image of an initial
2438 RAM disk (initramfs), which is used during boot.
2439 Supported formats are the same as those supported by the
2440 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
2441 variable.
2442 </para>
2443 </glossdef>
2444 </glossentry>
2445
2446 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
2447 <glossdef>
2448 <para>
2449 The filename of the initialization script as installed to
2450 <filename>${sysconfdir}/init.d</filename>.
2451 </para>
2452 <para>
2453 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
2454 The variable is mandatory.
2455 </para>
2456 </glossdef>
2457 </glossentry>
2458
2459 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
2460 <glossdef>
2461 <para>
2462 A list of the packages that contain initscripts.
2463 If multiple packages are specified, you need to append the package name
2464 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
2465 <para>
2466 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
2467 The variable is optional and defaults to the
2468 <link linkend='var-PN'><filename>PN</filename></link> variable.
2469 </para>
2470 </glossdef>
2471 </glossentry>
2472
2473 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
2474 <glossdef>
2475 <para>
2476 Specifies the options to pass to <filename>update-rc.d</filename>.
2477 Here is an example:
2478 <literallayout class='monospaced'>
2479 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
2480 </literallayout>
2481 In this example, the script has a runlevel of 99,
2482 starts the script in initlevels 2 and 5, and
2483 stops the script in levels 0, 1 and 6.
2484 </para>
2485 <para>
2486 The variable is mandatory and is used in recipes when using
2487 <filename>update-rc.d.bbclass</filename>.
2488 </para>
2489 </glossdef>
2490 </glossentry>
2491
2492 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
2493 <glossdef>
2494 <para>
2495 Specifies the QA checks to skip for a specific package
2496 within a recipe.
2497 For example, to skip the check for symbolic link
2498 <filename>.so</filename> files in the main package of a
2499 recipe, add the following to the recipe.
2500 The package name override must be used, which in this
2501 example is <filename>${PN}</filename>:
2502 <literallayout class='monospaced'>
2503 INSANE_SKIP_${PN} += "dev-so"
2504 </literallayout>
2505 </para>
2506 <para>
2507 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
2508 section for a list of the valid QA checks you can
2509 specify using this variable.
2510 </para>
2511 </glossdef>
2512 </glossentry>
2513
2514 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
2515 <glossdef>
2516 <para>
2517 When the IPK backend is in use and package management
2518 is enabled on the target, you can use this variable to
2519 set up <filename>opkg</filename> in the target image
2520 to point to package feeds on a nominated server.
2521 Once the feed is established, you can perform
2522 installations or upgrades using the package manager
2523 at runtime.
2524 </para>
2525 </glossdef>
2526 </glossentry>
2527
2528<!--
2529 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
2530 <glossdef>
2531 <para>
2532 An environment variable that defines the directory where
2533 post installation hooks are installed for the
2534 post install environment.
2535 This variable is fixed as follows:
2536 <literallayout class='monospaced'>
2537 ${WORKDIR}/intercept_scripts
2538 </literallayout>
2539 </para>
2540
2541 <para>
2542 After installation of a target's root filesystem,
2543 post installation scripts, which are essentially bash scripts,
2544 are all executed just a single time.
2545 Limiting execution of these scripts minimizes installation
2546 time that would be lengthened due to certain packages
2547 triggering redundant operations.
2548 For example, consider the installation of font packages
2549 as a common example.
2550 Without limiting the execution of post installation scripts,
2551 all font directories would be rescanned to create the
2552 cache after each individual font package was installed.
2553 </para>
2554
2555 <para>
2556 Do not edit the <filename>INTERCEPT_DIR</filename>
2557 variable.
2558 </para>
2559 </glossdef>
2560 </glossentry>
2561-->
2562
2563 </glossdiv>
2564
2565<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
2566<!-- </glossdiv>-->
2567
2568 <glossdiv id='var-glossary-k'><title>K</title>
2569
2570 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
2571 <glossdef>
2572 <para>
2573 Defines the kernel architecture used when assembling
2574 the configuration.
2575 Architectures supported for this release are:
2576 <literallayout class='monospaced'>
2577 powerpc
2578 i386
2579 x86_64
2580 arm
2581 qemu
2582 mips
2583 </literallayout>
2584 </para>
2585
2586 <para>
2587 You define the <filename>KARCH</filename> variable in the
2588 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
2589 </para>
2590 </glossdef>
2591 </glossentry>
2592
2593 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
2594 <glossdef>
2595 <para>
2596 A regular expression used by the build process to explicitly identify the kernel
2597 branch that is validated, patched and configured during a build.
2598 The <filename>KBRANCH</filename> variable is optional.
2599 You can use it to trigger checks to ensure the exact kernel branch you want is
2600 being used by the build process.
2601 </para>
2602
2603 <para>
2604 Values for this variable are set in the kernel's recipe file and the kernel's
2605 append file.
2606 For example, if you are using the Yocto Project kernel that is based on the
2607 Linux 3.4 kernel, the kernel recipe file is the
2608 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file.
2609 Following is the default value for <filename>KBRANCH</filename> and the default
2610 override for the architectures the Yocto Project supports:
2611 <literallayout class='monospaced'>
2612 KBRANCH_DEFAULT = "standard/base"
2613 KBRANCH = "${KBRANCH_DEFAULT}"
2614 </literallayout>
2615 This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git
2616 repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
2617 </para>
2618
2619 <para>
2620 This variable is also used from the kernel's append file to identify the kernel
2621 branch specific to a particular machine or target hardware.
2622 The kernel's append file is located in the BSP layer for a given machine.
2623 For example, the kernel append file for the Crown Bay BSP is in the
2624 <filename>meta-intel</filename> Git repository and is named
2625 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>.
2626 Here are the related statements from the append file:
2627 <literallayout class='monospaced'>
2628 COMPATIBLE_MACHINE_crownbay = "crownbay"
2629 KMACHINE_crownbay = "crownbay"
2630 KBRANCH_crownbay = "standard/crownbay"
2631
2632 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
2633 KMACHINE_crownbay-noemgd = "crownbay"
2634 KBRANCH_crownbay-noemgd = "standard/crownbay"
2635 </literallayout>
2636 The <filename>KBRANCH_*</filename> statements identify the kernel branch to
2637 use when building for the Crown Bay BSP.
2638 In this case there are two identical statements: one for each type of
2639 Crown Bay machine.
2640 </para>
2641 </glossdef>
2642 </glossentry>
2643
2644 <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
2645 <glossdef>
2646 <para>
2647 Defines the Linux kernel source repository's default
2648 branch used to build the Linux kernel.
2649 The <filename>KBRANCH_DEFAULT</filename> value is
2650 the default value for
2651 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
2652 Unless you specify otherwise,
2653 <filename>KBRANCH_DEFAULT</filename> initializes to
2654 "master".
2655 </para>
2656 </glossdef>
2657 </glossentry>
2658
2659 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
2660 <glossdef>
2661 <para>
2662 Specifies additional <filename>make</filename>
2663 command-line arguments the OpenEmbedded build system
2664 passes on when compiling the kernel.
2665 </para>
2666 </glossdef>
2667 </glossentry>
2668
2669 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
2670 <glossdef>
2671 <para>Includes additional metadata from the Yocto Project kernel Git repository.
2672 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
2673 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
2674 is provided through
2675 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
2676 and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
2677 You can use the <filename>KERNEL_FEATURES</filename> variable to further
2678 add metadata for all BSPs.</para>
2679 <para>The metadata you add through this variable includes config fragments and
2680 features descriptions,
2681 which usually includes patches as well as config fragments.
2682 You typically override the <filename>KERNEL_FEATURES</filename> variable
2683 for a specific machine.
2684 In this way, you can provide validated, but optional, sets of kernel
2685 configurations and features.</para>
2686 <para>For example, the following adds <filename>netfilter</filename> to all
2687 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
2688 machine:
2689 <literallayout class='monospaced'>
2690 # Add netfilter to all linux-yocto kernels
2691 KERNEL_FEATURES="features/netfilter"
2692
2693 # Add sound support to the qemux86 machine
2694 KERNEL_FEATURES_append_qemux86=" cfg/sound"
2695 </literallayout></para>
2696 </glossdef>
2697 </glossentry>
2698
2699 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
2700 <glossdef>
2701 <para>The type of kernel to build for a device, usually set by the
2702 machine configuration files and defaults to "zImage".
2703 This variable is used
2704 when building the kernel and is passed to <filename>make</filename> as the target to
2705 build.</para>
2706 </glossdef>
2707 </glossentry>
2708
2709 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
2710 <glossdef>
2711 <para>
2712 The location of the kernel sources.
2713 This variable is set to the value of the
2714 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
2715 within the <filename>module.bbclass</filename> class.
2716 For information on how this variable is used, see the
2717 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
2718 section.
2719 </para>
2720
2721 <para>
2722 The <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
2723 variable is identical to the <filename>KERNEL_PATH</filename>
2724 variable.
2725 </para>
2726 </glossdef>
2727 </glossentry>
2728
2729 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
2730 <glossdef>
2731 <para>
2732 The location of the kernel sources.
2733 This variable is set to the value of the
2734 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
2735 within the <filename>module.bbclass</filename> class.
2736 For information on how this variable is used, see the
2737 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
2738 section.
2739 </para>
2740
2741 <para>
2742 The <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
2743 variable is identical to the <filename>KERNEL_SRC</filename>
2744 variable.
2745 </para>
2746 </glossdef>
2747 </glossentry>
2748
2749 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
2750 <glossdef>
2751 <para>
2752 Provides a short description of a configuration fragment.
2753 You use this variable in the <filename>.scc</filename>
2754 file that describes a configuration fragment file.
2755 Here is the variable used in a file named
2756 <filename>smp.scc</filename> to describe SMP being
2757 enabled:
2758 <literallayout class='monospaced'>
2759 define KFEATURE_DESCRIPTION "Enable SMP"
2760 </literallayout>
2761 </para>
2762 </glossdef>
2763 </glossentry>
2764
2765 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
2766 <glossdef>
2767 <para>
2768 The machine as known by the kernel.
2769 Sometimes the machine name used by the kernel does not match the machine name
2770 used by the OpenEmbedded build system.
2771 For example, the machine name that the OpenEmbedded build system understands as
2772 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
2773 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
2774 For cases like these, the <filename>KMACHINE</filename> variable maps the
2775 kernel machine name to the OpenEmbedded build system machine name.
2776 </para>
2777
2778 <para>
2779 Kernel machine names are initially defined in the
2780 Yocto Linux Kernel's <filename>meta</filename> branch.
2781 From the <filename>meta</filename> branch, look in
2782 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
2783 For example, from the <filename>meta</filename> branch in the
2784 <filename>linux-yocto-3.0</filename> kernel, the
2785 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
2786 has the following:
2787 <literallayout class='monospaced'>
2788 define KMACHINE cedartrail
2789 define KTYPE standard
2790 define KARCH i386
2791
2792 include ktypes/standard
2793 branch cedartrail
2794
2795 include cedartrail.scc
2796 </literallayout>
2797 You can see that the kernel understands the machine name for
2798 the Cedar Trail Board Support Package (BSP) as
2799 <filename>cedartrail</filename>.
2800 </para>
2801
2802 <para>
2803 If you look in the Cedar Trail BSP layer in the
2804 <filename>meta-intel</filename>
2805 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
2806 at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
2807 you will find the following statements among others:
2808 <literallayout class='monospaced'>
2809 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
2810 KMACHINE_cedartrail = "cedartrail"
2811 KBRANCH_cedartrail = "yocto/standard/cedartrail"
2812 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
2813 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
2814
2815 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
2816 KMACHINE_cedartrail-nopvr = "cedartrail"
2817 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
2818 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
2819 </literallayout>
2820 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
2821 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
2822 names.
2823 </para>
2824
2825 <para>
2826 This append file uses two <filename>KMACHINE</filename> statements.
2827 The first is not really necessary but does ensure that the machine known to the
2828 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
2829 in the kernel also known as <filename>cedartrail</filename>:
2830 <literallayout class='monospaced'>
2831 KMACHINE_cedartrail = "cedartrail"
2832 </literallayout>
2833 </para>
2834
2835 <para>
2836 The second statement is a good example of why the <filename>KMACHINE</filename> variable
2837 is needed.
2838 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
2839 machine name to refer to the Cedar Trail BSP that does not support the proprietary
2840 PowerVR driver.
2841 The kernel, however, uses the machine name <filename>cedartrail</filename>.
2842 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
2843 the kernel's <filename>cedartrail</filename> name:
2844 <literallayout class='monospaced'>
2845 KMACHINE_cedartrail-nopvr = "cedartrail"
2846 </literallayout>
2847 </para>
2848
2849 <para>
2850 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
2851 Project kernel machine names and the OpenEmbedded machine names.
2852 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
2853 name you use is different than that used in the kernel.
2854 </para>
2855 </glossdef>
2856 </glossentry>
2857
2858 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
2859 <glossdef>
2860 <para>
2861 Defines the kernel type to be used in assembling the
2862 configuration.
2863 The linux-yocto recipes define "standard", "tiny",
2864 and "preempt-rt" kernel types.
2865 See the
2866 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
2867 section in the Yocto Project Linux Kernel Development
2868 Manual for more information on kernel types.
2869 </para>
2870
2871 <para>
2872 You define the <filename>KTYPE</filename> variable in the
2873 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
2874 The value you use must match the value used for the
2875 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
2876 value used by the kernel recipe.
2877 </para>
2878 </glossdef>
2879 </glossentry>
2880 </glossdiv>
2881
2882 <glossdiv id='var-glossary-l'><title>L</title>
2883
2884 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
2885 <glossdef>
2886 <para>Lists the layers that this recipe depends upon, separated by spaces.
2887 Optionally, you can specify a specific layer version for a dependency
2888 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
2889 to be compared against
2890 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
2891 in this case).
2892 An error will be produced if any dependency is missing or
2893 the version numbers do not match exactly (if specified).
2894 This variable is used in the <filename>conf/layer.conf</filename> file
2895 and must be suffixed with the name of the specific layer (e.g.
2896 <filename>LAYERDEPENDS_mylayer</filename>).</para>
2897 </glossdef>
2898 </glossentry>
2899
2900 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
2901 <glossdef>
2902 <para>When used inside the <filename>layer.conf</filename> configuration
2903 file, this variable provides the path of the current layer.
2904 This variable is not available outside of <filename>layer.conf</filename>
2905 and references are expanded immediately when parsing of the file completes.</para>
2906 </glossdef>
2907 </glossentry>
2908
2909 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
2910 <glossdef>
2911 <para>Optionally specifies the version of a layer as a single number.
2912 You can use this within
2913 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
2914 for another layer in order to depend on a specific version
2915 of the layer.
2916 This variable is used in the <filename>conf/layer.conf</filename> file
2917 and must be suffixed with the name of the specific layer (e.g.
2918 <filename>LAYERVERSION_mylayer</filename>).</para>
2919 </glossdef>
2920 </glossentry>
2921
2922 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
2923 <glossdef>
2924 <para>Checksums of the license text in the recipe source code.</para>
2925 <para>This variable tracks changes in license text of the source
2926 code files.
2927 If the license text is changed, it will trigger a build
2928 failure, which gives the developer an opportunity to review any
2929 license change.</para>
2930 <para>
2931 This variable must be defined for all recipes (unless
2932 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2933 is set to "CLOSED")</para>
2934 <para>For more information, see the
2935 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
2936 Tracking License Changes</link> section</para>
2937 </glossdef>
2938 </glossentry>
2939
2940 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
2941 <glossdef>
2942 <para>
2943 The list of source licenses for the recipe.
2944 Follow these rules:
2945 <itemizedlist>
2946 <listitem><para>Do not use spaces within individual
2947 license names.</para></listitem>
2948 <listitem><para>Separate license names using
2949 | (pipe) when there is a choice between licenses.
2950 </para></listitem>
2951 <listitem><para>Separate license names using
2952 &amp; (ampersand) when multiple licenses exist
2953 that cover different parts of the source.
2954 </para></listitem>
2955 <listitem><para>You can use spaces between license
2956 names.</para></listitem>
2957 </itemizedlist>
2958 </para>
2959
2960 <para>
2961 Here are some examples:
2962 <literallayout class='monospaced'>
2963 LICENSE = "LGPLv2.1 | GPLv3"
2964 LICENSE = "MPL-1 &amp; LGPLv2.1"
2965 LICENSE = "GPLv2+"
2966 </literallayout>
2967 The first example is from the recipes for Qt, which the user
2968 may choose to distribute under either the LGPL version
2969 2.1 or GPL version 3.
2970 The second example is from Cairo where two licenses cover
2971 different parts of the source code.
2972 The final example is from <filename>sysstat</filename>,
2973 which presents a single license.
2974 </para>
2975
2976 <para>
2977 You can also specify licenses on a per-package basis to
2978 handle situations where components of the output have
2979 different licenses.
2980 For example, a piece of software whose code is
2981 licensed under GPLv2 but has accompanying documentation
2982 licensed under the GNU Free Documentation License 1.2 could
2983 be specified as follows:
2984 <literallayout class='monospaced'>
2985 LICENSE = "GFDL-1.2 &amp; GPLv2"
2986 LICENSE_${PN} = "GPLv2"
2987 LICENSE_${PN}-doc = "GFDL-1.2"
2988 </literallayout>
2989 </para>
2990 </glossdef>
2991 </glossentry>
2992
2993 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
2994 <glossdef>
2995 <para>Path to additional licenses used during the build.
2996 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
2997 to define the directory that holds common license text used during the build.
2998 The <filename>LICENSE_PATH</filename> variable allows you to extend that
2999 location to other areas that have additional licenses:
3000 <literallayout class='monospaced'>
3001 LICENSE_PATH += "/path/to/additional/common/licenses"
3002 </literallayout></para>
3003 </glossdef>
3004 </glossentry>
3005
3006 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
3007 <glossdef>
3008 <para>
3009 Defines the kernel type to be used in assembling the
3010 configuration.
3011 The linux-yocto recipes define "standard", "tiny", and
3012 "preempt-rt" kernel types.
3013 See the
3014 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
3015 section in the Yocto Project Linux Kernel Development
3016 Manual for more information on kernel types.
3017 </para>
3018
3019 <para>
3020 If you do not specify a
3021 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
3022 "standard".
3023 Together with
3024 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
3025 the <filename>LINUX_KERNEL_TYPE</filename> variable
3026 defines the search
3027 arguments used by the kernel tools to find the appropriate
3028 description within the kernel
3029 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
3030 with which to build out the sources and configuration.
3031 </para>
3032 </glossdef>
3033 </glossentry>
3034
3035 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
3036 <glossdef>
3037 <para>The Linux version from <filename>kernel.org</filename>
3038 on which the Linux kernel image being built using the
3039 OpenEmbedded build system is based.
3040 You define this variable in the kernel recipe.
3041 For example, the <filename>linux-yocto-3.4.bb</filename>
3042 kernel recipe found in
3043 <filename>meta/recipes-kernel/linux</filename>
3044 defines the variables as follows:
3045 <literallayout class='monospaced'>
3046 LINUX_VERSION ?= "3.4.24"
3047 </literallayout>
3048 The <filename>LINUX_VERSION</filename> variable is used to
3049 define <link linkend='var-PV'><filename>PV</filename></link>
3050 for the recipe:
3051 <literallayout class='monospaced'>
3052 PV = "${LINUX_VERSION}+git${SRCPV}"
3053 </literallayout></para>
3054 </glossdef>
3055 </glossentry>
3056
3057 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
3058 <glossdef>
3059 <para>A string extension compiled into the version
3060 string of the Linux kernel built with the OpenEmbedded
3061 build system.
3062 You define this variable in the kernel recipe.
3063 For example, the linux-yocto kernel recipes all define
3064 the variable as follows:
3065 <literallayout class='monospaced'>
3066 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
3067 </literallayout>
3068 Defining this variable essentially sets the
3069 Linux kernel configuration item
3070 <filename>CONFIG_LOCALVERSION</filename>, which is visible
3071 through the <filename>uname</filename> command.
3072 Here is an example that shows the extension assuming it
3073 was set as previously shown:
3074 <literallayout class='monospaced'>
3075 $ uname -r
3076 3.7.0-rc8-custom
3077 </literallayout>
3078 </para>
3079 </glossdef>
3080 </glossentry>
3081
3082 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
3083 <glossdef>
3084 <para>
3085 Specifies the directory to which the OpenEmbedded build
3086 system writes overall log files.
3087 The default directory is <filename>${TMPDIR}/log</filename>.
3088 </para>
3089 <para>
3090 For the directory containing logs specific to each task,
3091 see the <link linkend='var-T'><filename>T</filename></link>
3092 variable.
3093 </para>
3094 </glossdef>
3095 </glossentry>
3096
3097 </glossdiv>
3098
3099 <glossdiv id='var-glossary-m'><title>M</title>
3100
3101 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
3102 <glossdef>
3103 <para>
3104 Specifies the target device for which the image is built.
3105 You define <filename>MACHINE</filename> in the
3106 <filename>local.conf</filename> file found in the
3107 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
3108 By default, <filename>MACHINE</filename> is set to
3109 "qemux86", which is an x86-based architecture machine to
3110 be emulated using QEMU:
3111 <literallayout class='monospaced'>
3112 MACHINE ?= "qemux86"
3113 </literallayout>
3114 The variable corresponds to a machine configuration file of the
3115 same name, through which machine-specific configurations are set.
3116 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
3117 exists the corresponding <filename>qemux86.conf</filename> machine
3118 configuration file, which can be found in the
3119 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3120 in <filename>meta/conf/machine</filename>.
3121 </para>
3122
3123 <para>
3124 The list of machines supported by the Yocto Project as
3125 shipped include the following:
3126 <literallayout class='monospaced'>
3127 MACHINE ?= "qemuarm"
3128 MACHINE ?= "qemumips"
3129 MACHINE ?= "qemuppc"
3130 MACHINE ?= "qemux86"
3131 MACHINE ?= "qemux86-64"
3132 MACHINE ?= "genericx86"
3133 MACHINE ?= "genericx86-64"
3134 MACHINE ?= "beagleboard"
3135 MACHINE ?= "mpc8315e-rdb"
3136 MACHINE ?= "routerstationpro"
3137 </literallayout>
3138 The last five are Yocto Project reference hardware boards, which
3139 are provided in the <filename>meta-yocto-bsp</filename> layer.
3140 <note>Adding additional Board Support Package (BSP) layers
3141 to your configuration adds new possible settings for
3142 <filename>MACHINE</filename>.
3143 </note>
3144 </para>
3145 </glossdef>
3146 </glossentry>
3147
3148 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
3149 <glossdef>
3150 <para></para>
3151 <para>
3152 A list of required machine-specific packages to install as part of
3153 the image being built.
3154 The build process depends on these packages being present.
3155 Furthermore, because this is a "machine essential" variable, the list of
3156 packages are essential for the machine to boot.
3157 The impact of this variable affects images based on
3158 <filename>packagegroup-core-boot</filename>,
3159 including the <filename>core-image-minimal</filename> image.
3160 </para>
3161 <para>
3162 This variable is similar to the
3163 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
3164 variable with the exception that the image being built has a build
3165 dependency on the variable's list of packages.
3166 In other words, the image will not build if a file in this list is not found.
3167 </para>
3168 <para>
3169 As an example, suppose the machine for which you are building requires
3170 <filename>example-init</filename> to be run during boot to initialize the hardware.
3171 In this case, you would use the following in the machine's
3172 <filename>.conf</filename> configuration file:
3173 <literallayout class='monospaced'>
3174 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
3175 </literallayout>
3176 </para>
3177 </glossdef>
3178 </glossentry>
3179
3180 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
3181 <glossdef>
3182 <para></para>
3183 <para>
3184 A list of recommended machine-specific packages to install as part of
3185 the image being built.
3186 The build process does not depend on these packages being present.
3187 However, because this is a "machine essential" variable, the list of
3188 packages are essential for the machine to boot.
3189 The impact of this variable affects images based on
3190 <filename>packagegroup-core-boot</filename>,
3191 including the <filename>core-image-minimal</filename> image.
3192 </para>
3193 <para>
3194 This variable is similar to the
3195 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
3196 variable with the exception that the image being built does not have a build
3197 dependency on the variable's list of packages.
3198 In other words, the image will still build if a package in this list is not found.
3199 Typically, this variable is used to handle essential kernel modules, whose
3200 functionality may be selected to be built into the kernel rather than as a module,
3201 in which case a package will not be produced.
3202 </para>
3203 <para>
3204 Consider an example where you have a custom kernel where a specific touchscreen
3205 driver is required for the machine to be usable.
3206 However, the driver can be built as a module or
3207 into the kernel depending on the kernel configuration.
3208 If the driver is built as a module, you want it to be installed.
3209 But, when the driver is built into the kernel, you still want the
3210 build to succeed.
3211 This variable sets up a "recommends" relationship so that in the latter case,
3212 the build will not fail due to the missing package.
3213 To accomplish this, assuming the package for the module was called
3214 <filename>kernel-module-ab123</filename>, you would use the
3215 following in the machine's <filename>.conf</filename> configuration
3216 file:
3217 <literallayout class='monospaced'>
3218 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
3219 </literallayout>
3220 </para>
3221 <para>
3222 Some examples of these machine essentials are flash, screen, keyboard, mouse,
3223 or touchscreen drivers (depending on the machine).
3224 </para>
3225 </glossdef>
3226 </glossentry>
3227
3228 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
3229 <glossdef>
3230 <para>
3231 A list of machine-specific packages to install as part of the
3232 image being built that are not essential for the machine to boot.
3233 However, the build process for more fully-featured images
3234 depends on the packages being present.
3235 </para>
3236 <para>
3237 This variable affects all images based on
3238 <filename>packagegroup-base</filename>, which does not include the
3239 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
3240 images.
3241 </para>
3242 <para>
3243 The variable is similar to the
3244 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
3245 variable with the exception that the image being built has a build
3246 dependency on the variable's list of packages.
3247 In other words, the image will not build if a file in this list is not found.
3248 </para>
3249 <para>
3250 An example is a machine that has WiFi capability but is not
3251 essential for the machine to boot the image.
3252 However, if you are building a more fully-featured image, you want to enable
3253 the WiFi.
3254 The package containing the firmware for the WiFi hardware is always
3255 expected to exist, so it is acceptable for the build process to depend upon
3256 finding the package.
3257 In this case, assuming the package for the firmware was called
3258 <filename>wifidriver-firmware</filename>, you would use the following in the
3259 <filename>.conf</filename> file for the machine:
3260 <literallayout class='monospaced'>
3261 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
3262 </literallayout>
3263 </para>
3264 </glossdef>
3265 </glossentry>
3266
3267 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
3268 <glossdef>
3269 <para></para>
3270 <para>
3271 A list of machine-specific packages to install as part of the
3272 image being built that are not essential for booting the machine.
3273 The image being built has no build dependency on this list of packages.
3274 </para>
3275 <para>
3276 This variable affects only images based on
3277 <filename>packagegroup-base</filename>, which does not include the
3278 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
3279 images.
3280 </para>
3281 <para>
3282 This variable is similar to the
3283 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
3284 variable with the exception that the image being built does not have a build
3285 dependency on the variable's list of packages.
3286 In other words, the image will build if a file in this list is not found.
3287 </para>
3288 <para>
3289 An example is a machine that has WiFi capability but is not essential
3290 For the machine to boot the image.
3291 However, if you are building a more fully-featured image, you want to enable
3292 WiFi.
3293 In this case, the package containing the WiFi kernel module will not be produced
3294 if the WiFi driver is built into the kernel, in which case you still want the
3295 build to succeed instead of failing as a result of the package not being found.
3296 To accomplish this, assuming the package for the module was called
3297 <filename>kernel-module-examplewifi</filename>, you would use the
3298 following in the <filename>.conf</filename> file for the machine:
3299 <literallayout class='monospaced'>
3300 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
3301 </literallayout>
3302 </para>
3303 </glossdef>
3304 </glossentry>
3305
3306 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
3307 <glossdef>
3308 <para>Specifies the list of hardware features the
3309 <link linkend='var-MACHINE'>MACHINE</link> supports.
3310 For example, including the "bluetooth" feature causes the
3311 <filename>bluez</filename> bluetooth daemon to be built and
3312 added to the image.
3313 It also causes the <filename>connman</filename> recipe
3314 to look at <filename>MACHINE_FEATURES</filename> and when it
3315 finds "bluetooth" there it enables the bluetooth
3316 support in ConnMan.
3317 </para>
3318
3319 <para>
3320 For a list of features supported by the Yocto Project as shipped,
3321 see the "<link linkend='ref-features-machine'>Machine</link>" section.
3322 </para>
3323 </glossdef>
3324 </glossentry>
3325
3326 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
3327 <glossdef>
3328 <para>Features to be added to
3329 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
3330 if not also present in
3331 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
3332 </para>
3333
3334 <para>
3335 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
3336 It is not intended to be user-configurable.
3337 It is best to just reference the variable to see which machine features are
3338 being backfilled for all machine configurations.
3339 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
3340 more information.
3341 </para>
3342 </glossdef>
3343 </glossentry>
3344
3345 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
3346 <glossdef>
3347 <para>Features from
3348 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
3349 that should not be backfilled (i.e. added to
3350 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
3351 during the build.
3352 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
3353 more information.
3354 </para>
3355 </glossdef>
3356 </glossentry>
3357
3358 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
3359 <glossdef>
3360 <para>
3361 Lists overrides specific to the current machine.
3362 By default, this list includes the value
3363 of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
3364 You can extend the list to apply variable overrides for
3365 classes of machines.
3366 For example, all QEMU emulated machines (e.g. qemuarm,
3367 qemux86, and so forth) include a common file named
3368 <filename>meta/conf/machine/include/qemu.inc</filename>
3369 that prepends <filename>MACHINEOVERRIDES</filename> with
3370 the following variable override:
3371 <literallayout class='monospaced'>
3372 MACHINEOVERRIDES =. "qemuall:"
3373 </literallayout>
3374 Applying an override like <filename>qemuall</filename>
3375 affects all QEMU emulated machines elsewhere.
3376 Here is an example from the
3377 <filename>connman-conf</filename> recipe:
3378 <literallayout class='monospaced'>
3379 SRC_URI_append_qemuall = "file://wired.config \
3380 file://wired-setup \
3381 "
3382 </literallayout>
3383 </para>
3384 </glossdef>
3385 </glossentry>
3386
3387 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
3388 <glossdef>
3389 <para>The email address of the distribution maintainer.</para>
3390 </glossdef>
3391 </glossentry>
3392
3393 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
3394 <glossdef>
3395 <para>
3396 Specifies additional paths from which the OpenEmbedded
3397 build system gets source code.
3398 When the build system searches for source code, it first
3399 tries the local download directory.
3400 If that location fails, the build system tries locations
3401 defined by
3402 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
3403 the upstream source, and then locations specified by
3404 <filename>MIRRORS</filename> in that order.
3405 </para>
3406
3407 <para>
3408 Assuming your distribution
3409 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
3410 is "poky", the default value for
3411 <filename>MIRRORS</filename> is defined in the
3412 <filename>conf/distro/poky.conf</filename> file in the
3413 <filename>meta-yocto</filename> Git repository.
3414 </para>
3415 </glossdef>
3416 </glossentry>
3417
3418 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
3419 <glossdef>
3420 <para>
3421 Specifies a prefix has been added to
3422 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
3423 of a recipe or package, such as a Multilib version.
3424 The variable is used in places where the prefix needs to be
3425 added to or removed from a the name (e.g. the
3426 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
3427 <filename>MLPREFIX</filename> gets set when a prefix has been
3428 added to <filename>PN</filename>.
3429 </para>
3430 </glossdef>
3431 </glossentry>
3432
3433 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
3434 <glossdef>
3435 <para>
3436 Controls creation of the <filename>modules-*.tgz</filename>
3437 file.
3438 Set this variable to "0" to disable creation of this
3439 file, which contains all of the kernel modules resulting
3440 from a kernel build.
3441 </para>
3442 </glossdef>
3443 </glossentry>
3444
3445 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
3446 <glossdef>
3447 <para>
3448 Separates files for different machines such that you can build
3449 for multiple target machines using the same output directories.
3450 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
3451 for an example.
3452 </para>
3453 </glossdef>
3454 </glossentry>
3455
3456 </glossdiv>
3457
3458 <glossdiv id='var-glossary-n'><title>N</title>
3459
3460 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
3461 <glossdef>
3462 <para>
3463 A string identifying the host distribution.
3464 Strings consist of the host distributor ID
3465 followed by the release, as reported by the
3466 <filename>lsb_release</filename> tool
3467 or as read from <filename>/etc/lsb-release</filename>.
3468 For example, when running a build on Ubuntu 12.10, the value
3469 is "Ubuntu-12.10".
3470 If this information is unable to be determined, the value
3471 resolves to "Unknown".
3472 </para>
3473 <para>
3474 This variable is used by default to isolate native shared
3475 state packages for different distributions (e.g. to avoid
3476 problems with <filename>glibc</filename> version
3477 incompatibilities).
3478 Additionally, the variable is checked against
3479 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
3480 if that variable is set.
3481 </para>
3482 </glossdef>
3483 </glossentry>
3484
3485 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
3486 <glossdef>
3487 <para>
3488 Prevents installation of all "recommended-only" packages.
3489 Recommended-only packages are packages installed only
3490 through the
3491 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
3492 variable).
3493 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
3494 to "1" turns this feature on:
3495 <literallayout class='monospaced'>
3496 NO_RECOMMENDATIONS = "1"
3497 </literallayout>
3498 You can set this variable globally in your
3499 <filename>local.conf</filename> file or you can attach it to
3500 a specific image recipe by using the recipe name override:
3501 <literallayout class='monospaced'>
3502 NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
3503 </literallayout>
3504 </para>
3505
3506 <para>
3507 It is important to realize that if you choose to not install
3508 packages using this variable and some other packages are
3509 dependent on them (i.e. listed in a recipe's
3510 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3511 variable), the OpenEmbedded build system ignores your
3512 request and will install the packages to avoid dependency
3513 errors.
3514 <note>
3515 Some recommended packages might be required for certain
3516 system functionality, such as kernel modules.
3517 It is up to you to add packages with the
3518 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
3519 variable.
3520 </note>
3521 </para>
3522
3523 <para>
3524 Support for this variable exists only when using the
3525 IPK and RPM packaging backend.
3526 Support does not exist for DEB.
3527 </para>
3528
3529 <para>
3530 See the
3531 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
3532 and the
3533 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
3534 variables for related information.
3535 </para>
3536 </glossdef>
3537 </glossentry>
3538 </glossdiv>
3539
3540 <glossdiv id='var-glossary-o'><title>O</title>
3541
3542 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
3543 <glossdef>
3544 <para>
3545 When a recipe inherits the
3546 <filename>binconfig.bbclass</filename> class, this variable
3547 specifies additional arguments passed to the "sed" command.
3548 The sed command alters any paths in configuration scripts
3549 that have been set up during compilation.
3550 Inheriting this class results in all paths in these scripts
3551 being changed to point into the
3552 <filename>sysroots/</filename> directory so that all builds
3553 that use the script will use the correct directories
3554 for the cross compiling layout.
3555 </para>
3556
3557 <para>
3558 See the <filename>meta/classes/binconfig.bbclass</filename>
3559 in the
3560 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3561 for details on how this class applies these additional
3562 sed command arguments.
3563 For general information on the
3564 <filename>binconfig.bbclass</filename> class, see the
3565 "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
3566 section.
3567 </para>
3568 </glossdef>
3569 </glossentry>
3570
3571 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
3572 <glossdef>
3573 <para>
3574 An internal variable used to tell the OpenEmbedded build
3575 system what Python modules to import for every Python
3576 function run by the system.
3577 </para>
3578
3579 <note>
3580 Do not set this variable.
3581 It is for internal use only.
3582 </note>
3583 </glossdef>
3584 </glossentry>
3585
3586 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
3587 <glossdef>
3588 <para>
3589 Controls how the OpenEmbedded build system spawns
3590 interactive terminals on the host development system
3591 (e.g. using the BitBake command with the
3592 <filename>-c devshell</filename> command-line option).
3593 For more information, see the
3594 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
3595 in the Yocto Project Development Manual.
3596 </para>
3597
3598 <para>
3599 You can use the following values for the
3600 <filename>OE_TERMINAL</filename> variable:
3601 <literallayout class='monospaced'>
3602 auto
3603 gnome
3604 xfce
3605 rxvt
3606 screen
3607 konsole
3608 none
3609 </literallayout>
3610 <note>Konsole support only works for KDE 3.x.
3611 Also, "auto" is the default behavior for
3612 <filename>OE_TERMINAL</filename></note>
3613 </para>
3614 </glossdef>
3615 </glossentry>
3616
3617 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
3618 <glossdef>
3619 <para>
3620 The directory from which the top-level build environment
3621 setup script is sourced.
3622 The Yocto Project makes two top-level build environment
3623 setup scripts available:
3624 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
3625 and
3626 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
3627 When you run one of these scripts, the
3628 <filename>OEROOT</filename> variable resolves to the
3629 directory that holds the script.
3630 </para>
3631
3632 <para>
3633 For additional information on how this variable is used,
3634 see the initialization scripts.
3635 </para>
3636 </glossdef>
3637 </glossentry>
3638
3639 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
3640 <glossdef>
3641 <para>
3642 Declares the oldest version of the Linux kernel that the
3643 produced binaries must support.
3644 This variable is passed into the build of the Embedded
3645 GNU C Library (<filename>eglibc</filename>).
3646 </para>
3647
3648 <para>
3649 The default for this variable comes from the
3650 <filename>meta/conf/bitbake.conf</filename> configuration
3651 file.
3652 You can override this default by setting the variable
3653 in a custom distribution configuration file.
3654 </para>
3655 </glossdef>
3656 </glossentry>
3657
3658 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
3659 <glossdef>
3660 <para>
3661 BitBake uses <filename>OVERRIDES</filename> to control
3662 what variables are overridden after BitBake parses
3663 recipes and configuration files.
3664 You can find more information on how overrides are handled
3665 in the BitBake Manual that is located at
3666 <filename>bitbake/doc/manual</filename> in the
3667 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3668 </para>
3669 </glossdef>
3670 </glossentry>
3671 </glossdiv>
3672
3673 <glossdiv id='var-glossary-p'><title>P</title>
3674
3675 <glossentry id='var-P'><glossterm>P</glossterm>
3676 <glossdef>
3677 <para>The recipe name and version.
3678 <filename>P</filename> is comprised of the following:
3679 <literallayout class='monospaced'>
3680 ${PN}-${PV}
3681 </literallayout></para>
3682 </glossdef>
3683 </glossentry>
3684
3685 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
3686 <glossdef>
3687 <para>The architecture of the resulting package or packages.</para>
3688 </glossdef>
3689 </glossentry>
3690
3691 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
3692 <glossdef>
3693 <para>Enables easily adding packages to
3694 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
3695 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
3696 so that those added packages can pick up files that would normally be
3697 included in the default package.</para>
3698 </glossdef>
3699 </glossentry>
3700
3701 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
3702 <glossdef>
3703 <para>This variable, which is set in the <filename>local.conf</filename> configuration
3704 file found in the <filename>conf</filename> folder of the
3705 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
3706 specifies the package manager to use when packaging data.
3707 You can provide one or more arguments for the variable with the first
3708 argument being the package manager used to create images:
3709 <literallayout class='monospaced'>
3710 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
3711 </literallayout>
3712 For information on build performance effects as a result of the
3713 package manager use, see
3714 <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
3715 in this manual.
3716 </para>
3717 </glossdef>
3718 </glossentry>
3719
3720 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
3721 <glossdef>
3722 <para>
3723 Lists packages that should not be installed into an image.
3724 For example:
3725 <literallayout class='monospaced'>
3726 PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
3727 </literallayout>
3728 You can set this variable globally in your
3729 <filename>local.conf</filename> file or you can attach it to
3730 a specific image recipe by using the recipe name override:
3731 <literallayout class='monospaced'>
3732 PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
3733 </literallayout>
3734 </para>
3735
3736 <para>
3737 If you choose to not install
3738 a package using this variable and some other package is
3739 dependent on it (i.e. listed in a recipe's
3740 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3741 variable), the OpenEmbedded build system generates a fatal
3742 installation error.
3743 Because the build system halts the process with a fatal
3744 error, you can use the variable with an iterative
3745 development process to remove specific components from a
3746 system.
3747 </para>
3748
3749 <para>
3750 Support for this variable exists only when using the
3751 IPK and RPM packaging backend.
3752 Support does not exist for DEB.
3753 </para>
3754
3755 <para>
3756 See the
3757 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
3758 and the
3759 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
3760 variables for related information.
3761 </para>
3762 </glossdef>
3763 </glossentry>
3764
3765 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
3766 <glossdef>
3767 <para>Specifies the list of architectures compatible with the device CPU.
3768 This variable is useful when you build for several different devices that use
3769 miscellaneous processors such as XScale and ARM926-EJS).</para>
3770 </glossdef>
3771 </glossentry>
3772
3773 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
3774 <glossdef>
3775 <para>
3776 Defines one or more packages to include in an image when
3777 a specific item is included in
3778 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
3779 When setting the value, <filename>PACKAGE_GROUP</filename>
3780 should have the name of the feature item as an override.
3781 Here is an example:
3782 <literallayout class='monospaced'>
3783 PACKAGE_GROUP_widget = "package1 package2"
3784 </literallayout>
3785 In this example, if "widget" were added to
3786 <filename>IMAGE_FEATURES</filename>, "package1" and
3787 "package2" would be included in the image.
3788 <note>
3789 Packages installed by features defined through
3790 <filename>PACKAGE_GROUP</filename> are often package
3791 groups.
3792 While similarly named, you should not confuse the
3793 <filename>PACKAGE_GROUP</filename> variable with
3794 package groups, which are discussed elsewhere in the
3795 documentation.
3796 </note>
3797 </para>
3798 </glossdef>
3799 </glossentry>
3800
3801 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
3802 <glossdef>
3803 <para>
3804 The final list of packages passed to the package manager
3805 for installation into the image.
3806 Because the package manager controls actual installation
3807 of all packages, the list of packages passed using
3808 <filename>PACKAGE_INSTALL</filename> is not the final list
3809 of packages that are actually installed.
3810 </para>
3811
3812 <para>
3813 This variable is internal to the image construction
3814 code.
3815 Use the
3816 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
3817 variable to specify packages for installation.
3818 </para>
3819 </glossdef>
3820 </glossentry>
3821
3822 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
3823 <glossdef>
3824 <para>
3825 This variable provides a means of enabling or disabling
3826 features of a recipe on a per-recipe basis.
3827 <filename>PACKAGECONFIG</filename> blocks are defined
3828 in recipes when you specify features and then arguments
3829 that define feature behaviors.
3830 Here is the basic block structure:
3831 <literallayout class='monospaced'>
3832 PACKAGECONFIG ??= "f1 f2 f3 ..."
3833 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
3834 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
3835 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
3836 </literallayout>
3837 The <filename>PACKAGECONFIG</filename>
3838 variable itself specifies a space-separated list of the
3839 features to enable.
3840 Following the features, you can determine the behavior of
3841 each feature by providing up to four order-dependent
3842 arguments, which are separated by commas.
3843 You can omit any argument you like but must retain the
3844 separating commas.
3845 The order is important and specifies the following:
3846 <orderedlist>
3847 <listitem><para>Extra arguments
3848 that should be added to the configure script
3849 argument list
3850 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
3851 if the feature is enabled.</para></listitem>
3852 <listitem><para>Extra arguments
3853 that should be added to <filename>EXTRA_OECONF</filename>
3854 if the feature is disabled.
3855 </para></listitem>
3856 <listitem><para>Additional build dependencies
3857 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
3858 that should be added if the feature is enabled.
3859 </para></listitem>
3860 <listitem><para>Additional runtime dependencies
3861 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
3862 that should be added if the feature is enabled.
3863 </para></listitem>
3864 </orderedlist>
3865 </para>
3866
3867 <para>
3868 Consider the following
3869 <filename>PACKAGECONFIG</filename> block taken from the
3870 <filename>librsvg</filename> recipe.
3871 In this example the feature is <filename>croco</filename>,
3872 which has three arguments that determine the feature's
3873 behavior.
3874 <literallayout class='monospaced'>
3875 PACKAGECONFIG ??= "croco"
3876 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
3877 </literallayout>
3878 The <filename>--with-croco</filename> and
3879 <filename>libcroco</filename> arguments apply only if
3880 the feature is enabled.
3881 In this case, <filename>--with-croco</filename> is
3882 added to the configure script argument list and
3883 <filename>libcroco</filename> is added to
3884 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
3885 On the other hand, if the feature is disabled say through
3886 a <filename>.bbappend</filename> file in another layer, then
3887 the second argument <filename>--without-croco</filename> is
3888 added to the configure script rather than
3889 <filename>--with-croco</filename>.
3890 </para>
3891
3892 <para>
3893 The basic <filename>PACKAGECONFIG</filename> structure
3894 previously described holds true regardless of whether you
3895 are creating a block or changing a block.
3896 When creating a block, use the structure inside your
3897 recipe.
3898 </para>
3899
3900 <para>
3901 If you want to change an existing
3902 <filename>PACKAGECONFIG</filename> block, you can do so
3903 one of two ways:
3904 <itemizedlist>
3905 <listitem><para><emphasis>Append file:</emphasis>
3906 Create an append file named
3907 <filename>&lt;recipename&gt;.bbappend</filename> in your
3908 layer and override the value of
3909 <filename>PACKAGECONFIG</filename>.
3910 You can either completely override the variable:
3911 <literallayout class='monospaced'>
3912 PACKAGECONFIG="f4 f5"
3913 </literallayout>
3914 Or, you can just append the variable:
3915 <literallayout class='monospaced'>
3916 PACKAGECONFIG_append = " f4"
3917 </literallayout></para></listitem>
3918 <listitem><para><emphasis>Configuration file:</emphasis>
3919 This method is identical to changing the block
3920 through an append file except you edit your
3921 <filename>local.conf</filename> or
3922 <filename>&lt;mydistro&gt;.conf</filename> file.
3923 As with append files previously described,
3924 you can either completely override the variable:
3925 <literallayout class='monospaced'>
3926 PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
3927 </literallayout>
3928 Or, you can just amended the variable:
3929 <literallayout class='monospaced'>
3930 PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
3931 </literallayout></para></listitem>
3932 </itemizedlist>
3933 </para>
3934 </glossdef>
3935 </glossentry>
3936
3937 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
3938 <glossdef>
3939 <para>The list of packages to be created from the recipe.
3940 The default value is the following:
3941 <literallayout class='monospaced'>
3942 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
3943 </literallayout></para>
3944 </glossdef>
3945 </glossentry>
3946
3947 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
3948 <glossdef>
3949 <para>
3950 A promise that your recipe satisfies runtime dependencies
3951 for optional modules that are found in other recipes.
3952 <filename>PACKAGES_DYNAMIC</filename>
3953 does not actually satisfy the dependencies, it only states that
3954 they should be satisfied.
3955 For example, if a hard, runtime dependency
3956 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
3957 of another package is satisfied
3958 at build time through the <filename>PACKAGES_DYNAMIC</filename>
3959 variable, but a package with the module name is never actually
3960 produced, then the other package will be broken.
3961 Thus, if you attempt to include that package in an image,
3962 you will get a dependency failure from the packaging system
3963 during <filename>do_rootfs</filename>.
3964 </para>
3965 <para>
3966 Typically, if there is a chance that such a situation can
3967 occur and the package that is not created is valid
3968 without the dependency being satisfied, then you should use
3969 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
3970 (a soft runtime dependency) instead of
3971 <filename>RDEPENDS</filename>.
3972 </para>
3973
3974 <para>
3975 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
3976 variable when you are splitting packages, see the
3977 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
3978 in the Yocto Project Development Manual.
3979 </para>
3980 </glossdef>
3981 </glossentry>
3982
3983 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
3984 <glossdef>
3985 <para>
3986 Extra options that are passed to the
3987 <filename>make</filename> command during the
3988 <filename>do_compile</filename> task in order to specify
3989 parallel compilation.
3990 This variable is usually in the form
3991 <filename>-j 4</filename>, where the number
3992 represents the maximum number of parallel threads make can
3993 run.
3994 If you development host supports multiple cores a good
3995 rule of thumb is to set this variable to twice the number
3996 of cores on the host.
3997 <note>
3998 Individual recipes might clear out this variable if
3999 the software being built has problems running its
4000 <filename>make</filename> process in parallel.
4001 </note>
4002 </para>
4003 </glossdef>
4004 </glossentry>
4005
4006 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
4007 <glossdef>
4008 <para>
4009 Extra options passed to the
4010 <filename>make install</filename> command during the
4011 <filename>do_install</filename> task in order to specify
4012 parallel installation.
4013 This variable defaults to the value of
4014 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
4015 <note>
4016 Individual recipes might clear out this variable if
4017 the software being built has problems running its
4018 <filename>make install</filename> process in parallel.
4019 </note>
4020 </para>
4021 </glossdef>
4022 </glossentry>
4023
4024 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
4025 <glossdef>
4026 <para>
4027 Determines the action to take when a patch fails.
4028 You can set this variable to one of two values: "noop" and
4029 "user".
4030 </para>
4031
4032 <para>
4033 The default value of "noop" causes the build to simply fail
4034 when the OpenEmbedded build system cannot successfully
4035 apply a patch.
4036 Setting the value to "user" causes the build system to
4037 launch a shell and places you in the right location so that
4038 you can manually resolve the conflicts.
4039 </para>
4040
4041 <para>
4042 Set this variable in your
4043 <filename>local.conf</filename> file.
4044 </para>
4045 </glossdef>
4046 </glossentry>
4047
4048 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
4049 <glossdef>
4050 <para>
4051 Specifies the utility used to apply patches for a recipe
4052 during <filename>do_patch</filename>.
4053 You can specify one of three utilities: "patch", "quilt", or
4054 "git".
4055 The default utility used is "quilt" except for the
4056 quilt-native recipe itself.
4057 Because the quilt tool is not available at the
4058 time quilt-native is being patched, it uses "patch".
4059 </para>
4060
4061 <para>
4062 If you wish to use an alternative patching tool, set the
4063 variable in the recipe using one of the following:
4064 <literallayout class='monospaced'>
4065 PATCHTOOL = "patch"
4066 PATCHTOOL = "quilt"
4067 PATCHTOOL = "git"
4068 </literallayout>
4069 </para>
4070 </glossdef>
4071 </glossentry>
4072
4073 <glossentry id='var-PE'><glossterm>PE</glossterm>
4074 <glossdef>
4075 <para>
4076 the epoch of the recipe.
4077 By default, this variable is unset.
4078 The field is used to make upgrades possible when the
4079 versioning scheme changes in some backwards incompatible
4080 way.
4081 </para>
4082 </glossdef>
4083 </glossentry>
4084
4085 <glossentry id='var-PF'><glossterm>PF</glossterm>
4086 <glossdef>
4087 <para>Specifies the recipe or package name and includes all version and revision
4088 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
4089 <filename>bash-4.2-r1/</filename>).
4090 This variable is comprised of the following:
4091 <literallayout class='monospaced'>
4092 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
4093 </literallayout></para>
4094 </glossdef>
4095 </glossentry>
4096
4097 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
4098 <glossdef>
4099 <para>
4100 Points to the destination directory for files to be
4101 packaged before they are split into individual packages.
4102 This directory defaults to the following:
4103 <literallayout class='monospaced'>
4104 ${WORKDIR}/package
4105 </literallayout>
4106 Do not change this default.
4107 </para>
4108 </glossdef>
4109 </glossentry>
4110
4111 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
4112 <glossdef>
4113 <para>
4114 Points to a shared, global-state directory that holds data
4115 generated during the packaging process.
4116 During the packaging process, the
4117 <filename>do_packagedata</filename> task packages
4118 data for each recipe and installs it into this temporary,
4119 shared area.
4120 This directory defaults to the following:
4121 <literallayout class='monospaced'>
4122 ${STAGING_DIR_HOST}/pkgdata
4123 </literallayout>
4124 Do not change this default.
4125 </para>
4126 </glossdef>
4127 </glossentry>
4128
4129 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
4130 <glossdef>
4131 <para>
4132 Points to the parent directory for files to be packaged
4133 after they have been split into individual packages.
4134 This directory defaults to the following:
4135 <literallayout class='monospaced'>
4136 ${WORKDIR}/packages-split
4137 </literallayout>
4138 Under this directory, the build system creates
4139 directories for each package specified in
4140 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
4141 Do not change this default.
4142 </para>
4143 </glossdef>
4144 </glossentry>
4145
4146 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
4147 <glossdef>
4148 <para>
4149 Points to a temporary work area used by the
4150 <filename>do_package</filename> task to write output
4151 from the <filename>do_packagedata</filename> task.
4152 The <filename>PKGDESTWORK</filename> location defaults to
4153 the following:
4154 <literallayout class='monospaced'>
4155 ${WORKDIR}/pkgdata
4156 </literallayout>
4157 The <filename>do_packagedata</filename> task then packages
4158 the data in the temporary work area and installs it into a
4159 shared directory pointed to by
4160 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
4161 </para>
4162
4163 <para>
4164 Do not change this default.
4165 </para>
4166 </glossdef>
4167 </glossentry>
4168
4169 <glossentry id='var-PN'><glossterm>PN</glossterm>
4170 <glossdef>
4171 <para>This variable can have two separate functions depending on the context: a recipe
4172 name or a resulting package name.</para>
4173 <para><filename>PN</filename> refers to a recipe name in the context of a file used
4174 by the OpenEmbedded build system as input to create a package.
4175 The name is normally extracted from the recipe file name.
4176 For example, if the recipe is named
4177 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
4178 will be "expat".</para>
4179 <para>
4180 The variable refers to a package name in the context of a file created or produced by the
4181 OpenEmbedded build system.</para>
4182 <para>If applicable, the <filename>PN</filename> variable also contains any special
4183 suffix or prefix.
4184 For example, using <filename>bash</filename> to build packages for the native
4185 machine, <filename>PN</filename> is <filename>bash-native</filename>.
4186 Using <filename>bash</filename> to build packages for the target and for Multilib,
4187 <filename>PN</filename> would be <filename>bash</filename> and
4188 <filename>lib64-bash</filename>, respectively.
4189 </para>
4190 </glossdef>
4191 </glossentry>
4192
4193 <glossentry id='var-PR'><glossterm>PR</glossterm>
4194 <glossdef>
4195 <para>The revision of the recipe.
4196 The default value for this variable is "r0".
4197 </para>
4198 </glossdef>
4199 </glossentry>
4200
4201 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
4202 <glossdef>
4203 <para>
4204 If multiple recipes provide an item, this variable
4205 determines which recipe should be given preference.
4206 You should always suffix the variable with the name of the
4207 provided item, and you should set it to the
4208 <link linkend='var-PN'><filename>PN</filename></link>
4209 of the recipe to which you want to give precedence.
4210 Some examples:
4211 <literallayout class='monospaced'>
4212 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
4213 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
4214 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
4215 </literallayout>
4216 </para>
4217 </glossdef>
4218 </glossentry>
4219
4220 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
4221 <glossdef>
4222 <para>
4223 If there are multiple versions of recipes available, this
4224 variable determines which recipe should be given preference.
4225 You must always suffix the variable with the
4226 <link linkend='var-PN'><filename>PN</filename></link>
4227 you want to select, and you should set the
4228 <link linkend='var-PV'><filename>PV</filename></link>
4229 accordingly for precedence.
4230 You can use the "<filename>%</filename>" character as a
4231 wildcard to match any number of characters, which can be
4232 useful when specifying versions that contain long revision
4233 numbers that could potentially change.
4234 Here are two examples:
4235 <literallayout class='monospaced'>
4236 PREFERRED_VERSION_python = "2.7.3"
4237 PREFERRED_VERSION_linux-yocto = "3.10%"
4238 </literallayout>
4239 </para>
4240 </glossdef>
4241 </glossentry>
4242
4243 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
4244 <glossdef>
4245 <para>
4246 Specifies additional paths from which the OpenEmbedded
4247 build system gets source code.
4248 When the build system searches for source code, it first
4249 tries the local download directory.
4250 If that location fails, the build system tries locations
4251 defined by <filename>PREMIRRORS</filename>, the upstream
4252 source, and then locations specified by
4253 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
4254 in that order.
4255 </para>
4256
4257 <para>
4258 Assuming your distribution
4259 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
4260 is "poky", the default value for
4261 <filename>PREMIRRORS</filename> is defined in the
4262 <filename>conf/distro/poky.conf</filename> file in the
4263 <filename>meta-yocto</filename> Git repository.
4264 </para>
4265
4266 <para>
4267 Typically, you could add a specific server for the
4268 build system to attempt before any others by adding
4269 something like the following to the
4270 <filename>local.conf</filename> configuration file in the
4271 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
4272 <literallayout class='monospaced'>
4273 PREMIRRORS_prepend = "\
4274 git://.*/.* http://www.yoctoproject.org/sources/ \n \
4275 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
4276 http://.*/.* http://www.yoctoproject.org/sources/ \n \
4277 https://.*/.* http://www.yoctoproject.org/sources/ \n"
4278 </literallayout>
4279 These changes cause the build system to intercept
4280 Git, FTP, HTTP, and HTTPS requests and direct them to
4281 the <filename>http://</filename> sources mirror.
4282 You can use <filename>file://</filename> URLs to point
4283 to local directories or network shares as well.
4284 </para>
4285 </glossdef>
4286 </glossentry>
4287
4288 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
4289 <glossdef>
4290 <para>Causes the <link linkend='var-PR'><filename>PR</filename></link>
4291 variable of <filename>.bbappend</filename> files to
4292 dynamically increment.
4293 This increment minimizes the impact of layer ordering.</para>
4294 <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist,
4295 <filename>PRINC</filename> should be self-referencing.
4296 This variable defaults to 0.</para>
4297 <para>Following is an example that increments <filename>PR</filename> by two:
4298 <literallayout class='monospaced'>
4299 PRINC := "${@int(PRINC) + 2}"
4300 </literallayout>
4301 It is advisable not to use strings such as ".= '.1'" with the variable because
4302 this usage is very sensitive to layer ordering.
4303 You should avoid explicit assignments as they cannot
4304 adequately represent multiple
4305 <filename>.bbappend</filename> files.</para>
4306 </glossdef>
4307 </glossentry>
4308
4309 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
4310 <glossdef>
4311 <para>
4312 A list of aliases that a recipe also provides.
4313 These aliases are useful for satisfying dependencies of
4314 other recipes during the build (as specified by
4315 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>).
4316 <note>
4317 A recipe's own
4318 <filename><link linkend='var-PN'>PN</link></filename>
4319 is implicitly already in its
4320 <filename>PROVIDES</filename> list.
4321 </note>
4322 </para>
4323 </glossdef>
4324 </glossentry>
4325
4326 <glossentry id='var-PV'><glossterm>PV</glossterm>
4327 <glossdef>
4328 <para>The version of the recipe.
4329 The version is normally extracted from the recipe filename.
4330 For example, if the recipe is named
4331 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
4332 will be "2.0.1".
4333 <filename>PV</filename> is generally not overridden within
4334 a recipe unless it is building an unstable (i.e. development) version from a source code repository
4335 (e.g. Git or Subversion).
4336 </para>
4337 </glossdef>
4338 </glossentry>
4339
4340 </glossdiv>
4341
4342<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
4343<!-- </glossdiv>-->
4344
4345 <glossdiv id='var-glossary-r'><title>R</title>
4346
4347 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
4348 <glossdef>
4349 <para>
4350 The list of packages that conflict with packages.
4351 Note that packages will not be installed if conflicting
4352 packages are not first removed.
4353 </para>
4354
4355 <para>
4356 Like all package-controlling variables, you must always use
4357 them in conjunction with a package name override.
4358 Here is an example:
4359 <literallayout class='monospaced'>
4360 RCONFLICTS_${PN} = "another-conflicting-package-name"
4361 </literallayout>
4362 </para>
4363
4364 <para>
4365 BitBake, which the OpenEmbedded build system uses, supports
4366 specifying versioned dependencies.
4367 Although the syntax varies depending on the packaging
4368 format, BitBake hides these differences from you.
4369 Here is the general syntax to specify versions with
4370 the <filename>RCONFLICTS</filename> variable:
4371 <literallayout class='monospaced'>
4372 RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4373 </literallayout>
4374 For <filename>operator</filename>, you can specify the
4375 following:
4376 <literallayout class='monospaced'>
4377 =
4378 &lt;
4379 &gt;
4380 &lt;=
4381 &gt;=
4382 </literallayout>
4383 For example, the following sets up a dependency on version
4384 1.2 or greater of the package <filename>foo</filename>:
4385 <literallayout class='monospaced'>
4386 RCONFLICTS_${PN} = "foo (>= 1.2)"
4387 </literallayout>
4388 </para>
4389 </glossdef>
4390 </glossentry>
4391
4392 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
4393 <glossdef>
4394 <para>
4395 Lists a package's runtime dependencies (i.e. other packages)
4396 that must be installed in order for the built package to run
4397 correctly.
4398 If a package in this list cannot be found during the build,
4399 you will get a build error.
4400 </para>
4401
4402 <para>
4403 When you use the <filename>RDEPENDS</filename> variable
4404 in a recipe, you are essentially stating that the recipe's
4405 <filename>do_build</filename> task depends on the existence
4406 of a specific package.
4407 Consider this simple example for two recipes named "a" and
4408 "b" that produce similarly named packages.
4409 In this example, the <filename>RDEPENDS</filename>
4410 statement appears in the "a" recipe:
4411 <literallayout class='monospaced'>
4412 RDEPENDS_${PN} = "b"
4413 </literallayout>
4414 Here, the dependency is such that the
4415 <filename>do_build</filename> task for recipe "a" depends
4416 on the <filename>do_package_write</filename> task
4417 of recipe "b".
4418 This means the package file for "b" must be available when
4419 the output for recipe "a" has been completely built.
4420 More importantly, package "a" will be marked as depending
4421 on package "b" in a manner that is understood by the
4422 package manager in use (i.e. rpm, opkg, or dpkg).
4423 </para>
4424
4425 <para>
4426 The names of the packages you list within
4427 <filename>RDEPENDS</filename> must be the names of other
4428 packages - they cannot be recipe names.
4429 Although package names and recipe names usually match,
4430 the important point here is that you are
4431 providing package names within the
4432 <filename>RDEPENDS</filename> variable.
4433 For an example of the default list of packages created from
4434 a recipe, see the
4435 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
4436 variable.
4437 </para>
4438
4439 <para>
4440 Because the <filename>RDEPENDS</filename> variable applies
4441 to packages being built, you should always use the variable
4442 in a form with an attached package name.
4443 For example, suppose you are building a development package
4444 that depends on the <filename>perl</filename> package.
4445 In this case, you would use the following
4446 <filename>RDEPENDS</filename> statement:
4447 <literallayout class='monospaced'>
4448 RDEPENDS_${PN}-dev += "perl"
4449 </literallayout>
4450 In the example, the development package depends on
4451 the <filename>perl</filename> package.
4452 Thus, the <filename>RDEPENDS</filename> variable has the
4453 <filename>${PN}-dev</filename> package name as part of the
4454 variable.
4455 </para>
4456
4457 <para>
4458 The package name you attach to the
4459 <filename>RDEPENDS</filename> variable must appear
4460 as it would in the <filename>PACKAGES</filename>
4461 namespace before any renaming of the output package by
4462 classes like <filename>debian.bbclass</filename>.
4463 </para>
4464
4465 <para>
4466 In many cases you do not need to explicitly add
4467 runtime dependencies using
4468 <filename>RDEPENDS</filename> since some automatic
4469 handling occurs:
4470 <itemizedlist>
4471 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
4472 a runtime package contains a shared library
4473 (<filename>.so</filename>), the build
4474 processes the library in order to determine other
4475 libraries to which it is dynamically linked.
4476 The build process adds these libraries to
4477 <filename>RDEPENDS</filename> when creating the runtime
4478 package.</para></listitem>
4479 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
4480 the package ships a <filename>pkg-config</filename>
4481 information file, the build process uses this file
4482 to add items to the <filename>RDEPENDS</filename>
4483 variable to create the runtime packages.
4484 </para></listitem>
4485 </itemizedlist>
4486 </para>
4487
4488 <para>
4489 BitBake, which the OpenEmbedded build system uses, supports
4490 specifying versioned dependencies.
4491 Although the syntax varies depending on the packaging
4492 format, BitBake hides these differences from you.
4493 Here is the general syntax to specify versions with
4494 the <filename>RDEPENDS</filename> variable:
4495 <literallayout class='monospaced'>
4496 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4497 </literallayout>
4498 For <filename>operator</filename>, you can specify the
4499 following:
4500 <literallayout class='monospaced'>
4501 =
4502 &lt;
4503 &gt;
4504 &lt;=
4505 &gt;=
4506 </literallayout>
4507 For example, the following sets up a dependency on version
4508 1.2 or greater of the package <filename>foo</filename>:
4509 <literallayout class='monospaced'>
4510 RDEPENDS_${PN} = "foo (>= 1.2)"
4511 </literallayout>
4512 </para>
4513
4514 <para>
4515 For information on build-time dependencies, see the
4516 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
4517 variable.
4518 </para>
4519 </glossdef>
4520 </glossentry>
4521
4522 <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
4523 <glossdef>
4524 <para>
4525 Reclaims disk space by removing previously built
4526 versions of the same image from the
4527 <filename>images</filename> directory pointed to by the
4528 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
4529 variable.
4530 </para>
4531
4532 <para>
4533 Set this variable to "1" in your
4534 <filename>local.conf</filename> file to remove these
4535 images.
4536 </para>
4537 </glossdef>
4538 </glossentry>
4539
4540 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
4541 <glossdef>
4542 <para>
4543 With <filename>rm_work</filename> enabled, this
4544 variable specifies a list of recipes whose work directories
4545 should not be removed.
4546 See the "<link linkend='ref-classes-rm-work'>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></link>"
4547 section for more details.
4548 </para>
4549 </glossdef>
4550 </glossentry>
4551
4552 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
4553 <glossdef>
4554 <para>
4555 Added by classes to run post processing commands once the
4556 OpenEmbedded build system has created the root filesystem.
4557 You can specify shell commands separated by semicolons:
4558 <literallayout class='monospaced'>
4559 ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
4560 </literallayout>
4561 If you need to pass the path to the root filesystem within
4562 the command, you can use
4563 <filename>${IMAGE_ROOTFS}</filename>, which points to
4564 the root filesystem image.
4565 </para>
4566 </glossdef>
4567 </glossentry>
4568
4569 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
4570 <glossdef>
4571 <para>
4572 A list of package name aliases that a package also provides.
4573 These aliases are useful for satisfying runtime dependencies
4574 of other packages both during the build and on the target
4575 (as specified by
4576 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
4577 <note>
4578 A package's own name is implicitly already in its
4579 <filename>RPROVIDES</filename> list.
4580 </note>
4581 </para>
4582 <para>
4583 As with all package-controlling variables, you must always
4584 use the variable in conjunction with a package name override.
4585 Here is an example:
4586 <literallayout class='monospaced'>
4587 RPROVIDES_${PN} = "widget-abi-2"
4588 </literallayout>
4589 </para>
4590 </glossdef>
4591 </glossentry>
4592
4593 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
4594 <glossdef>
4595 <para>
4596 A list of packages that extends the usability of a package
4597 being built.
4598 The package being built does not depend on this list of
4599 packages in order to successfully build, but needs them for
4600 the extended usability.
4601 To specify runtime dependencies for packages, see the
4602 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
4603 variable.
4604 </para>
4605
4606 <para>
4607 The OpenEmbedded build process automatically installs the
4608 list of packages as part of the built package.
4609 However, you can remove these packages later if you want.
4610 If, during the build, a package from the
4611 <filename>RRECOMMENDS</filename> list cannot be
4612 found, the build process continues without an error.
4613 </para>
4614
4615 <para>
4616 You can also prevent packages in the list from being
4617 installed by using several variables.
4618 See the
4619 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
4620 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
4621 and
4622 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
4623 variables for more information.
4624 </para>
4625
4626 <para>
4627 Because the <filename>RRECOMMENDS</filename> variable
4628 applies to packages being built, you should always attach
4629 an override to the variable to specify the particular
4630 package whose usability is being extended.
4631 For example, suppose you are building a development package
4632 that is extended to support wireless functionality.
4633 In this case, you would use the following:
4634 <literallayout class='monospaced'>
4635 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
4636 </literallayout>
4637 In the example, the package name
4638 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
4639 must appear as it would in the
4640 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
4641 namespace before any renaming of the output package by
4642 classes such as <filename>debian.bbclass</filename>.
4643 </para>
4644
4645 <para>
4646 BitBake, which the OpenEmbedded build system uses, supports
4647 specifying versioned recommends.
4648 Although the syntax varies depending on the packaging
4649 format, BitBake hides these differences from you.
4650 Here is the general syntax to specify versions with
4651 the <filename>RRECOMMENDS</filename> variable:
4652 <literallayout class='monospaced'>
4653 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4654 </literallayout>
4655 For <filename>operator</filename>, you can specify the
4656 following:
4657 <literallayout class='monospaced'>
4658 =
4659 &lt;
4660 &gt;
4661 &lt;=
4662 &gt;=
4663 </literallayout>
4664 For example, the following sets up a recommend on version
4665 1.2 or greater of the package <filename>foo</filename>:
4666 <literallayout class='monospaced'>
4667 RRECOMMENDS_${PN} = "foo (>= 1.2)"
4668 </literallayout>
4669 </para>
4670 </glossdef>
4671 </glossentry>
4672
4673 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
4674 <glossdef>
4675 <para>
4676 A list of packages replaced by a package.
4677 The package manager uses this variable to determine which
4678 package should be installed to replace other package(s)
4679 during an upgrade.
4680 In order to also have the other package(s) removed at the
4681 same time, you must add the name of the other
4682 package to the
4683 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
4684 </para>
4685 <para>
4686 As with all package-controlling variables, you must use
4687 this variable in conjunction with a package name
4688 override.
4689 Here is an example:
4690 <literallayout class='monospaced'>
4691 RREPLACES_${PN} = "other-package-being-replaced"
4692 </literallayout>
4693 </para>
4694
4695 <para>
4696 BitBake, which the OpenEmbedded build system uses, supports
4697 specifying versioned replacements.
4698 Although the syntax varies depending on the packaging
4699 format, BitBake hides these differences from you.
4700 Here is the general syntax to specify versions with
4701 the <filename>RREPLACES</filename> variable:
4702 <literallayout class='monospaced'>
4703 RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4704 </literallayout>
4705 For <filename>operator</filename>, you can specify the
4706 following:
4707 <literallayout class='monospaced'>
4708 =
4709 &lt;
4710 &gt;
4711 &lt;=
4712 &gt;=
4713 </literallayout>
4714 For example, the following sets up a replacement using
4715 version 1.2 or greater of the package
4716 <filename>foo</filename>:
4717 <literallayout class='monospaced'>
4718 RREPLACES_${PN} = "foo (>= 1.2)"
4719 </literallayout>
4720 </para>
4721 </glossdef>
4722 </glossentry>
4723
4724 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
4725 <glossdef>
4726 <para>
4727 A list of additional packages that you can suggest for
4728 installation by the package manager at the time a package
4729 is installed.
4730 Not all package managers support this functionality.
4731 </para>
4732 <para>
4733 As with all package-controlling variables, you must always
4734 use this variable in conjunction with a package name
4735 override.
4736 Here is an example:
4737 <literallayout class='monospaced'>
4738 RSUGGESTS_${PN} = "useful-package another-package"
4739 </literallayout>
4740 </para>
4741 </glossdef>
4742 </glossentry>
4743
4744 </glossdiv>
4745
4746 <glossdiv id='var-glossary-s'><title>S</title>
4747
4748 <glossentry id='var-S'><glossterm>S</glossterm>
4749 <glossdef>
4750 <para>
4751 The location in the
4752 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
4753 where unpacked recipe source code resides.
4754 This location is within the working directory
4755 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
4756 which is not static.
4757 The unpacked source location depends on the recipe name
4758 (<filename><link linkend='var-PN'>PN</link></filename>) and
4759 recipe version
4760 (<filename><link linkend='var-PV'>PV</link></filename>) as
4761 follows:
4762 <literallayout class='monospaced'>
4763 ${WORKDIR}/${PN}-${PV}
4764 </literallayout>
4765 As an example, assume a
4766 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4767 top-level folder named <filename>poky</filename> and a
4768 default Build Directory at <filename>poky/build</filename>.
4769 In this case, the working directory the build system uses
4770 to keep the unpacked recipe for <filename>db</filename>
4771 is the following:
4772 <literallayout class='monospaced'>
4773 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
4774 </literallayout>
4775 </para>
4776 </glossdef>
4777 </glossentry>
4778
4779 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
4780 <glossdef>
4781 <para>
4782 A list of the host distribution identifiers that the
4783 build system has been tested against.
4784 Identifiers consist of the host distributor ID
4785 followed by the release,
4786 as reported by the <filename>lsb_release</filename> tool
4787 or as read from <filename>/etc/lsb-release</filename>.
4788 Separate the list items with explicit newline
4789 characters (<filename>\n</filename>).
4790 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
4791 and the current value of
4792 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
4793 does not appear in the list, then the build system reports
4794 a warning that indicates the current host distribution has
4795 not been tested as a build host.
4796 </para>
4797 </glossdef>
4798 </glossentry>
4799
4800 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
4801 <glossdef>
4802 <para>
4803 The target architecture for the SDK.
4804 Typically, you do not directly set this variable.
4805 Instead, use
4806 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
4807 </para>
4808 </glossdef>
4809 </glossentry>
4810
4811 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
4812 <glossdef>
4813 <para>
4814 The base name for SDK output files.
4815 The name is derived from the
4816 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
4817 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
4818 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
4819 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
4820 and
4821 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
4822 variables:
4823 <literallayout class='monospaced'>
4824 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
4825 </literallayout>
4826 </para>
4827 </glossdef>
4828 </glossentry>
4829
4830 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
4831 <glossdef>
4832 <para>Equivalent to
4833 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
4834 However, this variable applies to the SDK generated from an
4835 image using the following command:
4836 <literallayout class='monospaced'>
4837 $ bitbake -c populate_sdk imagename
4838 </literallayout>
4839 </para>
4840 </glossdef>
4841 </glossentry>
4842
4843 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
4844 <glossdef>
4845 <para>
4846 The architecture of the machine that runs Application
4847 Development Toolkit (ADT) items.
4848 In other words, packages are built so that they will run
4849 on the target you specify with the argument.
4850 This implies that you can build out ADT/SDK items that
4851 run on an architecture other than that of your build host.
4852 For example, you can use an x86_64-based build host to
4853 create packages that will run on an i686-based
4854 SDK Machine.
4855 </para>
4856
4857 <para>
4858 You can use "i686" and "x86_64" as possible values for this
4859 variable.
4860 The variable defaults to "i686" and is set in the
4861 <filename>local.conf</filename> file in the
4862 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
4863 <literallayout class='monospaced'>
4864 SDKMACHINE ?= "i686"
4865 </literallayout>
4866 </para>
4867 </glossdef>
4868 </glossentry>
4869
4870 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
4871 <glossdef>
4872 <para>The section in which packages should be categorized.
4873 Package management utilities can make use of this variable.</para>
4874 </glossdef>
4875 </glossentry>
4876
4877 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
4878 <glossdef>
4879 <para>
4880 The variable takes the value of
4881 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
4882 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
4883 In this case the value of
4884 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
4885 </para>
4886 </glossdef>
4887 </glossentry>
4888
4889 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
4890 <glossdef>
4891 <para>
4892 Defines a serial console (TTY) to enable using getty.
4893 Provide a value that specifies the baud rate followed by
4894 the TTY device name separated by a space.
4895 You cannot specify more than one TTY device:
4896 <literallayout class='monospaced'>
4897 SERIAL_CONSOLE = "115200 ttyS0"
4898 </literallayout>
4899 <note>
4900 The <filename>SERIAL_CONSOLE</filename> variable
4901 is deprecated.
4902 Please use the
4903 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
4904 variable.
4905 </note>
4906 </para>
4907 </glossdef>
4908 </glossentry>
4909
4910 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
4911 <glossdef>
4912 <para>
4913 Defines the serial consoles (TTYs) to enable using getty.
4914 Provide a value that specifies the baud rate followed by
4915 the TTY device name separated by a semicolon.
4916 Use spaces to separate multiple devices:
4917 <literallayout class='monospaced'>
4918 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
4919 </literallayout>
4920 </para>
4921 </glossdef>
4922 </glossentry>
4923
4924 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
4925 <glossdef>
4926 <para>
4927 Similar to
4928 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
4929 except the device is checked for existence before attempting
4930 to enable it.
4931 This variable is currently only supported with SysVinit
4932 (i.e. not with systemd).
4933 </para>
4934 </glossdef>
4935 </glossentry>
4936
4937 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
4938 <glossdef>
4939 <para>
4940 A list of recipe dependencies that should not be used to
4941 determine signatures of tasks from one recipe when they
4942 depend on tasks from another recipe.
4943 For example:
4944 <literallayout class='monospaced'>
4945 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
4946 </literallayout>
4947 In this example, <filename>intone</filename> depends on
4948 <filename>mplayer2</filename>.
4949 </para>
4950
4951 <para>
4952 Use of this variable is one mechanism to remove dependencies
4953 that affect task signatures and thus force rebuilds when a
4954 recipe changes.
4955 <note><title>Caution</title>
4956 If you add an inappropriate dependency for a recipe
4957 relationship, the software might break during
4958 runtime if the interface of the second recipe was
4959 changed after the first recipe had been built.
4960 </note>
4961 </para>
4962 </glossdef>
4963 </glossentry>
4964
4965 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
4966 <glossdef>
4967 <para>
4968 A list of recipes that are completely stable and will
4969 never change.
4970 The ABI for the recipes in the list are presented by
4971 output from the tasks run to build the recipe.
4972 Use of this variable is one way to remove dependencies from
4973 one recipe on another that affect task signatures and
4974 thus force rebuilds when the recipe changes.
4975 <note><title>Caution</title>
4976 If you add an inappropriate variable to this list,
4977 the software might break at runtime if the
4978 interface of the recipe was changed after the other
4979 had been built.
4980 </note>
4981 </para>
4982 </glossdef>
4983 </glossentry>
4984
4985 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
4986 <glossdef>
4987 <para>
4988 Specifies the number of bits for the target system CPU.
4989 The value should be either "32" or "64".
4990 </para>
4991 </glossdef>
4992 </glossentry>
4993
4994 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
4995 <glossdef>
4996 <para>
4997 Specifies the endian byte order of the target system.
4998 The value should be either "le" for little-endian or "be" for big-endian.
4999 </para>
5000 </glossdef>
5001 </glossentry>
5002
5003 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
5004 <glossdef>
5005 <para>
5006 Groups together machines based upon the same family
5007 of SOC (System On Chip).
5008 You typically set this variable in a common
5009 <filename>.inc</filename> file that you include in the
5010 configuration files of all the machines.
5011 <note>
5012 You must include
5013 <filename>conf/machine/include/soc-family.inc</filename>
5014 for this variable to appear in
5015 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
5016 </note>
5017 </para>
5018 </glossdef>
5019 </glossentry>
5020
5021 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
5022 <glossdef>
5023 <para>
5024 Defines the suffix for shared libraries used on the
5025 target platform.
5026 By default, this suffix is ".so.*" for all Linux-based
5027 systems and is defined in the
5028 <filename>meta/conf/bitbake.conf</filename> configuration
5029 file.
5030 </para>
5031
5032 <para>
5033 You will see this variable referenced in the default values
5034 of <filename>FILES_${PN}</filename>.
5035 </para>
5036 </glossdef>
5037 </glossentry>
5038
5039 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
5040 <glossdef>
5041 <para>
5042 Defines the suffix for the development symbolic link
5043 (symlink) for shared libraries on the target platform.
5044 By default, this suffix is ".so" for Linux-based
5045 systems and is defined in the
5046 <filename>meta/conf/bitbake.conf</filename> configuration
5047 file.
5048 </para>
5049
5050 <para>
5051 You will see this variable referenced in the default values
5052 of <filename>FILES_${PN}-dev</filename>.
5053 </para>
5054 </glossdef>
5055 </glossentry>
5056
5057 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
5058 <glossdef>
5059 <para>
5060 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
5061 OpenEmbedded build system to create variants of recipes or packages.
5062 The list specifies the prefixes to strip off during certain circumstances
5063 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
5064 </para>
5065 </glossdef>
5066 </glossentry>
5067
5068 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
5069 <glossdef>
5070 <para>The list of source files - local or remote.
5071 This variable tells the OpenEmbedded build system which bits
5072 to pull in for the build and how to pull them in.
5073 For example, if the recipe or append file only needs to
5074 fetch a tarball from the Internet, the recipe or
5075 append file uses a single <filename>SRC_URI</filename>
5076 entry.
5077 On the other hand, if the recipe or append file needs to
5078 fetch a tarball, apply two patches, and include a custom
5079 file, the recipe or append file would include four
5080 instances of the variable.</para>
5081 <para>The following list explains the available URI protocols:
5082 <itemizedlist>
5083 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
5084 Fetches files, which are usually files shipped with
5085 the
5086 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
5087 from the local machine.
5088 The path is relative to the
5089 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
5090 variable.
5091 Thus, the build system searches, in order, from the
5092 following directories, which are assumed to be a
5093 subdirectories of the directory in which the
5094 recipe file (<filename>.bb</filename>) or
5095 append file (<filename>.bbappend</filename>)
5096 resides:
5097 <itemizedlist>
5098 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
5099 The base recipe name without any special
5100 suffix or version numbers.
5101 </para></listitem>
5102 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
5103 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
5104 The base recipe name and version but without
5105 any special package name suffix.
5106 </para></listitem>
5107 <listitem><para><emphasis>files -</emphasis>
5108 Files within a directory, which is named
5109 <filename>files</filename> and is also
5110 alongside the recipe or append file.
5111 </para></listitem>
5112 </itemizedlist>
5113 <note>
5114 If you want the build system to pick up files
5115 specified through a
5116 <filename>SRC_URI</filename>
5117 statement from your append file, you need to be
5118 sure to extend the
5119 <filename>FILESPATH</filename>
5120 variable by also using the
5121 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
5122 variable from within your append file.
5123 </note>
5124 </para></listitem>
5125 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
5126 Bazaar revision control repository.</para></listitem>
5127 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
5128 Git revision control repository.</para></listitem>
5129 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
5130 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
5131 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
5132 a repo (Git) repository.</para></listitem>
5133 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
5134 an SVK revision control repository.</para></listitem>
5135 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
5136 the Internet using <filename>http</filename>.</para></listitem>
5137 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
5138 from the Internet using <filename>https</filename>.</para></listitem>
5139 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
5140 from the Internet using <filename>ftp</filename>.</para></listitem>
5141 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
5142 a CVS revision control repository.</para></listitem>
5143 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
5144 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
5145 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
5146 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
5147 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
5148 a secure shell.</para></listitem>
5149 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
5150 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
5151 </itemizedlist>
5152 </para>
5153 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
5154 Here are standard options:
5155 <itemizedlist>
5156 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
5157 the patch or not.
5158 The default action is to apply the patch.</para></listitem>
5159 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
5160 striplevel to use when applying the patch.
5161 The default level is 1.</para></listitem>
5162 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
5163 the directory in which the patch should be applied.
5164 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
5165 </para></listitem>
5166 </itemizedlist>
5167 </para>
5168 <para>Here are options specific to recipes building code from a revision control system:
5169 <itemizedlist>
5170 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
5171 Apply the patch only if
5172 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
5173 is equal to or greater than <filename>mindate</filename>.
5174 </para></listitem>
5175 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
5176 Apply the patch only if <filename>SRCDATE</filename>
5177 is not later than <filename>mindate</filename>.
5178 </para></listitem>
5179 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
5180 Apply the patch only if <filename>SRCREV</filename>
5181 is equal to or greater than <filename>minrev</filename>.
5182 </para></listitem>
5183 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
5184 Apply the patch only if <filename>SRCREV</filename>
5185 is not later than <filename>maxrev</filename>.
5186 </para></listitem>
5187 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
5188 Apply the patch only if <filename>SRCREV</filename>
5189 is equal to <filename>rev</filename>.
5190 </para></listitem>
5191 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
5192 Apply the patch only if <filename>SRCREV</filename>
5193 is not equal to <filename>rev</filename>.
5194 </para></listitem>
5195 </itemizedlist>
5196 </para>
5197 <para>Here are some additional options worth mentioning:
5198 <itemizedlist>
5199 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
5200 whether or not to unpack the file if it is an archive.
5201 The default action is to unpack the file.</para></listitem>
5202 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
5203 (or extracts its contents) into the specified
5204 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
5205 This option is useful for unusual tarballs or other archives that
5206 do not have their files already in a subdirectory within the archive.
5207 </para></listitem>
5208 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
5209 name to be used for association with <filename>SRC_URI</filename> checksums
5210 when you have more than one file specified in <filename>SRC_URI</filename>.
5211 </para></listitem>
5212 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
5213 the filename used when storing the downloaded file.</para></listitem>
5214 </itemizedlist>
5215 </para>
5216 </glossdef>
5217 </glossentry>
5218
5219 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
5220 <glossdef>
5221 <para></para>
5222 <para>
5223 By default, the OpenEmbedded build system automatically detects whether
5224 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
5225 contains files that are machine-specific.
5226 If so, the build system automatically changes
5227 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
5228 Setting this variable to "0" disables this behavior.
5229 </para>
5230 </glossdef>
5231 </glossentry>
5232
5233 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
5234 <glossdef>
5235 <para>
5236 The date of the source code used to build the package.
5237 This variable applies only if the source was fetched from a Source Code Manager (SCM).
5238 </para>
5239 </glossdef>
5240 </glossentry>
5241
5242 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
5243 <glossdef>
5244 <para>
5245 Returns the version string of the current package.
5246 This string is used to help define the value of
5247 <link linkend='var-PV'><filename>PV</filename></link>.
5248 </para>
5249
5250 <para>
5251 The <filename>SRCPV</filename> variable is defined in the
5252 <filename>meta/conf/bitbake.conf</filename> configuration
5253 file in the
5254 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
5255 as follows:
5256 <literallayout class='monospaced'>
5257 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
5258 </literallayout>
5259 </para>
5260
5261 <para>
5262 Recipes that need to define <filename>PV</filename> do so
5263 with the help of the <filename>SRCPV</filename>.
5264 For example, the <filename>ofono</filename> recipe
5265 (<filename>ofono_git.bb</filename>) located in
5266 <filename>meta/recipes-connectivity</filename> in the
5267 Source Directory defines <filename>PV</filename> as
5268 follows:
5269 <literallayout class='monospaced'>
5270 PV = "0.12-git${SRCPV}"
5271 </literallayout>
5272 </para>
5273 </glossdef>
5274 </glossentry>
5275
5276 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
5277 <glossdef>
5278 <para>
5279 The revision of the source code used to build the package.
5280 This variable applies to Subversion, Git, Mercurial and Bazaar
5281 only.
5282 Note that if you wish to build a fixed revision and you wish
5283 to avoid performing a query on the remote repository every time
5284 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
5285 full revision identifier and not just a tag.
5286 </para>
5287 </glossdef>
5288 </glossentry>
5289
5290 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
5291 <glossdef>
5292 <para>The directory for the shared state cache.</para>
5293 </glossdef>
5294 </glossentry>
5295
5296 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
5297 <glossdef>
5298 <para>
5299 Configures the OpenEmbedded build system to search other
5300 mirror locations for prebuilt cache data objects before
5301 building out the data.
5302 This variable works like fetcher
5303 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
5304 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
5305 and points to the cache locations to check for the shared
5306 objects.
5307 </para>
5308
5309 <para>
5310 You can specify a filesystem directory or a remote URL such
5311 as HTTP or FTP.
5312 The locations you specify need to contain the shared state
5313 cache (sstate-cache) results from previous builds.
5314 The sstate-cache you point to can also be from builds on
5315 other machines.
5316 </para>
5317
5318 <para>
5319 If a mirror uses the same structure as
5320 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
5321 you need to add
5322 "PATH" at the end as shown in the examples below.
5323 The build system substitutes the correct path within the
5324 directory structure.
5325 <literallayout class='monospaced'>
5326 SSTATE_MIRRORS ?= "\
5327 file://.* http://someserver.tld/share/sstate/PATH \n \
5328 file://.* file:///some/local/dir/sstate/PATH"
5329 </literallayout>
5330 </para>
5331 </glossdef>
5332 </glossentry>
5333
5334 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
5335 <glossdef>
5336 <para>
5337 The directory with kernel headers that are required to build out-of-tree
5338 modules.
5339 </para>
5340 </glossdef>
5341 </glossentry>
5342
5343 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
5344 <glossdef>
5345 <para>
5346 Specifies the base path used to create recipe stamp files.
5347 The path to an actual stamp file is constructed by evaluating this
5348 string and then appending additional information.
5349 Currently, the default assignment for <filename>STAMP</filename>
5350 as set in the <filename>meta/conf/bitbake.conf</filename> file
5351 is:
5352 <literallayout class='monospaced'>
5353 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
5354 </literallayout>
5355 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
5356 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
5357 <link linkend='var-PN'><filename>PN</filename></link>,
5358 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
5359 <link linkend='var-PV'><filename>PV</filename></link>, and
5360 <link linkend='var-PR'><filename>PR</filename></link> for related variable
5361 information.
5362 </para>
5363 </glossdef>
5364 </glossentry>
5365
5366 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
5367 <glossdef>
5368 <para>
5369 Specifies the base directory in which the OpenEmbedded
5370 build system places stamps.
5371 The default directory is
5372 <filename>${TMPDIR}/stamps</filename>.
5373 </para>
5374 </glossdef>
5375 </glossentry>
5376
5377 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
5378 <glossdef>
5379 <para>The short (72 characters or less) summary of the binary package for packaging
5380 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
5381 <filename>dpkg</filename>.
5382 By default, <filename>SUMMARY</filename> is used to define
5383 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
5384 variable if <filename>DESCRIPTION</filename> is not set
5385 in the recipe.
5386 </para>
5387 </glossdef>
5388 </glossentry>
5389
5390 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
5391 <glossdef>
5392 <para>
5393 A list of functions to execute after files are staged into
5394 the sysroot.
5395 These functions are usually used to apply additional
5396 processing on the staged files, or to stage additional
5397 files.
5398 </para>
5399 </glossdef>
5400 </glossentry>
5401
5402 </glossdiv>
5403
5404 <glossdiv id='var-glossary-t'><title>T</title>
5405
5406 <glossentry id='var-T'><glossterm>T</glossterm>
5407 <glossdef>
5408 <para>This variable points to a directory were BitBake places
5409 temporary files, which consist mostly of task logs and
5410 scripts, when building a particular recipe.
5411 The variable is typically set as follows:
5412 <literallayout class='monospaced'>
5413 T = "${WORKDIR}/temp"
5414 </literallayout>
5415 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
5416 is the directory into which BitBake unpacks and builds the
5417 recipe.
5418 The default <filename>bitbake.conf</filename> file sets this variable.</para>
5419 <para>The <filename>T</filename> variable is not to be confused with
5420 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
5421 which points to the root of the directory tree where BitBake
5422 places the output of an entire build.
5423 </para>
5424 </glossdef>
5425 </glossentry>
5426
5427 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
5428 <glossdef>
5429 <para>
5430 The target machine's architecture.
5431 The OpenEmbedded build system supports many
5432 architectures.
5433 Here is an example list of architectures supported.
5434 This list is by no means complete as the architecture
5435 is configurable:
5436 <literallayout class='monospaced'>
5437 arm
5438 i586
5439 x86_64
5440 powerpc
5441 powerpc64
5442 mips
5443 mipsel
5444 </literallayout>
5445 </para>
5446 </glossdef>
5447 </glossentry>
5448
5449 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
5450 <glossdef>
5451 <para>
5452 Flags passed to the C compiler for the target system.
5453 This variable evaluates to the same as
5454 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
5455 </para>
5456 </glossdef>
5457 </glossentry>
5458
5459
5460 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
5461 <glossdef>
5462 <para>Specifies the method for handling FPU code.
5463 For FPU-less targets, which include most ARM CPUs, the variable must be
5464 set to "soft".
5465 If not, the kernel emulation gets used, which results in a performance penalty.</para>
5466 </glossdef>
5467 </glossentry>
5468
5469 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
5470 <glossdef>
5471 <para>Specifies the target's operating system.
5472 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
5473 to "linux-uclibc" for <filename>uclibc</filename>.
5474 For ARM/EABI targets, there are also "linux-gnueabi" and
5475 "linux-uclibc-gnueabi" values possible.</para>
5476 </glossdef>
5477 </glossentry>
5478
5479 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
5480 <glossdef>
5481 <para>
5482 Specifies which variant of the GNU standard C library (<filename>libc</filename>)
5483 to use during the build process.
5484 This variable replaces <filename>POKYLIBC</filename>, which is no longer
5485 supported.
5486 </para>
5487 <para>
5488 You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
5489 <note>
5490 This release of the Yocto Project does not support the
5491 <filename>glibc</filename> implementation of <filename>libc</filename>.
5492 </note>
5493 </para>
5494 </glossdef>
5495 </glossentry>
5496
5497 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
5498 <glossdef>
5499 <para>
5500 The toolchain selector.
5501 This variable replaces <filename>POKYMODE</filename>, which is no longer
5502 supported.
5503 </para>
5504 <para>
5505 The <filename>TCMODE</filename> variable selects the external toolchain
5506 built using the OpenEmbedded build system or a few supported combinations of
5507 the upstream GCC or CodeSourcery Labs toolchain.
5508 The variable identifies the <filename>tcmode-*</filename> files used in
5509 the <filename>meta/conf/distro/include</filename> directory, which is found in the
5510 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5511 </para>
5512 <para>
5513 By default, <filename>TCMODE</filename> is set to "default", which
5514 chooses the <filename>tcmode-default.inc</filename> file.
5515 The variable is similar to
5516 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
5517 the variant of the GNU standard C library (<filename>libc</filename>)
5518 used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
5519 </para>
5520 </glossdef>
5521 </glossentry>
5522
5523 <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
5524 <glossdef>
5525 <para>
5526 Automatically runs the series of automated tests for
5527 images when an image is successfully built.
5528 <note>
5529 Currently, there is only support for running these tests
5530 under QEMU.
5531 </note>
5532 These tests are written in Python making use of the
5533 <filename>unittest</filename> module, and the majority of
5534 them run commands on the target system over
5535 <filename>ssh</filename>.
5536 You can set this variable to "1" in your
5537 <filename>local.conf</filename> file in the
5538 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
5539 to have the OpenEmbedded build system automatically run
5540 these tests after an image successfully builds:
5541 <literallayout class='monospaced'>
5542 TEST_IMAGE = "1"
5543 </literallayout>
5544 For more information on enabling, running, and writing
5545 these tests, see the
5546 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5547 section in the Yocto Project Development Manual and the
5548 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
5549 section.
5550 </para>
5551 </glossdef>
5552 </glossentry>
5553
5554 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
5555 <glossdef>
5556 <para>
5557 The time in seconds allowed for an image to boot before
5558 automated runtime tests begin to run against an
5559 image.
5560 The default timeout period to allow the boot process to
5561 reach the login prompt is 500 seconds.
5562 You can specify a different value in the
5563 <filename>local.conf</filename> file.
5564 </para>
5565
5566 <para>
5567 For more information on testing images, see the
5568 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5569 section in the Yocto Project Development Manual.
5570 </para>
5571 </glossdef>
5572 </glossentry>
5573
5574 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
5575 <glossdef>
5576 <para>
5577 An ordered list of tests (modules) to run against
5578 an image when performing automated runtime testing.
5579 </para>
5580
5581 <para>
5582 The OpenEmbedded build system provides a core set of tests
5583 that can be used against images.
5584 <note>
5585 Currently, there is only support for running these tests
5586 under QEMU.
5587 </note>
5588 Tests include <filename>ping</filename>,
5589 <filename>ssh</filename>, <filename>df</filename> among
5590 others.
5591 You can add your own tests to the list of tests by
5592 appending <filename>TEST_SUITES</filename> as follows:
5593 <literallayout class='monospaced'>
5594 TEST_SUITES_append = " mytest"
5595 </literallayout>
5596 Alternatively, you can provide the "auto" option to
5597 have all applicable tests run against the image.
5598 <literallayout class='monospaced'>
5599 TEST_SUITES_append = " auto"
5600 </literallayout>
5601 Using this option causes the build system to automatically
5602 run tests that are applicable to the image.
5603 Tests that are not applicable are skipped.
5604 </para>
5605
5606 <para>
5607 The order in which tests are run is important.
5608 Tests that depend on another test must appear later in the
5609 list than the test on which they depend.
5610 For example, if you append the list of tests with two
5611 tests (<filename>test_A</filename> and
5612 <filename>test_B</filename>) where
5613 <filename>test_B</filename> is dependent on
5614 <filename>test_A</filename>, then you must order the tests
5615 as follows:
5616 <literallayout class='monospaced'>
5617 TEST_SUITES = " test_A test_B"
5618 </literallayout>
5619 </para>
5620
5621 <para>
5622 For more information on testing images, see the
5623 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5624 section in the Yocto Project Development Manual.
5625 </para>
5626 </glossdef>
5627 </glossentry>
5628
5629 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
5630 <glossdef>
5631 <para>
5632 The directory in which the file BitBake is currently
5633 parsing is located.
5634 Do not manually set this variable.
5635 </para>
5636 </glossdef>
5637 </glossentry>
5638
5639 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
5640 <glossdef>
5641 <para>
5642 This variable is the base directory the OpenEmbedded
5643 build system uses for all build output and intermediate
5644 files (other than the shared state cache).
5645 By default, the <filename>TMPDIR</filename> variable points
5646 to <filename>tmp</filename> within the
5647 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
5648 </para>
5649
5650 <para>
5651 If you want to establish this directory in a location other
5652 than the default, you can uncomment and edit the following
5653 statement in the
5654 <filename>conf/local.conf</filename> file in the
5655 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
5656 <literallayout class='monospaced'>
5657 #TMPDIR = "${TOPDIR}/tmp"
5658 </literallayout>
5659 </para>
5660 </glossdef>
5661 </glossentry>
5662
5663 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
5664 <glossdef>
5665 <para>
5666 This variable lists packages the OpenEmbedded build system
5667 uses when building an SDK, which contains a
5668 cross-development environment.
5669 The packages specified by this variable are part of the
5670 toolchain set that runs on the
5671 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
5672 and each package should usually have the prefix
5673 "nativesdk-".
5674 When building an SDK using
5675 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
5676 a default list of packages is set in this variable, but
5677 you can add additional packages to the list.
5678 </para>
5679
5680 <para>
5681 For background information on cross-development toolchains
5682 in the Yocto Project development environment, see the
5683 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
5684 section.
5685 For information on setting up a cross-development
5686 environment, see the
5687 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
5688 section in the Yocto Project Application Developer's Guide.
5689 </para>
5690 </glossdef>
5691 </glossentry>
5692
5693 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
5694 <glossdef>
5695 <para>
5696 This variable lists packages the OpenEmbedded build system
5697 uses when it creates the target part of an SDK
5698 (i.e. the part built for the target hardware), which
5699 includes libraries and headers.
5700 </para>
5701
5702 <para>
5703 For background information on cross-development toolchains
5704 in the Yocto Project development environment, see the
5705 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
5706 section.
5707 For information on setting up a cross-development
5708 environment, see the
5709 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
5710 section in the Yocto Project Application Developer's Guide.
5711 </para>
5712 </glossdef>
5713 </glossentry>
5714
5715 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
5716 <glossdef>
5717 <para>
5718 This variable points to the
5719 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
5720 BitBake automatically sets this variable.
5721 </para>
5722 </glossdef>
5723 </glossentry>
5724
5725 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
5726 <glossdef>
5727 <para>
5728 A sanitized version of
5729 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
5730 This variable is used where the architecture is needed in
5731 a value where underscores are not allowed, for example
5732 within package filenames.
5733 In this case, dash characters replace any underscore
5734 characters used in TARGET_ARCH.
5735 </para>
5736
5737 <para>
5738 Do not edit this variable.
5739 </para>
5740 </glossdef>
5741 </glossentry>
5742
5743 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
5744 <glossdef>
5745 <para>
5746 The package architecture understood by the packaging
5747 system to define the architecture, ABI, and tuning of
5748 output packages.
5749 </para>
5750 </glossdef>
5751 </glossentry>
5752
5753 </glossdiv>
5754
5755 <glossdiv id='var-glossary-u'><title>U</title>
5756
5757 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
5758 <glossdef>
5759 <para>
5760 Specifies the entry point for the U-Boot image.
5761 During U-Boot image creation, the
5762 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
5763 as a command-line parameter to the
5764 <filename>uboot-mkimage</filename> utility.
5765 </para>
5766 </glossdef>
5767 </glossentry>
5768
5769 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
5770 <glossdef>
5771 <para>
5772 Specifies the load address for the U-Boot image.
5773 During U-Boot image creation, the
5774 <filename>UBOOT_LOADADDRESS</filename> variable is passed
5775 as a command-line parameter to the
5776 <filename>uboot-mkimage</filename> utility.
5777 </para>
5778 </glossdef>
5779 </glossentry>
5780
5781 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
5782 <glossdef>
5783 <para>
5784 Specifies the value passed on the
5785 <filename>make</filename> command line when building
5786 a U-Boot image.
5787 The value indicates the target platform configuration.
5788 You typically set this variable from the machine
5789 configuration file (i.e.
5790 <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
5791 </para>
5792 </glossdef>
5793 </glossentry>
5794
5795 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
5796 <glossdef>
5797 <para>
5798 Specifies the target used for building U-Boot.
5799 The target is passed directly as part of the "make" command
5800 (e.g. SPL and AIS).
5801 If you do not specifically set this variable, the
5802 OpenEmbedded build process passes and uses "all" for the
5803 target during the U-Boot building process.
5804 </para>
5805 </glossdef>
5806 </glossentry>
5807
5808 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
5809 <glossdef>
5810 <para>
5811 A list of classes to globally inherit.
5812 These classes are used by the OpenEmbedded build system
5813 to enable extra features (e.g.
5814 <filename>buildstats</filename>,
5815 <filename>image-mklibs</filename>, and so forth).
5816 </para>
5817
5818 <para>
5819 The default list is set in your
5820 <filename>local.conf</filename> file:
5821 <literallayout class='monospaced'>
5822 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
5823 </literallayout>
5824 For more information, see
5825 <filename>meta-yocto/conf/local.conf.sample</filename> in
5826 the
5827 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5828 </para>
5829 </glossdef>
5830 </glossentry>
5831
5832 </glossdiv>
5833
5834<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
5835<!-- </glossdiv>-->
5836
5837 <glossdiv id='var-glossary-w'><title>W</title>
5838
5839 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
5840 <glossdef>
5841 <para>
5842 Specifies the quality assurance checks whose failures are
5843 reported as warnings by the OpenEmbedded build system.
5844 You set this variable in your distribution configuration
5845 file.
5846 For a list of the checks you can control with this variable,
5847 see the
5848 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
5849 section.
5850 </para>
5851 </glossdef>
5852 </glossentry>
5853
5854 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
5855 <glossdef>
5856 <para>
5857 The pathname of the working directory in which the OpenEmbedded build system
5858 builds a recipe.
5859 This directory is located within the
5860 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
5861 as different packages are built.
5862 </para>
5863
5864 <para>
5865 The actual <filename>WORKDIR</filename> directory depends on several things:
5866 <itemizedlist>
5867 <listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem>
5868 <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
5869 <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
5870 <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
5871 <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
5872 <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
5873 <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
5874 </itemizedlist>
5875 </para>
5876
5877 <para>
5878 For packages that are not dependent on a particular machine,
5879 <filename>WORKDIR</filename> is defined as follows:
5880 <literallayout class='monospaced'>
5881 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
5882 </literallayout>
5883 As an example, assume a
5884 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
5885 folder name <filename>poky</filename> and a default
5886 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
5887 at <filename>poky/build</filename>.
5888 In this case, the working directory the build system uses to build
5889 the <filename>v86d</filename> package is the following:
5890 <literallayout class='monospaced'>
5891 poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
5892 </literallayout>
5893 </para>
5894
5895 <para>
5896 For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
5897 is defined slightly differently:
5898 <literallayout class='monospaced'>
5899 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
5900 </literallayout>
5901 As an example, again assume a Source Directory top-level folder
5902 named <filename>poky</filename> and a default Build Directory
5903 at <filename>poky/build</filename>.
5904 In this case, the working directory the build system uses to build
5905 the <filename>acl</filename> recipe, which is being built for a
5906 MIPS-based device, is the following:
5907 <literallayout class='monospaced'>
5908 poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
5909 </literallayout>
5910 </para>
5911 </glossdef>
5912 </glossentry>
5913
5914 </glossdiv>
5915
5916<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
5917<!-- </glossdiv>-->
5918
5919<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
5920<!-- </glossdiv>-->
5921
5922<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
5923<!-- </glossdiv>-->
5924
5925</glossary>
5926</chapter>
5927<!--
5928vim: expandtab tw=80 ts=4
5929-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 12:24:45 +0000