summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-variables.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-variables.xml')
-rw-r--r--documentation/ref-manual/ref-variables.xml9714
1 files changed, 9714 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..c34188d
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,9714 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ABIEXTENSION'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FEATURE_PACKAGES'>F</link>
25 <link linkend='var-GROUPADD_PARAM'>G</link>
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-ICECC_DISABLED'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LABELS'>L</link>
31 <link linkend='var-MACHINE'>M</link>
32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_BINCONFIG_EXTRA_MANGLE'>O</link>
34 <link linkend='var-P'>P</link>
35 <link linkend='var-QMAKE_PROFILES'>Q</link>
36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39 <link linkend='var-UBOOT_CONFIG'>U</link>
40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WARN_QA'>W</link>
42<!-- <link linkend='var-glossary-x'>X</link> -->
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm>
50 <glossdef>
51 <para>
52 Extension to the Application Binary Interface (ABI)
53 field of the GNU canonical architecture name
54 (e.g. "eabi").
55 </para>
56
57 <para>
58 ABI extensions are set in the machine include files.
59 For example, the
60 <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>
61 file sets the following extension:
62 <literallayout class='monospaced'>
63 ABIEXTENSION = "eabi"
64 </literallayout>
65 </para>
66 </glossdef>
67 </glossentry>
68
69 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
70 <glossdef>
71 <para>
72 Specifies if an output package should still be produced if it is empty.
73 By default, BitBake does not produce empty packages.
74 This default behavior can cause issues when there is an
75 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
76 some other hard runtime requirement on the existence of the package.
77 </para>
78
79 <para>
80 Like all package-controlling variables, you must always use them in
81 conjunction with a package name override, as in:
82 <literallayout class='monospaced'>
83 ALLOW_EMPTY_${PN} = "1"
84 ALLOW_EMPTY_${PN}-dev = "1"
85 ALLOW_EMPTY_${PN}-staticdev = "1"
86 </literallayout>
87 </para>
88 </glossdef>
89 </glossentry>
90
91 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
92 <glossdef>
93 <para>
94 Lists commands in a package that need an alternative
95 binary naming scheme.
96 Sometimes the same command is provided in multiple packages.
97 When this occurs, the OpenEmbedded build system needs to
98 use the alternatives system to create a different binary
99 naming scheme so the commands can co-exist.
100 </para>
101
102 <para>
103 To use the variable, list out the package's commands
104 that also exist as part of another package.
105 For example, if the <filename>busybox</filename> package
106 has four commands that also exist as part of another
107 package, you identify them as follows:
108 <literallayout class='monospaced'>
109 ALTERNATIVE_busybox = "sh sed test bracket"
110 </literallayout>
111 For more information on the alternatives system, see the
112 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
113 section.
114 </para>
115 </glossdef>
116 </glossentry>
117
118 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
119 <glossdef>
120 <para>
121 Used by the alternatives system to map duplicated commands
122 to actual locations.
123 For example, if the <filename>bracket</filename> command
124 provided by the <filename>busybox</filename> package is
125 duplicated through another package, you must use the
126 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
127 specify the actual location:
128 <literallayout class='monospaced'>
129 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
130 </literallayout>
131 In this example, the binary for the
132 <filename>bracket</filename> command (i.e.
133 <filename>[</filename>) from the
134 <filename>busybox</filename> package resides in
135 <filename>/usr/bin/</filename>.
136 <note>
137 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
138 defined, it defaults to
139 <filename>${bindir}/&lt;name&gt;</filename>.
140 </note>
141 </para>
142
143 <para>
144 For more information on the alternatives system, see the
145 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
146 section.
147 </para>
148 </glossdef>
149 </glossentry>
150
151 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
152 <glossdef>
153 <para>
154 Used by the alternatives system to create default
155 priorities for duplicated commands.
156 You can use the variable to create a single default
157 regardless of the command name or package, a default for
158 specific duplicated commands regardless of the package, or
159 a default for specific commands tied to particular packages.
160 Here are the available syntax forms:
161 <literallayout class='monospaced'>
162 ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
163 ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
164 ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
165 </literallayout>
166 </para>
167
168 <para>
169 For more information on the alternatives system, see the
170 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
171 section.
172 </para>
173 </glossdef>
174 </glossentry>
175
176 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
177 <glossdef>
178 <para>
179 Used by the alternatives system to create default link
180 locations for duplicated commands.
181 You can use the variable to create a single default
182 location for all duplicated commands regardless of the
183 command name or package, a default for
184 specific duplicated commands regardless of the package, or
185 a default for specific commands tied to particular packages.
186 Here are the available syntax forms:
187 <literallayout class='monospaced'>
188 ALTERNATIVE_TARGET = "&lt;target&gt;"
189 ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
190 ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
191 </literallayout>
192 <note>
193 <para>
194 If <filename>ALTERNATIVE_TARGET</filename> is not
195 defined, it inherits the value from the
196 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
197 variable.
198 </para>
199
200 <para>
201 If <filename>ALTERNATIVE_LINK_NAME</filename> and
202 <filename>ALTERNATIVE_TARGET</filename> are the
203 same, the target for
204 <filename>ALTERNATIVE_TARGET</filename>
205 has "<filename>.{BPN}</filename>" appended to it.
206 </para>
207
208 <para>
209 Finally, if the file referenced has not been
210 renamed, the alternatives system will rename it to
211 avoid the need to rename alternative files in the
212 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
213 task while
214 retaining support for the command if necessary.
215 </para>
216 </note>
217 </para>
218
219 <para>
220 For more information on the alternatives system, see the
221 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
222 section.
223 </para>
224 </glossdef>
225 </glossentry>
226
227 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
228 <glossdef>
229 <para>
230 An override list of append strings for each
231 <link linkend='var-LABELS'><filename>LABEL</filename></link>.
232 </para>
233
234 <para>
235 See the
236 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
237 class for more information on how this variable is used.
238 </para>
239 </glossdef>
240 </glossentry>
241
242 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
243 <glossdef>
244 <para>The email address used to contact the original author
245 or authors in order to send patches and forward bugs.</para>
246 </glossdef>
247 </glossentry>
248
249 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
250 <glossdef>
251 <para>
252 Enables creating an automatic menu.
253 You must set this in your recipe.
254 The
255 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
256 class checks this variable.
257 </para>
258 </glossdef>
259 </glossentry>
260
261 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
262 <glossdef>
263 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
264 is set to the value of this variable, it specifies to use the latest
265 source revision in the repository.
266 Here is an example:
267 <literallayout class='monospaced'>
268 SRCREV = "${AUTOREV}"
269 </literallayout>
270 </para>
271 </glossdef>
272 </glossentry>
273
274 <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>
275 <glossdef>
276 <para>
277 The list of defined CPU and Application Binary Interface
278 (ABI) tunings (i.e. "tunes") available for use by the
279 OpenEmbedded build system.
280 </para>
281
282 <para>
283 The list simply presents the tunes that are available.
284 Not all tunes may be compatible with a particular
285 machine configuration, or with each other in a
286 <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>
287 configuration.
288 </para>
289
290 <para>
291 To add a tune to the list, be sure to append it with
292 spaces using the "+=" BitBake operator.
293 Do not simply replace the list by using the "=" operator.
294 See the
295 "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
296 section in the BitBake User Manual for more information.
297 </para>
298 </glossdef>
299 </glossentry>
300
301
302 </glossdiv>
303
304 <glossdiv id='var-glossary-b'><title>B</title>
305
306 <glossentry id='var-B'><glossterm>B</glossterm>
307 <glossdef>
308 <para>
309 The directory within the
310 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
311 in which the OpenEmbedded build system places generated
312 objects during a recipe's build process.
313 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
314 directory, which is defined as:
315 <literallayout class='monospaced'>
316 S = "${WORKDIR}/${BP}/"
317 </literallayout>
318 You can separate the (<filename>S</filename>) directory
319 and the directory pointed to by the <filename>B</filename>
320 variable.
321 Most Autotools-based recipes support separating these
322 directories.
323 The build system defaults to using separate directories for
324 <filename>gcc</filename> and some kernel recipes.
325 </para>
326 </glossdef>
327 </glossentry>
328
329 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
330 <glossdef>
331 <para>
332 Lists "recommended-only" packages to not install.
333 Recommended-only packages are packages installed only
334 through the
335 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
336 variable.
337 You can prevent any of these "recommended" packages from
338 being installed by listing them with the
339 <filename>BAD_RECOMMENDATIONS</filename> variable:
340 <literallayout class='monospaced'>
341 BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
342 </literallayout>
343 You can set this variable globally in your
344 <filename>local.conf</filename> file or you can attach it to
345 a specific image recipe by using the recipe name override:
346 <literallayout class='monospaced'>
347 BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
348 </literallayout>
349 </para>
350
351 <para>
352 It is important to realize that if you choose to not install
353 packages using this variable and some other packages are
354 dependent on them (i.e. listed in a recipe's
355 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
356 variable), the OpenEmbedded build system ignores your
357 request and will install the packages to avoid dependency
358 errors.
359 </para>
360
361 <para>
362 Support for this variable exists only when using the
363 IPK and RPM packaging backend.
364 Support does not exist for DEB.
365 </para>
366
367 <para>
368 See the
369 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
370 and the
371 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
372 variables for related information.
373 </para>
374 </glossdef>
375 </glossentry>
376
377 <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm>
378 <glossdef>
379 <para>
380 The library directory name for the CPU or Application
381 Binary Interface (ABI) tune.
382 The <filename>BASE_LIB</filename> applies only in the
383 Multilib context.
384 See the
385 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
386 section in the Yocto Project Development Manual for
387 information on Multilib.
388 </para>
389
390 <para>
391 The <filename>BASE_LIB</filename> variable is defined in
392 the machine include files in the
393 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
394 If Multilib is not being used, the value defaults to "lib".
395 </para>
396 </glossdef>
397 </glossentry>
398
399 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
400 <glossdef>
401 <para>
402 Defines how BitBake handles situations where an append
403 file (<filename>.bbappend</filename>) has no
404 corresponding recipe file (<filename>.bb</filename>).
405 This condition often occurs when layers get out of sync
406 (e.g. <filename>oe-core</filename> bumps a
407 recipe version and the old recipe no longer exists and the
408 other layer has not been updated to the new version
409 of the recipe yet).
410 </para>
411
412 <para>
413 The default fatal behavior is safest because it is
414 the sane reaction given something is out of sync.
415 It is important to realize when your changes are no longer
416 being applied.
417 </para>
418
419 <para>
420 You can change the default behavior by setting this
421 variable to "1", "yes", or "true"
422 in your <filename>local.conf</filename> file, which is
423 located in the
424 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
425 Here is an example:
426 <literallayout class='monospaced'>
427 BB_DANGLINGAPPENDS_WARNONLY = "1"
428 </literallayout>
429 </para>
430 </glossdef>
431 </glossentry>
432
433 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
434 <glossdef>
435 <para>
436 Monitors disk space and available inodes during the build
437 and allows you to control the build based on these
438 parameters.
439 </para>
440
441 <para>
442 Disk space monitoring is disabled by default.
443 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
444 variable to your <filename>conf/local.conf</filename> file found in the
445 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
446 Use the following form:
447 <literallayout class='monospaced'>
448 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
449
450 where:
451
452 &lt;action&gt; is:
453 ABORT: Immediately abort the build when
454 a threshold is broken.
455 STOPTASKS: Stop the build after the currently
456 executing tasks have finished when
457 a threshold is broken.
458 WARN: Issue a warning but continue the
459 build when a threshold is broken.
460 Subsequent warnings are issued as
461 defined by the
462 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
463 which must be defined in the
464 conf/local.conf file.
465
466 &lt;dir&gt; is:
467 Any directory you choose. You can specify one or
468 more directories to monitor by separating the
469 groupings with a space. If two directories are
470 on the same device, only the first directory
471 is monitored.
472
473 &lt;threshold&gt; is:
474 Either the minimum available disk space,
475 the minimum number of free inodes, or
476 both. You must specify at least one. To
477 omit one or the other, simply omit the value.
478 Specify the threshold using G, M, K for Gbytes,
479 Mbytes, and Kbytes, respectively. If you do
480 not specify G, M, or K, Kbytes is assumed by
481 default. Do not use GB, MB, or KB.
482 </literallayout>
483 </para>
484
485 <para>
486 Here are some examples:
487 <literallayout class='monospaced'>
488 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
489 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
490 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
491 </literallayout>
492 The first example works only if you also provide
493 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
494 in the <filename>conf/local.conf</filename>.
495 This example causes the build system to immediately
496 abort when either the disk space in <filename>${TMPDIR}</filename> drops
497 below 1 Gbyte or the available free inodes drops below
498 100 Kbytes.
499 Because two directories are provided with the variable, the
500 build system also issue a
501 warning when the disk space in the
502 <filename>${SSTATE_DIR}</filename> directory drops
503 below 1 Gbyte or the number of free inodes drops
504 below 100 Kbytes.
505 Subsequent warnings are issued during intervals as
506 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
507 variable.
508 </para>
509
510 <para>
511 The second example stops the build after all currently
512 executing tasks complete when the minimum disk space
513 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
514 directory drops below 1 Gbyte.
515 No disk monitoring occurs for the free inodes in this case.
516 </para>
517
518 <para>
519 The final example immediately aborts the build when the
520 number of free inodes in the <filename>${TMPDIR}</filename> directory
521 drops below 100 Kbytes.
522 No disk space monitoring for the directory itself occurs
523 in this case.
524 </para>
525 </glossdef>
526 </glossentry>
527
528 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
529 <glossdef>
530 <para>
531 Defines the disk space and free inode warning intervals.
532 To set these intervals, define the variable in your
533 <filename>conf/local.conf</filename> file in the
534 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
535 </para>
536
537 <para>
538 If you are going to use the
539 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
540 also use the
541 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
542 and define its action as "WARN".
543 During the build, subsequent warnings are issued each time
544 disk space or number of free inodes further reduces by
545 the respective interval.
546 </para>
547
548 <para>
549 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
550 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
551 the "WARN" action, the disk monitoring interval defaults to
552 the following:
553 <literallayout class='monospaced'>
554 BB_DISKMON_WARNINTERVAL = "50M,5K"
555 </literallayout>
556 </para>
557
558 <para>
559 When specifying the variable in your configuration file,
560 use the following form:
561 <literallayout class='monospaced'>
562 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
563
564 where:
565
566 &lt;disk_space_interval&gt; is:
567 An interval of memory expressed in either
568 G, M, or K for Gbytes, Mbytes, or Kbytes,
569 respectively. You cannot use GB, MB, or KB.
570
571 &lt;disk_inode_interval&gt; is:
572 An interval of free inodes expressed in either
573 G, M, or K for Gbytes, Mbytes, or Kbytes,
574 respectively. You cannot use GB, MB, or KB.
575 </literallayout>
576 </para>
577
578 <para>
579 Here is an example:
580 <literallayout class='monospaced'>
581 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
582 BB_DISKMON_WARNINTERVAL = "50M,5K"
583 </literallayout>
584 These variables cause the OpenEmbedded build system to
585 issue subsequent warnings each time the available
586 disk space further reduces by 50 Mbytes or the number
587 of free inodes further reduces by 5 Kbytes in the
588 <filename>${SSTATE_DIR}</filename> directory.
589 Subsequent warnings based on the interval occur each time
590 a respective interval is reached beyond the initial warning
591 (i.e. 1 Gbytes and 100 Kbytes).
592 </para>
593 </glossdef>
594 </glossentry>
595
596 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
597 <glossdef>
598 <para>
599 Causes tarballs of the Git repositories, including the
600 Git metadata, to be placed in the
601 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
602 directory.
603 </para>
604
605 <para>
606 For performance reasons, creating and placing tarballs of
607 the Git repositories is not the default action by the
608 OpenEmbedded build system.
609 <literallayout class='monospaced'>
610 BB_GENERATE_MIRROR_TARBALLS = "1"
611 </literallayout>
612 Set this variable in your <filename>local.conf</filename>
613 file in the
614 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
615 </para>
616 </glossdef>
617 </glossentry>
618
619 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
620 <glossdef>
621 <para>
622 The maximum number of tasks BitBake should run in parallel
623 at any one time.
624 If your host development system supports multiple cores,
625 a good rule of thumb is to set this variable to twice the
626 number of cores.
627 </para>
628
629 <para>
630 The default value for <filename>BB_NUMBER_THREADS</filename>
631 is equal to the number of cores your build system has.
632 </para>
633 </glossdef>
634 </glossentry>
635
636 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
637 <glossdef>
638 <para>
639 Allows you to extend a recipe so that it builds variants of the software.
640 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
641 which is a copy of Quilt built to run on the build system;
642 "crosses" such as <filename>gcc-cross</filename>,
643 which is a compiler built to run on the build machine but produces binaries
644 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
645 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
646 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
647 </para>
648
649 <para>
650 To build a different variant of the recipe with a minimal amount of code, it usually
651 is as simple as adding the following to your recipe:
652 <literallayout class='monospaced'>
653 BBCLASSEXTEND =+ "native nativesdk"
654 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
655 </literallayout>
656 </para>
657 </glossdef>
658 </glossentry>
659
660 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
661 <glossdef>
662 <para>Lists the names of configured layers.
663 These names are used to find the other <filename>BBFILE_*</filename>
664 variables.
665 Typically, each layer will append its name to this variable in its
666 <filename>conf/layer.conf</filename> file.
667 </para>
668 </glossdef>
669 </glossentry>
670
671 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
672 <glossdef>
673 <para>Variable that expands to match files from
674 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
675 in a particular layer.
676 This variable is used in the <filename>conf/layer.conf</filename> file and must
677 be suffixed with the name of the specific layer (e.g.
678 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
679 </glossdef>
680 </glossentry>
681
682 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
683 <glossdef>
684 <para>Assigns the priority for recipe files in each layer.</para>
685 <para>This variable is useful in situations where the same recipe appears in
686 more than one layer.
687 Setting this variable allows you to prioritize a
688 layer against other layers that contain the same recipe - effectively
689 letting you control the precedence for the multiple layers.
690 The precedence established through this variable stands regardless of a
691 recipe's version
692 (<link linkend='var-PV'><filename>PV</filename></link> variable).
693 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
694 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
695 lower precedence.</para>
696 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
697 precedence.
698 For example, the value 6 has a higher precedence than the value 5.
699 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
700 dependencies (see the
701 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
702 more information.
703 The default priority, if unspecified
704 for a layer with no dependencies, is the lowest defined priority + 1
705 (or 1 if no priorities are defined).</para>
706 <tip>
707 You can use the command <filename>bitbake-layers show-layers</filename> to list
708 all configured layers along with their priorities.
709 </tip>
710 </glossdef>
711 </glossentry>
712
713 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
714 <glossdef>
715 <para>List of recipe files used by BitBake to build software.</para>
716 </glossdef>
717 </glossentry>
718
719 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
720 <glossdef>
721 <para>Variable that controls how BitBake displays logs on build failure.</para>
722 </glossdef>
723 </glossentry>
724
725 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
726 <glossdef>
727 <para>Lists the layers to enable during the build.
728 This variable is defined in the <filename>bblayers.conf</filename> configuration
729 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
730 Here is an example:
731 <literallayout class='monospaced'>
732 BBLAYERS = " \
733 /home/scottrif/poky/meta \
734 /home/scottrif/poky/meta-yocto \
735 /home/scottrif/poky/meta-yocto-bsp \
736 /home/scottrif/poky/meta-mykernel \
737 "
738
739 BBLAYERS_NON_REMOVABLE ?= " \
740 /home/scottrif/poky/meta \
741 /home/scottrif/poky/meta-yocto \
742 "
743 </literallayout>
744 This example enables four layers, one of which is a custom, user-defined layer
745 named <filename>meta-mykernel</filename>.
746 </para>
747 </glossdef>
748 </glossentry>
749
750 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
751 <glossdef>
752 <para>Lists core layers that cannot be removed from the
753 <filename>bblayers.conf</filename> file during a build
754 using the
755 <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>.
756 <note>
757 When building an image outside of Hob, this variable
758 is ignored.
759 </note>
760 In order for BitBake to build your image using Hob, your
761 <filename>bblayers.conf</filename> file must include the
762 <filename>meta</filename> and <filename>meta-yocto</filename>
763 core layers.
764 Here is an example that shows these two layers listed in
765 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
766 <literallayout class='monospaced'>
767 BBLAYERS = " \
768 /home/scottrif/poky/meta \
769 /home/scottrif/poky/meta-yocto \
770 /home/scottrif/poky/meta-yocto-bsp \
771 /home/scottrif/poky/meta-mykernel \
772 "
773
774 BBLAYERS_NON_REMOVABLE ?= " \
775 /home/scottrif/poky/meta \
776 /home/scottrif/poky/meta-yocto \
777 "
778 </literallayout>
779 </para>
780 </glossdef>
781 </glossentry>
782
783 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
784 <glossdef>
785 <para>
786 Prevents BitBake from processing recipes and recipe
787 append files.
788 Use the <filename>BBMASK</filename> variable from within the
789 <filename>conf/local.conf</filename> file found
790 in the
791 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
792 </para>
793
794 <para>
795 You can use the <filename>BBMASK</filename> variable
796 to "hide" these <filename>.bb</filename> and
797 <filename>.bbappend</filename> files.
798 BitBake ignores any recipe or recipe append files that
799 match the expression.
800 It is as if BitBake does not see them at all.
801 Consequently, matching files are not parsed or otherwise
802 used by BitBake.</para>
803 <para>
804 The value you provide is passed to Python's regular
805 expression compiler.
806 The expression is compared against the full paths to
807 the files.
808 For complete syntax information, see Python's
809 documentation at
810 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
811 </para>
812
813 <para>
814 The following example uses a complete regular expression
815 to tell BitBake to ignore all recipe and recipe append
816 files in the <filename>meta-ti/recipes-misc/</filename>
817 directory:
818 <literallayout class='monospaced'>
819 BBMASK = "meta-ti/recipes-misc/"
820 </literallayout>
821 If you want to mask out multiple directories or recipes,
822 use the vertical bar to separate the regular expression
823 fragments.
824 This next example masks out multiple directories and
825 individual recipes:
826 <literallayout class='monospaced'>
827 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
828 BBMASK .= "|.*meta-oe/recipes-support/"
829 BBMASK .= "|.*openldap"
830 BBMASK .= "|.*opencv"
831 BBMASK .= "|.*lzma"
832 </literallayout>
833 Notice how the vertical bar is used to append the fragments.
834 <note>
835 When specifying a directory name, use the trailing
836 slash character to ensure you match just that directory
837 name.
838 </note>
839 </para>
840 </glossdef>
841 </glossentry>
842
843 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
844 <glossdef>
845 <para>
846 Used by BitBake to locate
847 <filename>.bbclass</filename> and configuration files.
848 This variable is analogous to the
849 <filename>PATH</filename> variable.
850 <note>
851 If you run BitBake from a directory outside of the
852 <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
853 you must be sure to set
854 <filename>BBPATH</filename> to point to the
855 Build Directory.
856 Set the variable as you would any environment variable
857 and then run BitBake:
858 <literallayout class='monospaced'>
859 $ BBPATH = "&lt;build_directory&gt;"
860 $ export BBPATH
861 $ bitbake &lt;target&gt;
862 </literallayout>
863 </note>
864 </para>
865 </glossdef>
866 </glossentry>
867
868 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
869 <glossdef>
870 <para>
871 Points to the server that runs memory-resident BitBake.
872 This variable is set by the
873 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
874 setup script and should not be hand-edited.
875 The variable is only used when you employ memory-resident
876 BitBake.
877 The setup script exports the value as follows:
878 <literallayout class='monospaced'>
879 export BBSERVER=localhost:$port
880 </literallayout>
881 For more information on how the
882 <filename>BBSERVER</filename> is used, see the
883 <filename>oe-init-build-env-memres</filename> script, which
884 is located in the
885 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
886 </para>
887 </glossdef>
888 </glossentry>
889
890 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
891 <glossdef>
892 <para>
893 When inheriting <filename>binconfig.bbclass</filename>
894 from a recipe, this variable specifies a wildcard for
895 configuration scripts that need editing.
896 The scripts are edited to correct any paths that have been
897 set up during compilation so that they are correct for
898 use when installed into the sysroot and called by the
899 build processes of other recipes.
900 </para>
901
902 <para>
903 For more information on how this variable works, see
904 <filename>meta/classes/binconfig.bbclass</filename> in the
905 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
906 You can also find general information on the class in the
907 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
908 section.
909 </para>
910 </glossdef>
911 </glossentry>
912
913 <glossentry id='var-BP'><glossterm>BP</glossterm>
914 <glossdef>
915 <para>The base recipe name and version but without any special
916 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
917 and so forth).
918 <filename>BP</filename> is comprised of the following:
919 <literallayout class="monospaced">
920 ${BPN}-${PV}
921 </literallayout></para>
922 </glossdef>
923 </glossentry>
924
925 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
926 <glossdef>
927 <para>The bare name of the recipe.
928 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
929 but removes common suffixes such as "-native" and "-cross" as well
930 as removes common prefixes such as multilib's "lib64-" and "lib32-".
931 The exact list of suffixes removed is specified by the
932 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
933 The exact list of prefixes removed is specified by the
934 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
935 Prefixes are removed for <filename>multilib</filename>
936 and <filename>nativesdk</filename> cases.</para>
937 </glossdef>
938 </glossentry>
939
940 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
941 <glossdef>
942 <para>
943 Specifies a URL for an upstream bug tracking website for
944 a recipe.
945 The OpenEmbedded build system does not use this variable.
946 Rather, the variable is a useful pointer in case a bug
947 in the software being built needs to be manually reported.
948 </para>
949 </glossdef>
950 </glossentry>
951
952 <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>
953 <glossdef>
954 <para>
955 Specifies the flags to pass to the C compiler when building
956 for the build host.
957 When building in the <filename>-native</filename> context,
958 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
959 is set to the value of this variable by default.
960 </para>
961 </glossdef>
962 </glossentry>
963
964 <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
965 <glossdef>
966 <para>
967 Specifies the flags to pass to the C pre-processor
968 (i.e. to both the C and the C++ compilers) when building
969 for the build host.
970 When building in the <filename>native</filename> context,
971 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
972 is set to the value of this variable by default.
973 </para>
974 </glossdef>
975 </glossentry>
976
977 <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>
978 <glossdef>
979 <para>
980 Specifies the flags to pass to the C++ compiler when
981 building for the build host.
982 When building in the <filename>native</filename> context,
983 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
984 is set to the value of this variable by default.
985 </para>
986 </glossdef>
987 </glossentry>
988
989 <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>
990 <glossdef>
991 <para>
992 Specifies the flags to pass to the linker when building
993 for the build host.
994 When building in the <filename>-native</filename> context,
995 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
996 is set to the value of this variable by default.
997 </para>
998 </glossdef>
999 </glossentry>
1000
1001 <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>
1002 <glossdef>
1003 <para>
1004 Specifies the optimization flags passed to the C compiler
1005 when building for the build host or the SDK.
1006 The flags are passed through the
1007 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1008 and
1009 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1010 default values.
1011 </para>
1012
1013 <para>
1014 The default value of the
1015 <filename>BUILD_OPTIMIZATION</filename> variable is
1016 "-O2 -pipe".
1017 </para>
1018 </glossdef>
1019 </glossentry>
1020
1021 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
1022 <glossdef>
1023 <para>
1024 Points to the location of the
1025 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1026 You can define this directory indirectly through the
1027 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
1028 and
1029 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
1030 scripts by passing in a Build Directory path when you run
1031 the scripts.
1032 If you run the scripts and do not provide a Build Directory
1033 path, the <filename>BUILDDIR</filename> defaults to
1034 <filename>build</filename> in the current directory.
1035 </para>
1036 </glossdef>
1037 </glossentry>
1038
1039 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
1040 <glossdef>
1041 <para>
1042 When inheriting the
1043 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1044 class, specifies whether or not to commit the build
1045 history output in a local Git repository.
1046 If set to "1", this local repository will be maintained
1047 automatically by the
1048 <filename>buildhistory</filename>
1049 class and a commit will be created on every
1050 build for changes to each top-level subdirectory of the
1051 build history output (images, packages, and sdk).
1052 If you want to track changes to build history over
1053 time, you should set this value to "1".
1054 </para>
1055
1056 <para>
1057 By default, the <filename>buildhistory</filename> class
1058 does not commit the build history output in a local
1059 Git repository:
1060 <literallayout class='monospaced'>
1061 BUILDHISTORY_COMMIT ?= "0"
1062 </literallayout>
1063 </para>
1064 </glossdef>
1065 </glossentry>
1066
1067 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
1068 <glossdef>
1069 <para>
1070 When inheriting the
1071 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1072 class, specifies the author to use for each Git commit.
1073 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
1074 variable to work, the
1075 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1076 variable must be set to "1".
1077 </para>
1078
1079 <para>
1080 Git requires that the value you provide for the
1081 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
1082 takes the form of "name &lt;email@host&gt;".
1083 Providing an email address or host that is not valid does
1084 not produce an error.
1085 </para>
1086
1087 <para>
1088 By default, the <filename>buildhistory</filename> class
1089 sets the variable as follows:
1090 <literallayout class='monospaced'>
1091 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
1092 </literallayout>
1093 </para>
1094 </glossdef>
1095 </glossentry>
1096
1097 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
1098 <glossdef>
1099 <para>
1100 When inheriting the
1101 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1102 class, specifies the directory in which build history
1103 information is kept.
1104 For more information on how the variable works, see the
1105 <filename>buildhistory.class</filename>.
1106 </para>
1107
1108 <para>
1109 By default, the <filename>buildhistory</filename> class
1110 sets the directory as follows:
1111 <literallayout class='monospaced'>
1112 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1113 </literallayout>
1114 </para>
1115 </glossdef>
1116 </glossentry>
1117
1118 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
1119 <glossdef>
1120 <para>
1121 When inheriting the
1122 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1123 class, specifies the build history features to be enabled.
1124 For more information on how build history works, see the
1125 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
1126 section.
1127 </para>
1128
1129 <para>
1130 You can specify three features in the form of a
1131 space-separated list:
1132 <itemizedlist>
1133 <listitem><para><emphasis>image:</emphasis>
1134 Analysis of the contents of images, which
1135 includes the list of installed packages among other
1136 things.
1137 </para></listitem>
1138 <listitem><para><emphasis>package:</emphasis>
1139 Analysis of the contents of individual packages.
1140 </para></listitem>
1141 <listitem><para><emphasis>sdk:</emphasis>
1142 Analysis of the contents of the software
1143 development kit (SDK).
1144 </para></listitem>
1145 </itemizedlist>
1146 </para>
1147
1148 <para>
1149 By default, the <filename>buildhistory</filename> class
1150 enables all three features:
1151 <literallayout class='monospaced'>
1152 BUILDHISTORY_FEATURES ?= "image package sdk"
1153 </literallayout>
1154 </para>
1155 </glossdef>
1156 </glossentry>
1157
1158 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
1159 <glossdef>
1160 <para>
1161 When inheriting the
1162 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1163 class, specifies a list of paths to files copied from the
1164 image contents into the build history directory under
1165 an "image-files" directory in the directory for
1166 the image, so that you can track the contents of each file.
1167 The default is to copy <filename>/etc/passwd</filename>
1168 and <filename>/etc/group</filename>, which allows you to
1169 monitor for changes in user and group entries.
1170 You can modify the list to include any file.
1171 Specifying an invalid path does not produce an error.
1172 Consequently, you can include files that might
1173 not always be present.
1174 </para>
1175
1176 <para>
1177 By default, the <filename>buildhistory</filename> class
1178 provides paths to the following files:
1179 <literallayout class='monospaced'>
1180 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1181 </literallayout>
1182 </para>
1183 </glossdef>
1184 </glossentry>
1185
1186 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
1187 <glossdef>
1188 <para>
1189 When inheriting the
1190 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1191 class, optionally specifies a remote repository
1192 to which build history pushes Git changes.
1193 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
1194 to work,
1195 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1196 must be set to "1".
1197 </para>
1198
1199 <para>
1200 The repository should correspond to a remote
1201 address that specifies a repository as understood by
1202 Git, or alternatively to a remote name that you have
1203 set up manually using <filename>git remote</filename>
1204 within the local repository.
1205 </para>
1206
1207 <para>
1208 By default, the <filename>buildhistory</filename> class
1209 sets the variable as follows:
1210 <literallayout class='monospaced'>
1211 BUILDHISTORY_PUSH_REPO ?= ""
1212 </literallayout>
1213 </para>
1214 </glossdef>
1215 </glossentry>
1216
1217 <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>
1218 <glossdef>
1219 <para>
1220 Specifies the flags to pass to the C compiler when building
1221 for the SDK.
1222 When building in the <filename>nativesdk</filename>
1223 context,
1224 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1225 is set to the value of this variable by default.
1226 </para>
1227 </glossdef>
1228 </glossentry>
1229
1230 <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>
1231 <glossdef>
1232 <para>
1233 Specifies the flags to pass to the C pre-processor
1234 (i.e. to both the C and the C++ compilers) when building
1235 for the SDK.
1236 When building in the <filename>nativesdk</filename>
1237 context,
1238 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
1239 is set to the value of this variable by default.
1240 </para>
1241 </glossdef>
1242 </glossentry>
1243
1244 <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>
1245 <glossdef>
1246 <para>
1247 Specifies the flags to pass to the C++ compiler when
1248 building for the SDK.
1249 When building in the <filename>nativesdk</filename>
1250 context,
1251 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
1252 is set to the value of this variable by default.
1253 </para>
1254 </glossdef>
1255 </glossentry>
1256
1257 <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>
1258 <glossdef>
1259 <para>
1260 Specifies the flags to pass to the linker when building
1261 for the SDK.
1262 When building in the <filename>nativesdk-</filename>
1263 context,
1264 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1265 is set to the value of this variable by default.
1266 </para>
1267 </glossdef>
1268 </glossentry>
1269
1270 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
1271 <glossdef>
1272 <para>
1273 Points to the location of the directory that holds build
1274 statistics when you use and enable the
1275 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
1276 class.
1277 The <filename>BUILDSTATS_BASE</filename> directory defaults
1278 to
1279 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
1280 </para>
1281 </glossdef>
1282 </glossentry>
1283
1284 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
1285 <glossdef>
1286 <para>
1287 For the BusyBox recipe, specifies whether to split the
1288 output executable file into two parts: one for features
1289 that require <filename>setuid root</filename>, and one for
1290 the remaining features (i.e. those that do not require
1291 <filename>setuid root</filename>).
1292 </para>
1293
1294 <para>
1295 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
1296 defaults to "1", which results in a single output
1297 executable file.
1298 Set the variable to "0" to split the output file.
1299 </para>
1300 </glossdef>
1301 </glossentry>
1302
1303 </glossdiv>
1304
1305 <glossdiv id='var-glossary-c'><title>C</title>
1306
1307 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
1308 <glossdef>
1309 <para>
1310 Specifies the flags to pass to the C compiler.
1311 This variable is exported to an environment
1312 variable and thus made visible to the software being
1313 built during the compilation step.
1314 </para>
1315
1316 <para>
1317 Default initialization for <filename>CFLAGS</filename>
1318 varies depending on what is being built:
1319 <itemizedlist>
1320 <listitem><para>
1321 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
1322 when building for the target
1323 </para></listitem>
1324 <listitem><para>
1325 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1326 when building for the build host (i.e.
1327 <filename>-native</filename>)
1328 </para></listitem>
1329 <listitem><para>
1330 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1331 when building for an SDK (i.e.
1332 <filename>nativesdk-</filename>)
1333 </para></listitem>
1334 </itemizedlist>
1335 </para>
1336 </glossdef>
1337 </glossentry>
1338
1339 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
1340 <glossdef>
1341 <para>
1342 An internal variable specifying the special class override
1343 that should currently apply (e.g. "class-target",
1344 "class-native", and so forth).
1345 The classes that use this variable set it to
1346 appropriate values.
1347 </para>
1348
1349 <para>
1350 You do not normally directly interact with this variable.
1351 The value for the <filename>CLASSOVERRIDE</filename>
1352 variable goes into
1353 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1354 and then can be used as an override.
1355 Here is an example where "python-native" is added to
1356 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1357 only when building for the native case:
1358 <literallayout class='monospaced'>
1359 DEPENDS_append_class-native = " python-native"
1360 </literallayout>
1361 </para>
1362 </glossdef>
1363 </glossentry>
1364
1365 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
1366 <glossdef>
1367 <para>
1368 Provides a list of hardware features that are enabled in
1369 both
1370 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1371 and
1372 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1373 This select list of features contains features that make
1374 sense to be controlled both at the machine and distribution
1375 configuration level.
1376 For example, the "bluetooth" feature requires hardware
1377 support but should also be optional at the distribution
1378 level, in case the hardware supports Bluetooth but you
1379 do not ever intend to use it.
1380 </para>
1381
1382 <para>
1383 For more information, see the
1384 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1385 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
1386 variables.
1387 </para>
1388 </glossdef>
1389 </glossentry>
1390
1391 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
1392 <glossdef>
1393 <para>
1394 Points to <filename>meta/files/common-licenses</filename>
1395 in the
1396 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1397 which is where generic license files reside.
1398 </para>
1399 </glossdef>
1400 </glossentry>
1401
1402 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
1403 <glossdef>
1404 <para>A regular expression that resolves to one or more hosts
1405 (when the recipe is native) or one or more targets (when
1406 the recipe is non-native) with which a recipe is compatible.
1407 The regular expression is matched against
1408 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
1409 You can use the variable to stop recipes from being built
1410 for classes of systems with which the recipes are not
1411 compatible.
1412 Stopping these builds is particularly useful with kernels.
1413 The variable also helps to increase parsing speed
1414 since the build system skips parsing recipes not
1415 compatible with the current system.</para>
1416 </glossdef>
1417 </glossentry>
1418
1419 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
1420 <glossdef>
1421 <para>A regular expression that resolves to one or more
1422 target machines with which a recipe is compatible.
1423 The regular expression is matched against
1424 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
1425 You can use the variable to stop recipes from being built
1426 for machines with which the recipes are not compatible.
1427 Stopping these builds is particularly useful with kernels.
1428 The variable also helps to increase parsing speed
1429 since the build system skips parsing recipes not
1430 compatible with the current machine.</para>
1431 </glossdef>
1432 </glossentry>
1433
1434 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
1435 <glossdef>
1436 <para>
1437 Defines wildcards to match when installing a list of
1438 complementary packages for all the packages explicitly
1439 (or implicitly) installed in an image.
1440 The resulting list of complementary packages is associated
1441 with an item that can be added to
1442 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
1443 An example usage of this is the "dev-pkgs" item that when
1444 added to <filename>IMAGE_FEATURES</filename> will
1445 install -dev packages (containing headers and other
1446 development files) for every package in the image.
1447 </para>
1448
1449 <para>
1450 To add a new feature item pointing to a wildcard, use a
1451 variable flag to specify the feature item name and
1452 use the value to specify the wildcard.
1453 Here is an example:
1454 <literallayout class='monospaced'>
1455 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1456 </literallayout>
1457 </para>
1458 </glossdef>
1459 </glossentry>
1460
1461 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
1462 <glossdef>
1463 <para>
1464 Identifies editable or configurable files that are part of a package.
1465 If the Package Management System (PMS) is being used to update
1466 packages on the target system, it is possible that
1467 configuration files you have changed after the original installation
1468 and that you now want to remain unchanged are overwritten.
1469 In other words, editable files might exist in the package that you do not
1470 want reset as part of the package update process.
1471 You can use the <filename>CONFFILES</filename> variable to list the files in the
1472 package that you wish to prevent the PMS from overwriting during this update process.
1473 </para>
1474
1475 <para>
1476 To use the <filename>CONFFILES</filename> variable, provide a package name
1477 override that identifies the resulting package.
1478 Then, provide a space-separated list of files.
1479 Here is an example:
1480 <literallayout class='monospaced'>
1481 CONFFILES_${PN} += "${sysconfdir}/file1 \
1482 ${sysconfdir}/file2 ${sysconfdir}/file3"
1483 </literallayout>
1484 </para>
1485
1486 <para>
1487 A relationship exists between the <filename>CONFFILES</filename> and
1488 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
1489 The files listed within <filename>CONFFILES</filename> must be a subset of
1490 the files listed within <filename>FILES</filename>.
1491 Because the configuration files you provide with <filename>CONFFILES</filename>
1492 are simply being identified so that the PMS will not overwrite them,
1493 it makes sense that
1494 the files must already be included as part of the package through the
1495 <filename>FILES</filename> variable.
1496 </para>
1497
1498 <note>
1499 When specifying paths as part of the <filename>CONFFILES</filename> variable,
1500 it is good practice to use appropriate path variables.
1501 For example, <filename>${sysconfdir}</filename> rather than
1502 <filename>/etc</filename> or <filename>${bindir}</filename> rather
1503 than <filename>/usr/bin</filename>.
1504 You can find a list of these variables at the top of the
1505 <filename>meta/conf/bitbake.conf</filename> file in the
1506 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1507 </note>
1508 </glossdef>
1509 </glossentry>
1510
1511 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
1512 <glossdef>
1513 <para>
1514 Identifies the initial RAM disk (initramfs) source files.
1515 The OpenEmbedded build system receives and uses
1516 this kernel Kconfig variable as an environment variable.
1517 By default, the variable is set to null ("").
1518 </para>
1519
1520 <para>
1521 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
1522 either a single cpio archive with a
1523 <filename>.cpio</filename> suffix or a
1524 space-separated list of directories and files for building
1525 the initramfs image.
1526 A cpio archive should contain a filesystem archive
1527 to be used as an initramfs image.
1528 Directories should contain a filesystem layout to be
1529 included in the initramfs image.
1530 Files should contain entries according to the format
1531 described by the
1532 <filename>usr/gen_init_cpio</filename> program in the
1533 kernel tree.
1534 </para>
1535
1536 <para>
1537 If you specify multiple directories and files, the
1538 initramfs image will be the aggregate of all of them.
1539 </para>
1540 </glossdef>
1541 </glossentry>
1542
1543 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
1544 <glossdef>
1545 <para>
1546 A list of files that contains <filename>autoconf</filename> test results relevant
1547 to the current build.
1548 This variable is used by the Autotools utilities when running
1549 <filename>configure</filename>.
1550 </para>
1551 </glossdef>
1552 </glossentry>
1553
1554 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
1555 <glossdef>
1556 <para>
1557 When a recipe inherits the
1558 <filename>distro_features_check</filename> class, this
1559 variable identifies distribution features that would
1560 be in conflict should the recipe
1561 be built.
1562 In other words, if the
1563 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
1564 lists a feature that also appears in
1565 <filename>DISTRO_FEATURES</filename> within the
1566 current configuration, an error occurs and the
1567 build stops.
1568 </para>
1569 </glossdef>
1570 </glossentry>
1571
1572 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
1573 <glossdef>
1574 <para>
1575 If set to "1" along with the
1576 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1577 variable, the OpenEmbedded build system copies
1578 into the image the license files, which are located in
1579 <filename>/usr/share/common-licenses</filename>,
1580 for each package.
1581 The license files are placed
1582 in directories within the image itself.
1583 </para>
1584 </glossdef>
1585 </glossentry>
1586
1587 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
1588 <glossdef>
1589 <para>
1590 If set to "1", the OpenEmbedded build system copies
1591 the license manifest for the image to
1592 <filename>/usr/share/common-licenses/license.manifest</filename>
1593 within the image itself.
1594 </para>
1595 </glossdef>
1596 </glossentry>
1597
1598 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
1599 <glossdef>
1600 <para>
1601 Specifies the list of packages to be added to the image.
1602 You should only set this variable in the
1603 <filename>local.conf</filename> configuration file found
1604 in the
1605 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1606 </para>
1607
1608 <para>
1609 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
1610 </para>
1611 </glossdef>
1612 </glossentry>
1613
1614 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
1615 <glossdef>
1616 <para>
1617 Specifies the parent directory of the OpenEmbedded
1618 Core Metadata layer (i.e. <filename>meta</filename>).
1619 </para>
1620
1621 <para>
1622 It is an important distinction that
1623 <filename>COREBASE</filename> points to the parent of this
1624 layer and not the layer itself.
1625 Consider an example where you have cloned the Poky Git
1626 repository and retained the <filename>poky</filename>
1627 name for your local copy of the repository.
1628 In this case, <filename>COREBASE</filename> points to
1629 the <filename>poky</filename> folder because it is the
1630 parent directory of the <filename>poky/meta</filename>
1631 layer.
1632 </para>
1633 </glossdef>
1634 </glossentry>
1635
1636 <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>
1637 <glossdef>
1638 <para>
1639 Specifies the flags to pass to the C pre-processor
1640 (i.e. to both the C and the C++ compilers).
1641 This variable is exported to an environment
1642 variable and thus made visible to the software being
1643 built during the compilation step.
1644 </para>
1645
1646 <para>
1647 Default initialization for <filename>CPPFLAGS</filename>
1648 varies depending on what is being built:
1649 <itemizedlist>
1650 <listitem><para>
1651 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>
1652 when building for the target
1653 </para></listitem>
1654 <listitem><para>
1655 <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link>
1656 when building for the build host (i.e.
1657 <filename>-native</filename>)
1658 </para></listitem>
1659 <listitem><para>
1660 <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link>
1661 when building for an SDK (i.e.
1662 <filename>nativesdk-</filename>)
1663 </para></listitem>
1664 </itemizedlist>
1665 </para>
1666 </glossdef>
1667 </glossentry>
1668
1669 <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>
1670 <glossdef>
1671 <para>
1672 Specifies the flags to pass to the C++ compiler.
1673 This variable is exported to an environment
1674 variable and thus made visible to the software being
1675 built during the compilation step.
1676 </para>
1677
1678 <para>
1679 Default initialization for <filename>CXXFLAGS</filename>
1680 varies depending on what is being built:
1681 <itemizedlist>
1682 <listitem><para>
1683 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>
1684 when building for the target
1685 </para></listitem>
1686 <listitem><para>
1687 <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link>
1688 when building for the build host (i.e.
1689 <filename>-native</filename>)
1690 </para></listitem>
1691 <listitem><para>
1692 <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
1693 when building for an SDK (i.e.
1694 <filename>nativesdk</filename>)
1695 </para></listitem>
1696 </itemizedlist>
1697 </para>
1698 </glossdef>
1699 </glossentry>
1700
1701 </glossdiv>
1702
1703 <glossdiv id='var-glossary-d'><title>D</title>
1704
1705 <glossentry id='var-D'><glossterm>D</glossterm>
1706 <glossdef>
1707 <para>
1708 The destination directory.
1709 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1710 where components are installed by the
1711 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1712 task.
1713 This location defaults to:
1714 <literallayout class='monospaced'>
1715 ${WORKDIR}/image
1716 </literallayout>
1717 </para>
1718 </glossdef>
1719 </glossentry>
1720
1721 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
1722 <glossdef>
1723 <para>
1724 The date and time on which the current build started.
1725 The format is suitable for timestamps.
1726 </para>
1727 </glossdef>
1728 </glossentry>
1729
1730 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
1731 <glossdef>
1732 <para>
1733 Specifies to build packages with debugging information.
1734 This influences the value of the
1735 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
1736 variable.
1737 </para>
1738 </glossdef>
1739 </glossentry>
1740
1741 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
1742 <glossdef>
1743 <para>
1744 The options to pass in
1745 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1746 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
1747 a system for debugging.
1748 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1749 </para>
1750 </glossdef>
1751 </glossentry>
1752
1753 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1754 <glossdef>
1755 <para>
1756 Specifies a weak bias for recipe selection priority.
1757 </para>
1758 <para>
1759 The most common usage of this is variable is to set
1760 it to "-1" within a recipe for a development version of a
1761 piece of software.
1762 Using the variable in this way causes the stable version
1763 of the recipe to build by default in the absence of
1764 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1765 being used to build the development version.
1766 </para>
1767 <note>
1768 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1769 is weak and is overridden by
1770 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1771 if that variable is different between two layers
1772 that contain different versions of the same recipe.
1773 </note>
1774 </glossdef>
1775 </glossentry>
1776
1777 <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>
1778 <glossdef>
1779 <para>
1780 The default CPU and Application Binary Interface (ABI)
1781 tunings (i.e. the "tune") used by the OpenEmbedded build
1782 system.
1783 The <filename>DEFAULTTUNE</filename> helps define
1784 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
1785 </para>
1786
1787 <para>
1788 The default tune is either implicitly or explicitly set
1789 by the machine
1790 (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).
1791 However, you can override the setting using available tunes
1792 as defined with
1793 <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>.
1794 </para>
1795 </glossdef>
1796 </glossentry>
1797
1798 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1799 <glossdef>
1800 <para>
1801 Lists a recipe's build-time dependencies
1802 (i.e. other recipe files).
1803 The system ensures that all the dependencies listed
1804 have been built and have their contents in the appropriate
1805 sysroots before the recipe's configure task is executed.
1806 </para>
1807
1808 <para>
1809 Consider this simple example for two recipes named "a" and
1810 "b" that produce similarly named packages.
1811 In this example, the <filename>DEPENDS</filename>
1812 statement appears in the "a" recipe:
1813 <literallayout class='monospaced'>
1814 DEPENDS = "b"
1815 </literallayout>
1816 Here, the dependency is such that the
1817 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
1818 task for recipe "a" depends on the
1819 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
1820 task of recipe "b".
1821 This means anything that recipe "b" puts into sysroot
1822 is available when recipe "a" is configuring itself.
1823 </para>
1824
1825 <para>
1826 For information on runtime dependencies, see the
1827 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1828 variable.
1829 </para>
1830 </glossdef>
1831 </glossentry>
1832
1833 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
1834 <glossdef>
1835 <para>
1836 Points to the general area that the OpenEmbedded build
1837 system uses to place images, packages, SDKs and other output
1838 files that are ready to be used outside of the build system.
1839 By default, this directory resides within the
1840 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1841 as <filename>${TMPDIR}/deploy</filename>.
1842 </para>
1843
1844 <para>
1845 For more information on the structure of the Build
1846 Directory, see
1847 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1848 section.
1849 For more detail on the contents of the
1850 <filename>deploy</filename> directory, see the
1851 "<link linkend='images-dev-environment'>Images</link>" and
1852 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1853 sections.
1854 </para>
1855 </glossdef>
1856 </glossentry>
1857
1858 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
1859 <glossdef>
1860 <para>
1861 Points to the area that the OpenEmbedded build system uses
1862 to place images and other associated output files that are
1863 ready to be deployed onto the target machine.
1864 The directory is machine-specific as it contains the
1865 <filename>${MACHINE}</filename> name.
1866 By default, this directory resides within the
1867 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1868 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
1869 </para>
1870
1871 <para>
1872 For more information on the structure of the Build
1873 Directory, see
1874 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1875 section.
1876 For more detail on the contents of the
1877 <filename>deploy</filename> directory, see the
1878 "<link linkend='images-dev-environment'>Images</link>" and
1879 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1880 sections.
1881 </para>
1882 </glossdef>
1883 </glossentry>
1884
1885 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
1886 <glossdef>
1887 <para>
1888 For recipes that inherit the
1889 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
1890 class, the <filename>DEPLOYDIR</filename> points to a
1891 temporary work area for deployed files that is set in the
1892 <filename>deploy</filename> class as follows:
1893 <literallayout class='monospaced'>
1894 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
1895 </literallayout>
1896 Recipes inheriting the <filename>deploy</filename> class
1897 should copy files to be deployed into
1898 <filename>DEPLOYDIR</filename>, and the class will take
1899 care of copying them into
1900 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
1901 afterwards.
1902 </para>
1903 </glossdef>
1904 </glossentry>
1905
1906 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1907 <glossdef>
1908 <para>The package description used by package managers.
1909 If not set, <filename>DESCRIPTION</filename> takes
1910 the value of the
1911 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
1912 variable.
1913 </para>
1914 </glossdef>
1915 </glossentry>
1916
1917 <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm>
1918 <glossdef>
1919 <para>
1920 A 32-bit MBR disk signature used by
1921 <filename>directdisk</filename> images.
1922 </para>
1923
1924 <para>
1925 By default, the signature is set to an automatically
1926 generated random value that allows the OpenEmbedded
1927 build system to create a boot loader.
1928 You can override the signature in the image recipe
1929 by setting <filename>DISK_SIGNATURE</filename> to an
1930 8-digit hex string.
1931 You might want to override
1932 <filename>DISK_SIGNATURE</filename> if you want the disk
1933 signature to remain constant between image builds.
1934 </para>
1935
1936 <para>
1937 When using Linux 3.8 or later, you can use
1938 <filename>DISK_SIGNATURE</filename> to specify the root
1939 by UUID to allow the kernel to locate the root device
1940 even if the device name changes due to differences in
1941 hardware configuration.
1942 By default, <filename>SYSLINUX_ROOT</filename> is set
1943 as follows:
1944 <literallayout class='monospaced'>
1945 SYSLINUX_ROOT = "root=/dev/sda2"
1946 </literallayout>
1947 However, you can change this to locate the root device
1948 using the disk signature instead:
1949 <literallayout class='monospaced'>
1950 SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02"
1951 </literallayout>
1952 </para>
1953
1954 <para>
1955 As previously mentioned, it is possible to set the
1956 <filename>DISK_SIGNATURE</filename> variable in your
1957 <filename>local.conf</filename> file to a fixed
1958 value if you do not want <filename>syslinux.cfg</filename>
1959 changing for each build.
1960 You might find this useful when you want to upgrade the
1961 root filesystem on a device without having to recreate or
1962 modify the master boot record.
1963 </para>
1964 </glossdef>
1965 </glossentry>
1966
1967 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
1968 <glossdef>
1969 <para>
1970 The short name of the distribution.
1971 This variable corresponds to a distribution
1972 configuration file whose root name is the same as the
1973 variable's argument and whose filename extension is
1974 <filename>.conf</filename>.
1975 For example, the distribution configuration file for the
1976 Poky distribution is named <filename>poky.conf</filename>
1977 and resides in the
1978 <filename>meta-yocto/conf/distro</filename> directory of
1979 the
1980 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1981 </para>
1982
1983 <para>
1984 Within that <filename>poky.conf</filename> file, the
1985 <filename>DISTRO</filename> variable is set as follows:
1986 <literallayout class='monospaced'>
1987 DISTRO = "poky"
1988 </literallayout>
1989 </para>
1990
1991 <para>
1992 Distribution configuration files are located in a
1993 <filename>conf/distro</filename> directory within the
1994 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
1995 that contains the distribution configuration.
1996 The value for <filename>DISTRO</filename> must not contain
1997 spaces, and is typically all lower-case.
1998 <note>
1999 If the <filename>DISTRO</filename> variable is blank, a set
2000 of default configurations are used, which are specified
2001 within
2002 <filename>meta/conf/distro/defaultsetup.conf</filename>
2003 also in the Source Directory.
2004 </note>
2005 </para>
2006 </glossdef>
2007 </glossentry>
2008
2009 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
2010 <glossdef>
2011 <para>
2012 Specifies a list of distro-specific packages to add to all images.
2013 This variable takes affect through
2014 <filename>packagegroup-base</filename> so the
2015 variable only really applies to the more full-featured
2016 images that include <filename>packagegroup-base</filename>.
2017 You can use this variable to keep distro policy out of
2018 generic images.
2019 As with all other distro variables, you set this variable
2020 in the distro <filename>.conf</filename> file.
2021 </para>
2022 </glossdef>
2023 </glossentry>
2024
2025 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
2026 <glossdef>
2027 <para>
2028 Specifies a list of distro-specific packages to add to all images
2029 if the packages exist.
2030 The packages might not exist or be empty (e.g. kernel modules).
2031 The list of packages are automatically installed but you can
2032 remove them.
2033 </para>
2034 </glossdef>
2035 </glossentry>
2036
2037 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
2038 <glossdef>
2039 <para>
2040 The software support you want in your distribution for
2041 various features.
2042 You define your distribution features in the distribution
2043 configuration file.
2044 </para>
2045
2046 <para>
2047 In most cases, the presence or absence of a feature in
2048 <filename>DISTRO_FEATURES</filename> is translated to the
2049 appropriate option supplied to the configure script
2050 during the
2051 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2052 task for recipes that optionally support the feature.
2053 For example, specifying "x11" in
2054 <filename>DISTRO_FEATURES</filename>, causes
2055 every piece of software built for the target that can
2056 optionally support X11 to have its X11 support enabled.
2057 </para>
2058
2059 <para>
2060 Two more examples are Bluetooth and NFS support.
2061 For a more complete list of features that ships with the
2062 Yocto Project and that you can provide with this variable,
2063 see the
2064 "<link linkend='ref-features-distro'>Distro Features</link>"
2065 section.
2066 </para>
2067 </glossdef>
2068 </glossentry>
2069
2070 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
2071 <glossdef>
2072 <para>Features to be added to
2073 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
2074 if not also present in
2075 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
2076 </para>
2077
2078 <para>
2079 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
2080 It is not intended to be user-configurable.
2081 It is best to just reference the variable to see which distro features are
2082 being backfilled for all distro configurations.
2083 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
2084 more information.
2085 </para>
2086 </glossdef>
2087 </glossentry>
2088
2089 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
2090 <glossdef>
2091 <para>Features from
2092 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
2093 that should not be backfilled (i.e. added to
2094 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
2095 during the build.
2096 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
2097 more information.
2098 </para>
2099 </glossdef>
2100 </glossentry>
2101
2102 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
2103 <glossdef>
2104 <para>The long name of the distribution.</para>
2105 </glossdef>
2106 </glossentry>
2107
2108 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
2109 <glossdef>
2110 <para>Alias names used for the recipe in various Linux distributions.</para>
2111 <para>See the
2112 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
2113 a Package Name Alias</ulink>" section in the Yocto Project Development
2114 Manual for more information.</para>
2115 </glossdef>
2116 </glossentry>
2117
2118 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
2119 <glossdef>
2120 <para>The version of the distribution.</para>
2121 </glossdef>
2122 </glossentry>
2123
2124 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
2125 <glossdef>
2126 <para>
2127 This variable lists overrides specific to the current
2128 distribution.
2129 By default, the variable list includes the value of the
2130 <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
2131 variable.
2132 You can extend the variable to apply any variable overrides
2133 you want as part of the distribution and are not
2134 already in <filename>OVERRIDES</filename> through
2135 some other means.
2136 </para>
2137 </glossdef>
2138 </glossentry>
2139
2140 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
2141 <glossdef>
2142 <para>
2143 The central download directory used by the build process to
2144 store downloads.
2145 By default, <filename>DL_DIR</filename> gets files
2146 suitable for mirroring for everything except Git
2147 repositories.
2148 If you want tarballs of Git repositories, use the
2149 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
2150 variable.
2151 </para>
2152
2153 <para>
2154 You can set this directory by defining the
2155 <filename>DL_DIR</filename> variable in the
2156 <filename>conf/local.conf</filename> file.
2157 This directory is self-maintaining and you should not have
2158 to touch it.
2159 By default, the directory is <filename>downloads</filename>
2160 in the
2161 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2162 <literallayout class='monospaced'>
2163 #DL_DIR ?= "${TOPDIR}/downloads"
2164 </literallayout>
2165 To specify a different download directory, simply remove
2166 the comment from the line and provide your directory.
2167 </para>
2168
2169 <para>
2170 During a first build, the system downloads many different
2171 source code tarballs from various upstream projects.
2172 Downloading can take a while, particularly if your network
2173 connection is slow.
2174 Tarballs are all stored in the directory defined by
2175 <filename>DL_DIR</filename> and the build system looks there
2176 first to find source tarballs.
2177 <note>
2178 When wiping and rebuilding, you can preserve this
2179 directory to speed up this part of subsequent
2180 builds.
2181 </note>
2182 </para>
2183
2184 <para>
2185 You can safely share this directory between multiple builds
2186 on the same development machine.
2187 For additional information on how the build process gets
2188 source files when working behind a firewall or proxy server,
2189 see this specific question in the
2190 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
2191 chapter.
2192 </para>
2193 </glossdef>
2194
2195 </glossentry>
2196 </glossdiv>
2197
2198 <glossdiv id='var-glossary-e'><title>E</title>
2199
2200 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
2201 <glossdef>
2202 <para></para>
2203 <para>Variable that controls which locales for
2204 <filename>eglibc</filename> are generated during the
2205 build (useful if the target device has 64Mbytes
2206 of RAM or less).</para>
2207 </glossdef>
2208 </glossentry>
2209
2210 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
2211 <glossdef>
2212 <para>
2213 Specifies the quality assurance checks whose failures are
2214 reported as errors by the OpenEmbedded build system.
2215 You set this variable in your distribution configuration
2216 file.
2217 For a list of the checks you can control with this variable,
2218 see the
2219 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
2220 section.
2221 </para>
2222 </glossdef>
2223 </glossentry>
2224
2225 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
2226 <glossdef>
2227 <para>
2228 When used with the
2229 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
2230 class, specifies the path used for storing the debug files
2231 created by the
2232 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
2233 which allows you to submit build errors you encounter to a
2234 central database.
2235 By default, the value of this variable is
2236 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
2237 </para>
2238
2239 <para>
2240 You can set <filename>ERR_REPORT_DIR</filename> to the path
2241 you want the error reporting tool to store the debug files
2242 as follows in your <filename>local.conf</filename> file:
2243 <literallayout class='monospaced'>
2244 ERR_REPORT_DIR = "path"
2245 </literallayout>
2246 </para>
2247 </glossdef>
2248 </glossentry>
2249
2250 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
2251 <glossdef>
2252 <para>
2253 Directs BitBake to exclude a recipe from world builds (i.e.
2254 <filename>bitbake world</filename>).
2255 During world builds, BitBake locates, parses and builds all
2256 recipes found in every layer exposed in the
2257 <filename>bblayers.conf</filename> configuration file.
2258 </para>
2259
2260 <para>
2261 To exclude a recipe from a world build using this variable,
2262 set the variable to "1" in the recipe.
2263 </para>
2264
2265 <note>
2266 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
2267 may still be built during a world build in order to satisfy
2268 dependencies of other recipes.
2269 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
2270 only ensures that the recipe is not explicitly added
2271 to the list of build targets in a world build.
2272 </note>
2273 </glossdef>
2274 </glossentry>
2275
2276 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
2277 <glossdef>
2278 <para>
2279 Used with file and pathnames to create a prefix for a recipe's
2280 version based on the recipe's
2281 <link linkend='var-PE'><filename>PE</filename></link> value.
2282 If <filename>PE</filename> is set and greater than zero for a recipe,
2283 <filename>EXTENDPE</filename> becomes that value (e.g if
2284 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
2285 becomes "1_").
2286 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
2287 zero, <filename>EXTENDPE</filename> becomes "".</para>
2288 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
2289 variable for an example.
2290 </para>
2291 </glossdef>
2292 </glossentry>
2293
2294 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
2295 <glossdef>
2296 <para>
2297 The full package version specification as it appears on the
2298 final packages produced by a recipe.
2299 The variable's value is normally used to fix a runtime
2300 dependency to the exact same version of another package
2301 in the same recipe:
2302 <literallayout class='monospaced'>
2303 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
2304 </literallayout>
2305 </para>
2306
2307 <para>
2308 The dependency relationships are intended to force the
2309 package manager to upgrade these types of packages in
2310 lock-step.
2311 </para>
2312 </glossdef>
2313 </glossentry>
2314
2315 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
2316 <glossdef>
2317 <para>
2318 If <filename>externalsrc.bbclass</filename> is inherited,
2319 this variable points to the source tree, which is
2320 outside of the OpenEmbedded build system.
2321 When set, this variable sets the
2322 <link linkend='var-S'><filename>S</filename></link>
2323 variable, which is what the OpenEmbedded build system uses
2324 to locate unpacked recipe source code.
2325 </para>
2326
2327 <para>
2328 For more information on
2329 <filename>externalsrc.bbclass</filename>, see the
2330 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2331 section.
2332 You can also find information on how to use this variable
2333 in the
2334 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2335 section in the Yocto Project Development Manual.
2336 </para>
2337 </glossdef>
2338 </glossentry>
2339
2340 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
2341 <glossdef>
2342 <para>
2343 If <filename>externalsrc.bbclass</filename> is inherited,
2344 this variable points to the directory in which the recipe's
2345 source code is built,
2346 which is outside of the OpenEmbedded build system.
2347 When set, this variable sets the
2348 <link linkend='var-B'><filename>B</filename></link>
2349 variable, which is what the OpenEmbedded build system uses
2350 to locate the Build Directory.
2351 </para>
2352
2353 <para>
2354 For more information on
2355 <filename>externalsrc.bbclass</filename>, see the
2356 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2357 section.
2358 You can also find information on how to use this variable
2359 in the
2360 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2361 section in the Yocto Project Development Manual.
2362 </para>
2363 </glossdef>
2364 </glossentry>
2365
2366 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
2367 <glossdef>
2368 <para>
2369 The list of additional features to include in an image.
2370 Typically, you configure this variable in your
2371 <filename>local.conf</filename> file, which is found in the
2372 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2373 Although you can use this variable from within a recipe,
2374 best practices dictate that you do not.
2375 <note>
2376 To enable primary features from within the image
2377 recipe, use the
2378 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2379 variable.
2380 </note>
2381 </para>
2382
2383 <para>
2384 Here are some examples of features you can add:
2385 <literallayout class='monospaced'>
2386"dbg-pkgs" - Adds -dbg packages for all installed packages
2387 including symbol information for debugging and
2388 profiling.
2389
2390"debug-tweaks" - Makes an image suitable for development.
2391 For example, ssh root access has a blank
2392 password. You should remove this feature
2393 before you produce a production image.
2394
2395"dev-pkgs" - Adds -dev packages for all installed packages.
2396 This is useful if you want to develop against
2397 the libraries in the image.
2398
2399"read-only-rootfs" - Creates an image whose root
2400 filesystem is read-only. See the
2401 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
2402 section in the Yocto Project
2403 Development Manual for more
2404 information
2405
2406"tools-debug" - Adds debugging tools such as gdb and
2407 strace.
2408
2409"tools-profile" - Adds profiling tools such as oprofile,
2410 exmap, lttng and valgrind (x86 only).
2411
2412"tools-sdk" - Adds development tools such as gcc, make,
2413 pkgconfig and so forth.
2414
2415"tools-testapps" - Adds useful testing tools such as
2416 ts_print, aplay, arecord and so
2417 forth.
2418
2419 </literallayout>
2420 </para>
2421
2422 <para>
2423 For a complete list of image features that ships with the
2424 Yocto Project, see the
2425 "<link linkend="ref-features-image">Image Features</link>"
2426 section.
2427 </para>
2428
2429 <para>
2430 For an example that shows how to customize your image by
2431 using this variable, see the
2432 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
2433 section in the Yocto Project Development Manual.
2434 </para>
2435 </glossdef>
2436 </glossentry>
2437
2438 <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
2439 <glossdef>
2440 <para>
2441 Specifies additional options for the image
2442 creation command that has been specified in
2443 <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
2444 When setting this variable, you should
2445 use an override for the associated type.
2446 Here is an example:
2447 <literallayout class='monospaced'>
2448 EXTRA_IMAGECMD_ext3 ?= "-i 4096"
2449 </literallayout>
2450 </para>
2451 </glossdef>
2452 </glossentry>
2453
2454 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
2455 <glossdef>
2456 <para>A list of recipes to build that do not provide packages
2457 for installing into the root filesystem.
2458 </para>
2459 <para>Sometimes a recipe is required to build the final image but is not
2460 needed in the root filesystem.
2461 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
2462 list these recipes and thus specify the dependencies.
2463 A typical example is a required bootloader in a machine configuration.
2464 </para>
2465 <note>
2466 To add packages to the root filesystem, see the various
2467 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
2468 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
2469 variables.
2470 </note>
2471 </glossdef>
2472 </glossentry>
2473
2474 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
2475 <glossdef>
2476 <para>Additional <filename>cmake</filename> options.</para>
2477 </glossdef>
2478 </glossentry>
2479
2480 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
2481 <glossdef>
2482 <para>Additional <filename>configure</filename> script options.</para>
2483 </glossdef>
2484 </glossentry>
2485
2486 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
2487 <glossdef>
2488 <para>Additional GNU <filename>make</filename> options.</para>
2489 </glossdef>
2490 </glossentry>
2491
2492 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
2493 <glossdef>
2494 <para>
2495 When a recipe inherits the
2496 <link linkend='ref-classes-scons'><filename>scons</filename></link>
2497 class, this variable specifies additional configuration
2498 options you want to pass to the
2499 <filename>scons</filename> command line.
2500 </para>
2501 </glossdef>
2502 </glossentry>
2503
2504 <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>EXTRA_QMAKEVARS_POST</glossterm>
2505 <glossdef>
2506 <para>
2507 Configuration variables or options you want to pass to
2508 <filename>qmake</filename>.
2509 Use this variable when the arguments need to be after the
2510 <filename>.pro</filename> file list on the command line.
2511 </para>
2512
2513 <para>
2514 This variable is used with recipes that inherit the
2515 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2516 class or other classes that inherit
2517 <filename>qmake_base</filename>.
2518 </para>
2519 </glossdef>
2520 </glossentry>
2521
2522 <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>EXTRA_QMAKEVARS_PRE</glossterm>
2523 <glossdef>
2524 <para>
2525 Configuration variables or options you want to pass to
2526 <filename>qmake</filename>.
2527 Use this variable when the arguments need to be before the
2528 <filename>.pro</filename> file list on the command line.
2529 </para>
2530
2531 <para>
2532 This variable is used with recipes that inherit the
2533 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2534 class or other classes that inherit
2535 <filename>qmake_base</filename>.
2536 </para>
2537 </glossdef>
2538 </glossentry>
2539
2540 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
2541 <glossdef>
2542 <para>
2543 When a recipe inherits the
2544 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
2545 class, this variable provides image level user and group
2546 operations.
2547 This is a more global method of providing user and group
2548 configuration as compared to using the
2549 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
2550 class, which ties user and group configurations to a
2551 specific recipe.
2552 </para>
2553
2554 <para>
2555 The set list of commands you can configure using the
2556 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
2557 <filename>extrausers</filename> class.
2558 These commands map to the normal Unix commands of the same
2559 names:
2560 <literallayout class='monospaced'>
2561 # EXTRA_USERS_PARAMS = "\
2562 # useradd -p '' tester; \
2563 # groupadd developers; \
2564 # userdel nobody; \
2565 # groupdel -g video; \
2566 # groupmod -g 1020 developers; \
2567 # usermod -s /bin/sh tester; \
2568 # "
2569 </literallayout>
2570 </para>
2571 </glossdef>
2572 </glossentry>
2573
2574 </glossdiv>
2575
2576 <glossdiv id='var-glossary-f'><title>F</title>
2577
2578 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
2579 <glossdef>
2580 <para>
2581 Defines one or more packages to include in an image when
2582 a specific item is included in
2583 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2584 When setting the value, <filename>FEATURE_PACKAGES</filename>
2585 should have the name of the feature item as an override.
2586 Here is an example:
2587 <literallayout class='monospaced'>
2588 FEATURE_PACKAGES_widget = "package1 package2"
2589 </literallayout>
2590 In this example, if "widget" were added to
2591 <filename>IMAGE_FEATURES</filename>, "package1" and
2592 "package2" would be included in the image.
2593 <note>
2594 Packages installed by features defined through
2595 <filename>FEATURE_PACKAGES</filename> are often package
2596 groups.
2597 While similarly named, you should not confuse the
2598 <filename>FEATURE_PACKAGES</filename> variable with
2599 package groups, which are discussed elsewhere in the
2600 documentation.
2601 </note>
2602 </para>
2603 </glossdef>
2604 </glossentry>
2605
2606 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
2607 <glossdef>
2608 <para>
2609 Points to the base URL of the server and location within
2610 the document-root that provides the metadata and
2611 packages required by OPKG to support runtime package
2612 management of IPK packages.
2613 You set this variable in your
2614 <filename>local.conf</filename> file.
2615 </para>
2616
2617 <para>
2618 Consider the following example:
2619 <literallayout class='monospaced'>
2620 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2621 </literallayout>
2622 This example assumes you are serving your packages over
2623 HTTP and your databases are located in a directory
2624 named <filename>BOARD-dir</filename>, which is underneath
2625 your HTTP server's document-root.
2626 In this case, the OpenEmbedded build system generates a set
2627 of configuration files for you in your target that work
2628 with the feed.
2629 </para>
2630 </glossdef>
2631 </glossentry>
2632
2633 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
2634 <glossdef>
2635 <para>
2636 The list of directories or files that are placed in packages.
2637 </para>
2638
2639 <para>
2640 To use the <filename>FILES</filename> variable, provide a package name
2641 override that identifies the resulting package.
2642 Then, provide a space-separated list of files or paths that identifies the
2643 files you want included as part of the resulting package.
2644 Here is an example:
2645 <literallayout class='monospaced'>
2646 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
2647 </literallayout>
2648 </para>
2649
2650 <note>
2651 When specifying paths as part of the <filename>FILES</filename> variable,
2652 it is good practice to use appropriate path variables.
2653 For example, use <filename>${sysconfdir}</filename> rather than
2654 <filename>/etc</filename>, or <filename>${bindir}</filename> rather
2655 than <filename>/usr/bin</filename>.
2656 You can find a list of these variables at the top of the
2657 <filename>meta/conf/bitbake.conf</filename> file in the
2658 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2659 </note>
2660
2661 <para>
2662 If some of the files you provide with the <filename>FILES</filename> variable
2663 are editable and you know they should not be
2664 overwritten during the package update process by the Package Management
2665 System (PMS), you can identify these files so that the PMS will not
2666 overwrite them.
2667 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
2668 variable for information on how to identify these files to the PMS.
2669 </para>
2670
2671 </glossdef>
2672 </glossentry>
2673
2674 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
2675 <glossdef>
2676 <para>
2677 Extends the search path the OpenEmbedded build system uses
2678 when looking for files and patches as it processes recipes
2679 and append files.
2680 The default directories BitBake uses when it processes
2681 recipes are initially defined by the
2682 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2683 variable.
2684 You can extend <filename>FILESPATH</filename> variable
2685 by using <filename>FILESEXTRAPATHS</filename>.
2686 </para>
2687
2688 <para>
2689 Best practices dictate that you accomplish this by using
2690 <filename>FILESEXTRAPATHS</filename> from within a
2691 <filename>.bbappend</filename> file and that you prepend
2692 paths as follows:
2693 <literallayout class='monospaced'>
2694 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2695 </literallayout>
2696 In the above example, the build system first looks for files
2697 in a directory that has the same name as the corresponding
2698 append file.
2699 <note>
2700 <para>When extending <filename>FILESEXTRAPATHS</filename>,
2701 be sure to use the immediate expansion
2702 (<filename>:=</filename>) operator.
2703 Immediate expansion makes sure that BitBake evaluates
2704 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
2705 at the time the directive is encountered rather than at
2706 some later time when expansion might result in a
2707 directory that does not contain the files you need.
2708 </para>
2709 <para>Also, include the trailing separating colon
2710 character if you are prepending.
2711 The trailing colon character is necessary because you
2712 are directing BitBake to extend the path by prepending
2713 directories to the search path.</para>
2714 </note>
2715 Here is another common use:
2716 <literallayout class='monospaced'>
2717 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
2718 </literallayout>
2719 In this example, the build system extends the
2720 <filename>FILESPATH</filename> variable to include a
2721 directory named <filename>files</filename> that is in the
2722 same directory as the corresponding append file.
2723 </para>
2724
2725 <para>
2726 Here is a final example that specifically adds three paths:
2727 <literallayout class='monospaced'>
2728 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
2729 </literallayout>
2730 </para>
2731
2732 <para>
2733 By prepending paths in <filename>.bbappend</filename>
2734 files, you allow multiple append files that reside in
2735 different layers but are used for the same recipe to
2736 correctly extend the path.
2737 </para>
2738 </glossdef>
2739 </glossentry>
2740
2741 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
2742 <glossdef>
2743 <para>
2744 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2745 used by the OpenEmbedded build system for creating
2746 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
2747 You can find more information on how overrides are handled
2748 in the BitBake Manual that is located at
2749 <filename>bitbake/doc/manual</filename> in the
2750 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2751 </para>
2752
2753 <para>
2754 By default, the <filename>FILESOVERRIDES</filename>
2755 variable is defined as:
2756 <literallayout class='monospaced'>
2757 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2758 </literallayout>
2759
2760 <note>
2761 Do not hand-edit the <filename>FILESOVERRIDES</filename>
2762 variable.
2763 The values match up with expected overrides and are
2764 used in an expected manner by the build system.
2765 </note>
2766 </para>
2767 </glossdef>
2768 </glossentry>
2769
2770 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
2771 <glossdef>
2772 <para>
2773 The default set of directories the OpenEmbedded build system
2774 uses when searching for patches and files.
2775 During the build process, BitBake searches each directory in
2776 <filename>FILESPATH</filename> in the specified order when
2777 looking for files and patches specified by each
2778 <filename>file://</filename> URI in a recipe.
2779 </para>
2780
2781 <para>
2782 The default value for the <filename>FILESPATH</filename>
2783 variable is defined in the <filename>base.bbclass</filename>
2784 class found in <filename>meta/classes</filename> in the
2785 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2786 <literallayout class='monospaced'>
2787 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2788 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2789 </literallayout>
2790 <note>
2791 Do not hand-edit the <filename>FILESPATH</filename>
2792 variable.
2793 If you want the build system to look in directories
2794 other than the defaults, extend the
2795 <filename>FILESPATH</filename> variable by using the
2796 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2797 variable.
2798 </note>
2799 Be aware that the default <filename>FILESPATH</filename>
2800 directories do not map to directories in custom layers
2801 where append files (<filename>.bbappend</filename>)
2802 are used.
2803 If you want the build system to find patches or files
2804 that reside with your append files, you need to extend
2805 the <filename>FILESPATH</filename> variable by using
2806 the
2807 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2808 variable.
2809 </para>
2810 </glossdef>
2811 </glossentry>
2812
2813 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
2814 <glossdef>
2815 <para>Allows you to define your own file permissions settings table as part of
2816 your configuration for the packaging process.
2817 For example, suppose you need a consistent set of custom permissions for
2818 a set of groups and users across an entire work project.
2819 It is best to do this in the packages themselves but this is not always
2820 possible.
2821 </para>
2822 <para>
2823 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
2824 is located in the <filename>meta/files</filename> folder in the
2825 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2826 If you create your own file permissions setting table, you should place it in your
2827 layer or the distro's layer.
2828 </para>
2829 <para>
2830 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
2831 <filename>conf/local.conf</filename> file, which is found in the
2832 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
2833 point to your custom <filename>fs-perms.txt</filename>.
2834 You can specify more than a single file permissions setting table.
2835 The paths you specify to these files must be defined within the
2836 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
2837 </para>
2838 <para>
2839 For guidance on how to create your own file permissions settings table file,
2840 examine the existing <filename>fs-perms.txt</filename>.
2841 </para>
2842 </glossdef>
2843 </glossentry>
2844
2845 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
2846 <glossdef>
2847 <para>
2848 When a recipe inherits the
2849 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
2850 class, this variable identifies packages containing font
2851 files that need to be cached by Fontconfig.
2852 By default, the <filename>fontcache</filename> class assumes
2853 that fonts are in the recipe's main package
2854 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2855 Use this variable if fonts you need are in a package
2856 other than that main package.
2857 </para>
2858 </glossdef>
2859 </glossentry>
2860
2861 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
2862 <glossdef>
2863 <para>
2864 The options to pass in
2865 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
2866 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
2867 when compiling an optimized system.
2868 This variable defaults to
2869 "-O2 -pipe ${DEBUG_FLAGS}".
2870 </para>
2871 </glossdef>
2872 </glossentry>
2873 </glossdiv>
2874
2875 <glossdiv id='var-glossary-g'><title>G</title>
2876
2877 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
2878 <glossdef>
2879 <para>
2880 When a recipe inherits the
2881 <filename>useradd</filename> class, this variable
2882 specifies for a package what parameters should be passed
2883 to the <filename>groupadd</filename> command
2884 if you wish to add a group to the system when the package
2885 is installed.
2886 </para>
2887
2888 <para>
2889 Here is an example from the <filename>dbus</filename>
2890 recipe:
2891 <literallayout class='monospaced'>
2892 GROUPADD_PARAM_${PN} = "-r netdev"
2893 </literallayout>
2894 For information on the standard Linux shell command
2895 <filename>groupadd</filename>, see
2896 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
2897 </para>
2898 </glossdef>
2899 </glossentry>
2900
2901 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
2902 <glossdef>
2903 <para>
2904 When a recipe inherits the
2905 <filename>useradd</filename> class, this variable
2906 specifies for a package what parameters should be passed
2907 to the <filename>groupmems</filename> command
2908 if you wish to modify the members of a group when the
2909 package is installed.
2910 </para>
2911
2912 <para>
2913 For information on the standard Linux shell command
2914 <filename>groupmems</filename>, see
2915 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
2916 </para>
2917 </glossdef>
2918 </glossentry>
2919
2920 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
2921 <glossdef>
2922 <para>
2923 Configures the GNU GRand Unified Bootloader (GRUB) to have
2924 graphics and serial in the boot menu.
2925 Set this variable to "1" in your
2926 <filename>local.conf</filename> or distribution
2927 configuration file to enable graphics and serial
2928 in the menu.
2929 </para>
2930
2931 <para>
2932 See the
2933 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2934 class for more information on how this variable is used.
2935 </para>
2936 </glossdef>
2937 </glossentry>
2938
2939 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
2940 <glossdef>
2941 <para>
2942 Additional options to add to the GNU GRand Unified
2943 Bootloader (GRUB) configuration.
2944 Use a semi-colon character (<filename>;</filename>) to
2945 separate multiple options.
2946 </para>
2947
2948 <para>
2949 The <filename>GRUB_OPTS</filename> variable is optional.
2950 See the
2951 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2952 class for more information on how this variable is used.
2953 </para>
2954 </glossdef>
2955 </glossentry>
2956
2957 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
2958 <glossdef>
2959 <para>
2960 Specifies the timeout before executing the default
2961 <filename>LABEL</filename> in the GNU GRand Unified
2962 Bootloader (GRUB).
2963 </para>
2964
2965 <para>
2966 The <filename>GRUB_TIMEOUT</filename> variable is optional.
2967 See the
2968 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2969 class for more information on how this variable is used.
2970 </para>
2971 </glossdef>
2972 </glossentry>
2973
2974 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
2975 <glossdef>
2976 <para>
2977 For recipes that inherit the
2978 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
2979 class, this variable specifies the packages that contain the
2980 GTK+ input method modules being installed when the modules
2981 are in packages other than the main package.
2982 </para>
2983 </glossdef>
2984 </glossentry>
2985
2986 </glossdiv>
2987
2988 <glossdiv id='var-glossary-h'><title>H</title>
2989
2990 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
2991 <glossdef>
2992 <para>Website where more information about the software the recipe is building
2993 can be found.</para>
2994 </glossdef>
2995 </glossentry>
2996
2997 <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm>
2998 <glossdef>
2999 <para>
3000 Specifies architecture-specific compiler flags that are
3001 passed to the C compiler.
3002 </para>
3003
3004 <para>
3005 Default initialization for <filename>HOST_CC_ARCH</filename>
3006 varies depending on what is being built:
3007 <itemizedlist>
3008 <listitem><para>
3009 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
3010 when building for the target
3011 </para></listitem>
3012 <listitem><para>
3013 <filename>BUILD_CC_ARCH</filename>
3014 when building for the build host (i.e.
3015 <filename>native</filename>)
3016 </para></listitem>
3017 <listitem><para>
3018 <filename>BUILDSDK_CC_ARCH</filename>
3019 when building for an SDK (i.e.
3020 <filename>nativesdk</filename>)
3021 </para></listitem>
3022 </itemizedlist>
3023 </para>
3024 </glossdef>
3025 </glossentry>
3026
3027 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
3028 <glossdef>
3029 <para>
3030 Specifies the system, including the architecture and the
3031 operating system, for with the build is occurring
3032 in the context of the current
3033 recipe.
3034 The OpenEmbedded build system automatically sets this
3035 variable.
3036 You do not need to set the variable yourself.
3037 </para>
3038
3039 <para>
3040 Here are two examples:
3041 <itemizedlist>
3042 <listitem><para>Given a native recipe on a 32-bit
3043 x86 machine running Linux, the value is
3044 "i686-linux".
3045 </para></listitem>
3046 <listitem><para>Given a recipe being built for a
3047 little-endian MIPS target running Linux,
3048 the value might be "mipsel-linux".
3049 </para></listitem>
3050 </itemizedlist>
3051 </para>
3052 </glossdef>
3053 </glossentry>
3054
3055 </glossdiv>
3056
3057 <glossdiv id='var-glossary-i'><title>I</title>
3058
3059 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
3060 <glossdef>
3061 <para>
3062 Disables or enables the <filename>icecc</filename>
3063 (Icecream) function.
3064 For more information on this function and best practices
3065 for using this variable, see the
3066 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
3067 section.
3068 </para>
3069
3070 <para>
3071 Setting this variable to "1" in your
3072 <filename>local.conf</filename> disables the function:
3073 <literallayout class='monospaced'>
3074 ICECC_DISABLED ??= "1"
3075 </literallayout>
3076 To enable the function, set the variable as follows:
3077 <literallayout class='monospaced'>
3078 ICECC_DISABLED = ""
3079 </literallayout>
3080 </para>
3081 </glossdef>
3082 </glossentry>
3083
3084 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
3085 <glossdef>
3086 <para>
3087 Points to the <filename>icecc-create-env</filename> script
3088 that you provide.
3089 This variable is used by the
3090 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3091 class.
3092 You set this variable in your
3093 <filename>local.conf</filename> file.
3094 </para>
3095
3096 <para>
3097 If you do not point to a script that you provide, the
3098 OpenEmbedded build system uses the default script provided
3099 by the <filename>icecc-create-env.bb</filename> recipe,
3100 which is a modified version and not the one that comes with
3101 <filename>icecc</filename>.
3102 </para>
3103 </glossdef>
3104 </glossentry>
3105
3106 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
3107 <glossdef>
3108 <para>
3109 Extra options passed to the <filename>make</filename>
3110 command during the
3111 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
3112 task that specify parallel compilation.
3113 This variable usually takes the form of
3114 <filename>-j 4</filename>, where the number
3115 represents the maximum number of parallel threads
3116 <filename>make</filename> can run.
3117 <note>
3118 The options passed affect builds on all enabled
3119 machines on the network, which are machines running the
3120 <filename>iceccd</filename> daemon.
3121 </note>
3122 </para>
3123
3124 <para>
3125 If your enabled machines support multiple cores,
3126 coming up with the maximum number of parallel threads
3127 that gives you the best performance could take some
3128 experimentation since machine speed, network lag,
3129 available memory, and existing machine loads can all
3130 affect build time.
3131 Consequently, unlike the
3132 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
3133 variable, there is no rule-of-thumb for setting
3134 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
3135 optimal performance.
3136 </para>
3137
3138 <para>
3139 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
3140 the build system does not use it (i.e. the system does
3141 not detect and assign the number of cores as is done with
3142 <filename>PARALLEL_MAKE</filename>).
3143 </para>
3144 </glossdef>
3145 </glossentry>
3146
3147 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
3148 <glossdef>
3149 <para>
3150 The location of the <filename>icecc</filename> binary.
3151 You can set this variable in your
3152 <filename>local.conf</filename> file.
3153 If your <filename>local.conf</filename> file does not define
3154 this variable, the
3155 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3156 class attempts to define it by locating
3157 <filename>icecc</filename> using <filename>which</filename>.
3158 </para>
3159 </glossdef>
3160 </glossentry>
3161
3162 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
3163 <glossdef>
3164 <para>
3165 Identifies user classes that you do not want the
3166 Icecream distributed compile support to consider.
3167 This variable is used by the
3168 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3169 class.
3170 You set this variable in your
3171 <filename>local.conf</filename> file.
3172 </para>
3173
3174 <para>
3175 When you list classes using this variable, you are
3176 "blacklisting" them from distributed compilation across
3177 remote hosts.
3178 Any classes you list will be distributed and compiled
3179 locally.
3180 </para>
3181 </glossdef>
3182 </glossentry>
3183
3184 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
3185 <glossdef>
3186 <para>
3187 Identifies user recipes that you do not want the
3188 Icecream distributed compile support to consider.
3189 This variable is used by the
3190 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3191 class.
3192 You set this variable in your
3193 <filename>local.conf</filename> file.
3194 </para>
3195
3196 <para>
3197 When you list packages using this variable, you are
3198 "blacklisting" them from distributed compilation across
3199 remote hosts.
3200 Any packages you list will be distributed and compiled
3201 locally.
3202 </para>
3203 </glossdef>
3204 </glossentry>
3205
3206 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
3207 <glossdef>
3208 <para>
3209 Identifies user recipes that use an empty
3210 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
3211 variable that you want to force remote distributed
3212 compilation on using the Icecream distributed compile
3213 support.
3214 This variable is used by the
3215 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
3216 class.
3217 You set this variable in your
3218 <filename>local.conf</filename> file.
3219 </para>
3220 </glossdef>
3221 </glossentry>
3222
3223 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
3224 <glossdef>
3225 <para>
3226 The base name of image output files.
3227 This variable defaults to the recipe name
3228 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
3229 </para>
3230 </glossdef>
3231 </glossentry>
3232
3233 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
3234 <glossdef>
3235 <para>
3236 A list of classes that all images should inherit.
3237 You typically use this variable to specify the list of
3238 classes that register the different types of images
3239 the OpenEmbedded build system creates.
3240 </para>
3241
3242 <para>
3243 The default value for <filename>IMAGE_CLASSES</filename> is
3244 <filename>image_types</filename>.
3245 You can set this variable in your
3246 <filename>local.conf</filename> or in a distribution
3247 configuration file.
3248 </para>
3249
3250 <para>
3251 For more information, see
3252 <filename>meta/classes/image_types.bbclass</filename> in the
3253 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3254 </para>
3255 </glossdef>
3256 </glossentry>
3257
3258 <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>
3259 <glossdef>
3260 <para>
3261 Specifies the command to create the image file for a
3262 specific image type, which corresponds to the value set
3263 set in
3264 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
3265 (e.g. <filename>ext3</filename>,
3266 <filename>btrfs</filename>, and so forth).
3267 When setting this variable, you should use
3268 an override for the associated type.
3269 Here is an example:
3270 <literallayout class='monospaced'>
3271 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
3272 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
3273 ${EXTRA_IMAGECMD}"
3274 </literallayout>
3275 You typically do not need to set this variable unless
3276 you are adding support for a new image type.
3277 For more examples on how to set this variable, see the
3278 <link linkend='ref-classes-image_types'><filename>image_types</filename></link>
3279 class file, which is
3280 <filename>meta/classes/image_types.bbclass</filename>.
3281 </para>
3282 </glossdef>
3283 </glossentry>
3284
3285 <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>
3286 <glossdef>
3287 <para>
3288 Specifies one or more files that contain custom device
3289 tables that are passed to the
3290 <filename>makedevs</filename> command as part of creating
3291 an image.
3292 These files list basic device nodes that should be
3293 created under <filename>/dev</filename> within the image.
3294 If <filename>IMAGE_DEVICE_TABLES</filename> is not set,
3295 <filename>files/device_table-minimal.txt</filename> is
3296 used, which is located by
3297 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
3298 For details on how you should write device table files,
3299 see <filename>meta/files/device_table-minimal.txt</filename>
3300 as an example.
3301 </para>
3302 </glossdef>
3303 </glossentry>
3304
3305 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
3306 <glossdef>
3307 <para>
3308 The primary list of features to include in an image.
3309 Typically, you configure this variable in an image recipe.
3310 Although you can use this variable from your
3311 <filename>local.conf</filename> file, which is found in the
3312 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
3313 best practices dictate that you do not.
3314 <note>
3315 To enable extra features from outside the image recipe,
3316 use the
3317 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
3318 </note>
3319 For a list of image features that ships with the Yocto
3320 Project, see the
3321 "<link linkend="ref-features-image">Image Features</link>"
3322 section.
3323 </para>
3324
3325 <para>
3326 For an example that shows how to customize your image by
3327 using this variable, see the
3328 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
3329 section in the Yocto Project Development Manual.
3330 </para>
3331 </glossdef>
3332 </glossentry>
3333
3334 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
3335 <glossdef>
3336 <para>
3337 Specifies the formats the OpenEmbedded build system uses
3338 during the build when creating the root filesystem.
3339 For example, setting <filename>IMAGE_FSTYPES</filename>
3340 as follows causes the build system to create root
3341 filesystems using two formats: <filename>.ext3</filename>
3342 and <filename>.tar.bz2</filename>:
3343 <literallayout class='monospaced'>
3344 IMAGE_FSTYPES = "ext3 tar.bz2"
3345 </literallayout>
3346 For the complete list of supported image formats from which
3347 you can choose, see
3348 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
3349 </para>
3350
3351 <note>
3352 If you add "live" to <filename>IMAGE_FSTYPES</filename>
3353 inside an image recipe, be sure that you do so prior to the
3354 "inherit image" line of the recipe or the live image will
3355 not build.
3356 </note>
3357
3358 <note>
3359 Due to the way this variable is processed, it is not
3360 possible to update its contents using
3361 <filename>_append</filename> or
3362 <filename>_prepend</filename>. To add one or more
3363 additional options to this variable the
3364 <filename>+=</filename> operator must be used.
3365 </note>
3366 </glossdef>
3367 </glossentry>
3368
3369 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
3370 <glossdef>
3371 <para>
3372 Specifies the packages to install into an image.
3373 The <filename>IMAGE_INSTALL</filename> variable is a
3374 mechanism for an image recipe and you should use it
3375 with care to avoid ordering issues.
3376 <note>
3377 When working with an
3378 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
3379 image, do not use the <filename>IMAGE_INSTALL</filename>
3380 variable to specify packages for installation.
3381 Instead, use the
3382 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
3383 variable, which allows the initial RAM disk (initramfs)
3384 recipe to use a fixed set of packages and not be
3385 affected by <filename>IMAGE_INSTALL</filename>.
3386 </note>
3387 </para>
3388
3389 <para>
3390 Image recipes set <filename>IMAGE_INSTALL</filename>
3391 to specify the packages to install into an image through
3392 <filename>image.bbclass</filename>.
3393 Additionally, "helper" classes exist, such as
3394 <filename>core-image.bbclass</filename>, that can take
3395 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
3396 lists and turn these into auto-generated entries in
3397 <filename>IMAGE_INSTALL</filename> in addition to its
3398 default contents.
3399 </para>
3400
3401 <para>
3402 Using <filename>IMAGE_INSTALL</filename> with the
3403 <filename>+=</filename> operator from the
3404 <filename>/conf/local.conf</filename> file or from within
3405 an image recipe is not recommended as it can cause ordering
3406 issues.
3407 Since <filename>core-image.bbclass</filename> sets
3408 <filename>IMAGE_INSTALL</filename> to a default value using
3409 the <filename>?=</filename> operator, using a
3410 <filename>+=</filename> operation against
3411 <filename>IMAGE_INSTALL</filename> will result in
3412 unexpected behavior when used in
3413 <filename>conf/local.conf</filename>.
3414 Furthermore, the same operation from within an image
3415 recipe may or may not succeed depending on the specific
3416 situation.
3417 In both these cases, the behavior is contrary to how most
3418 users expect the <filename>+=</filename> operator to work.
3419 </para>
3420
3421 <para>
3422 When you use this variable, it is best to use it as follows:
3423 <literallayout class='monospaced'>
3424 IMAGE_INSTALL_append = " package-name"
3425 </literallayout>
3426 Be sure to include the space between the quotation character
3427 and the start of the package name or names.
3428 </para>
3429 </glossdef>
3430 </glossentry>
3431
3432 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
3433 <glossdef>
3434 <para>
3435 Specifies the list of locales to install into the image
3436 during the root filesystem construction process.
3437 The OpenEmbedded build system automatically splits locale
3438 files, which are used for localization, into separate
3439 packages.
3440 Setting the <filename>IMAGE_LINGUAS</filename> variable
3441 ensures that any locale packages that correspond to packages
3442 already selected for installation into the image are also
3443 installed.
3444 Here is an example:
3445 <literallayout class='monospaced'>
3446 IMAGE_LINGUAS = "pt-br de-de"
3447 </literallayout>
3448 In this example, the build system ensures any Brazilian
3449 Portuguese and German locale files that correspond to
3450 packages in the image are installed (i.e.
3451 <filename>*-locale-pt-br</filename>
3452 and <filename>*-locale-de-de</filename> as well as
3453 <filename>*-locale-pt</filename>
3454 and <filename>*-locale-de</filename>, since some software
3455 packages only provide locale files by language and not by
3456 country-specific language).
3457 </para>
3458 </glossdef>
3459 </glossentry>
3460
3461 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
3462 <glossdef>
3463 <para>
3464 The manifest file for the image.
3465 This file lists all the installed packages that make up
3466 the image.
3467 The file contains package information on a line-per-package
3468 basis as follows:
3469 <literallayout class='monospaced'>
3470 &lt;packagename&gt; &lt;packagearch&gt; &lt;version&gt;
3471 </literallayout>
3472 </para>
3473
3474 <para>
3475 The
3476 <link linkend='ref-classes-image'><filename>image</filename></link>
3477 class defines the manifest file as follows:
3478 <literallayout class='monospaced'>
3479 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
3480 </literallayout>
3481 The location is derived using the
3482 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3483 and
3484 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
3485 variables.
3486 You can find information on how the image
3487 is created in the
3488 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
3489 section.
3490 </para>
3491 </glossdef>
3492 </glossentry>
3493
3494 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
3495 <glossdef>
3496 <para>
3497 The name of the output image files minus the extension.
3498 This variable is derived using the
3499 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
3500 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3501 and
3502 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3503 variables:
3504 <literallayout class='monospaced'>
3505 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
3506 </literallayout>
3507 </para>
3508 </glossdef>
3509 </glossentry>
3510
3511 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
3512 <glossdef>
3513 <para>
3514 Defines a multiplier that the build system applies to the initial image
3515 size for cases when the multiplier times the returned disk usage value
3516 for the image is greater than the sum of
3517 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3518 and
3519 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
3520 The result of the multiplier applied to the initial image size creates
3521 free disk space in the image as overhead.
3522 By default, the build process uses a multiplier of 1.3 for this variable.
3523 This default value results in 30% free disk space added to the image when this
3524 method is used to determine the final generated image size.
3525 You should be aware that post install scripts and the package management
3526 system uses disk space inside this overhead area.
3527 Consequently, the multiplier does not produce an image with
3528 all the theoretical free disk space.
3529 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3530 for information on how the build system determines the overall image size.
3531 </para>
3532
3533 <para>
3534 The default 30% free disk space typically gives the image enough room to boot
3535 and allows for basic post installs while still leaving a small amount of
3536 free disk space.
3537 If 30% free space is inadequate, you can increase the default value.
3538 For example, the following setting gives you 50% free space added to the image:
3539 <literallayout class='monospaced'>
3540 IMAGE_OVERHEAD_FACTOR = "1.5"
3541 </literallayout>
3542 </para>
3543
3544 <para>
3545 Alternatively, you can ensure a specific amount of free disk space is added
3546 to the image by using the
3547 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3548 variable.
3549 </para>
3550 </glossdef>
3551 </glossentry>
3552
3553 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
3554 <glossdef>
3555 <para>
3556 Defines the package type (DEB, RPM, IPK, or TAR) used
3557 by the OpenEmbedded build system.
3558 The variable is defined appropriately by the
3559 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
3560 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
3561 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
3562 or
3563 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3564 class.
3565 </para>
3566
3567 <para>
3568 The
3569 <link linkend='ref-classes-populate-sdk-*'><filename>package_sdk_base</filename></link>
3570 and
3571 <link linkend='ref-classes-image'><filename>image</filename></link>
3572 classes use the <filename>IMAGE_PKGTYPE</filename> for
3573 packaging up images and SDKs.
3574 </para>
3575
3576 <para>
3577 You should not set the <filename>IMAGE_PKGTYPE</filename>
3578 manually.
3579 Rather, the variable is set indirectly through the
3580 appropriate
3581 <link linkend='ref-classes-package'><filename>package_*</filename></link>
3582 class using the
3583 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3584 variable.
3585 The OpenEmbedded build system uses the first package type
3586 (e.g. DEB, RPM, or IPK) that appears with the variable
3587 <note>
3588 Files using the <filename>.tar</filename> format are
3589 never used as a substitute packaging format for DEB,
3590 RPM, and IPK formatted files for your image or SDK.
3591 </note>
3592 </para>
3593 </glossdef>
3594 </glossentry>
3595
3596 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
3597 <glossdef>
3598 <para>
3599 Added by classes to run post processing commands once the
3600 OpenEmbedded build system has created the image.
3601 You can specify shell commands separated by semicolons:
3602 <literallayout class='monospaced'>
3603 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
3604 </literallayout>
3605 If you need to pass the path to the root filesystem within
3606 the command, you can use
3607 <filename>${IMAGE_ROOTFS}</filename>, which points to
3608 the root filesystem image.
3609 </para>
3610 </glossdef>
3611 </glossentry>
3612
3613 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
3614 <glossdef>
3615 <para>
3616 The location of the root filesystem while it is under
3617 construction (i.e. during the
3618 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
3619 task).
3620 This variable is not configurable.
3621 Do not change it.
3622 </para>
3623 </glossdef>
3624 </glossentry>
3625
3626 <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>
3627 <glossdef>
3628 <para>
3629 Specifies the alignment for the output image file in
3630 Kbytes.
3631 If the size of the image is not a multiple of
3632 this value, then the size is rounded up to the nearest
3633 multiple of the value.
3634 The default value is "1".
3635 See
3636 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
3637 for additional information.
3638 </para>
3639 </glossdef>
3640 </glossentry>
3641
3642 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
3643 <glossdef>
3644 <para>
3645 Defines additional free disk space created in the image in Kbytes.
3646 By default, this variable is set to "0".
3647 This free disk space is added to the image after the build system determines
3648 the image size as described in
3649 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
3650 </para>
3651
3652 <para>
3653 This variable is particularly useful when you want to ensure that a
3654 specific amount of free disk space is available on a device after an image
3655 is installed and running.
3656 For example, to be sure 5 Gbytes of free disk space is available, set the
3657 variable as follows:
3658 <literallayout class='monospaced'>
3659 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3660 </literallayout>
3661 </para>
3662
3663 <para>
3664 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
3665 of extra space with the line:
3666 <literallayout class='monospaced'>
3667 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3668 </literallayout>
3669 </para>
3670 </glossdef>
3671 </glossentry>
3672
3673 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
3674 <glossdef>
3675 <para>
3676 Defines the size in Kbytes for the generated image.
3677 The OpenEmbedded build system determines the final size for the generated
3678 image using an algorithm that takes into account the initial disk space used
3679 for the generated image, a requested size for the image, and requested
3680 additional free disk space to be added to the image.
3681 Programatically, the build system determines the final size of the
3682 generated image as follows:
3683 <literallayout class='monospaced'>
3684 if (image-du * overhead) &lt; rootfs-size:
3685 internal-rootfs-size = rootfs-size + xspace
3686 else:
3687 internal-rootfs-size = (image-du * overhead) + xspace
3688
3689 where:
3690
3691 image-du = Returned value of the du command on
3692 the image.
3693
3694 overhead = IMAGE_OVERHEAD_FACTOR
3695
3696 rootfs-size = IMAGE_ROOTFS_SIZE
3697
3698 internal-rootfs-size = Initial root filesystem
3699 size before any modifications.
3700
3701 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3702 </literallayout>
3703 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
3704 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
3705 variables for related information.
3706<!-- In the above example, <filename>overhead</filename> is defined by the
3707 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
3708 variable, <filename>xspace</filename> is defined by the
3709 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3710 variable, and <filename>du</filename> is the results of the disk usage command
3711 on the initially generated image. -->
3712 </para>
3713 </glossdef>
3714 </glossentry>
3715
3716 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
3717 <glossdef>
3718 <para>
3719 Specifies a dependency from one image type on another.
3720 Here is an example from the
3721 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
3722 class:
3723 <literallayout class='monospaced'>
3724 IMAGE_TYPEDEP_live = "ext3"
3725 </literallayout>
3726 In the previous example, the variable ensures that when
3727 "live" is listed with the
3728 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3729 variable, the OpenEmbedded build system produces an
3730 <filename>ext3</filename> image first since one of the
3731 components of the live
3732 image is an <filename>ext3</filename>
3733 formatted partition containing the root
3734 filesystem.
3735 </para>
3736 </glossdef>
3737 </glossentry>
3738
3739 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
3740 <glossdef>
3741 <para>
3742 Specifies the complete list of supported image types
3743 by default:
3744 <literallayout class='monospaced'>
3745 jffs2
3746 jffs2.sum
3747 cramfs
3748 ext2
3749 ext2.gz
3750 ext2.bz2
3751 ext3
3752 ext3.gz
3753 ext2.lzma
3754 btrfs
3755 live
3756 squashfs
3757 squashfs-xz
3758 ubi
3759 ubifs
3760 tar
3761 tar.gz
3762 tar.bz2
3763 tar.xz
3764 cpio
3765 cpio.gz
3766 cpio.xz
3767 cpio.lzma
3768 vmdk
3769 elf
3770 </literallayout>
3771 For more information about these types of images, see
3772 <filename>meta/classes/image_types*.bbclass</filename>
3773 in the
3774 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3775 </para>
3776 </glossdef>
3777 </glossentry>
3778
3779 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
3780 <glossdef>
3781 <para>Helps define the recipe revision for recipes that share
3782 a common <filename>include</filename> file.
3783 You can think of this variable as part of the recipe revision
3784 as set from within an include file.</para>
3785 <para>Suppose, for example, you have a set of recipes that
3786 are used across several projects.
3787 And, within each of those recipes the revision
3788 (its <link linkend='var-PR'><filename>PR</filename></link>
3789 value) is set accordingly.
3790 In this case, when the revision of those recipes changes,
3791 the burden is on you to find all those recipes and
3792 be sure that they get changed to reflect the updated
3793 version of the recipe.
3794 In this scenario, it can get complicated when recipes
3795 that are used in many places and provide common functionality
3796 are upgraded to a new revision.</para>
3797 <para>A more efficient way of dealing with this situation is
3798 to set the <filename>INC_PR</filename> variable inside
3799 the <filename>include</filename> files that the recipes
3800 share and then expand the <filename>INC_PR</filename>
3801 variable within the recipes to help
3802 define the recipe revision.
3803 </para>
3804 <para>
3805 The following provides an example that shows how to use
3806 the <filename>INC_PR</filename> variable
3807 given a common <filename>include</filename> file that
3808 defines the variable.
3809 Once the variable is defined in the
3810 <filename>include</filename> file, you can use the
3811 variable to set the <filename>PR</filename> values in
3812 each recipe.
3813 You will notice that when you set a recipe's
3814 <filename>PR</filename> you can provide more granular
3815 revisioning by appending values to the
3816 <filename>INC_PR</filename> variable:
3817 <literallayout class='monospaced'>
3818recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3819recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3820recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3821recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3822 </literallayout>
3823 The first line of the example establishes the baseline
3824 revision to be used for all recipes that use the
3825 <filename>include</filename> file.
3826 The remaining lines in the example are from individual
3827 recipes and show how the <filename>PR</filename> value
3828 is set.</para>
3829 </glossdef>
3830 </glossentry>
3831
3832 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
3833 <glossdef>
3834 <para>
3835 Specifies a space-separated list of license names
3836 (as they would appear in
3837 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
3838 that should be excluded from the build.
3839 Recipes that provide no alternatives to listed incompatible
3840 licenses are not built.
3841 Packages that are individually licensed with the specified
3842 incompatible licenses will be deleted.
3843 </para>
3844
3845 <note>
3846 This functionality is only regularly tested using
3847 the following setting:
3848 <literallayout class='monospaced'>
3849 INCOMPATIBLE_LICENSE = "GPLv3"
3850 </literallayout>
3851 Although you can use other settings, you might be required
3852 to remove dependencies on or provide alternatives to
3853 components that are required to produce a functional system
3854 image.
3855 </note>
3856 </glossdef>
3857 </glossentry>
3858
3859 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
3860 <glossdef>
3861 <para>
3862 Prevents the default dependencies, namely the C compiler
3863 and standard C library (libc), from being added to
3864 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
3865 This variable is usually used within recipes that do not
3866 require any compilation using the C compiler.
3867 </para>
3868
3869 <para>
3870 Set the variable to "1" to prevent the default dependencies
3871 from being added.
3872 </para>
3873 </glossdef>
3874 </glossentry>
3875
3876 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
3877 <glossdef>
3878 <para>
3879 If set to "1", causes the build to not strip binaries in resulting packages.
3880 </para>
3881 </glossdef>
3882 </glossentry>
3883
3884 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
3885 <glossdef>
3886 <para>
3887 Causes the named class to be inherited at
3888 this point during parsing.
3889 The variable is only valid in configuration files.
3890 </para>
3891 </glossdef>
3892 </glossentry>
3893
3894 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
3895 <glossdef>
3896 <para>
3897 Lists classes that will be inherited at the
3898 distribution level.
3899 It is unlikely that you want to edit this variable.
3900 </para>
3901
3902 <para>
3903 The default value of the variable is set as follows in the
3904 <filename>meta/conf/distro/defaultsetup.conf</filename>
3905 file:
3906 <literallayout class='monospaced'>
3907 INHERIT_DISTRO ?= "debian devshell sstate license"
3908 </literallayout>
3909 </para>
3910 </glossdef>
3911 </glossentry>
3912
3913 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
3914 <glossdef>
3915 <para>
3916 Defines the format for the output image of an initial
3917 RAM disk (initramfs), which is used during boot.
3918 Supported formats are the same as those supported by the
3919 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3920 variable.
3921 </para>
3922 </glossdef>
3923 </glossentry>
3924
3925 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
3926 <glossdef>
3927 <para>
3928 Causes the OpenEmbedded build system to build an additional
3929 recipe as a dependency to your root filesystem recipe
3930 (e.g. <filename>core-image-sato</filename>).
3931 The additional recipe is used to create an initial RAM disk
3932 (initramfs) that might be needed during the initial boot of
3933 the target system to accomplish such things as loading
3934 kernel modules prior to mounting the root file system.
3935 </para>
3936
3937 <para>
3938 When you set the variable, specify the name of the
3939 initramfs you want created.
3940 The following example, which is set in the
3941 <filename>local.conf</filename> configuration file, causes
3942 a separate recipe to be created that results in an
3943 initramfs image named
3944 <filename>core-image-sato-initramfs.bb</filename> to be
3945 created:
3946 <literallayout class='monospaced'>
3947 INITRAMFS_IMAGE = "core-image-minimal-initramfs"
3948 </literallayout>
3949 By default, the
3950 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3951 class sets this variable to a null string as follows:
3952 <literallayout class='monospaced'>
3953 INITRAMFS_IMAGE = ""
3954 </literallayout>
3955 </para>
3956
3957 <para>
3958 See the
3959 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
3960 file for additional information.
3961 You can also reference the
3962 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/kernel.bbclass'><filename>kernel.bbclass</filename></ulink>
3963 file to see how the variable is used.
3964 </para>
3965 </glossdef>
3966 </glossentry>
3967
3968 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
3969 <glossdef>
3970 <para>
3971 Controls whether or not the image recipe specified by
3972 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
3973 is run through an extra pass during kernel compilation
3974 in order to build a single binary that contains both the
3975 kernel image and the initial RAM disk (initramfs).
3976 Using an extra compilation pass ensures that when a kernel
3977 attempts to use an initramfs, it does not encounter
3978 circular dependencies should the initramfs include kernel
3979 modules.
3980 </para>
3981
3982 <para>
3983 The combined binary is deposited into the
3984 <filename>tmp/deploy</filename> directory, which is part
3985 of the
3986 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
3987 </para>
3988
3989 <para>
3990 Setting the variable to "1" in a configuration file causes
3991 the OpenEmbedded build system to make the extra pass during
3992 kernel compilation:
3993 <literallayout class='monospaced'>
3994 INITRAMFS_IMAGE_BUNDLE = "1"
3995 </literallayout>
3996 By default, the
3997 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3998 class sets this variable to a null string as follows:
3999 <literallayout class='monospaced'>
4000 INITRAMFS_IMAGE_BUNDLE = ""
4001 </literallayout>
4002 <note>
4003 You must set the
4004 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
4005 a configuration file.
4006 You cannot set the variable in a recipe file.
4007 </note>
4008 See the
4009 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
4010 file for additional information.
4011 </para>
4012 </glossdef>
4013 </glossentry>
4014
4015 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
4016 <glossdef>
4017 <para>
4018 Indicates a filesystem image to use as an initial RAM
4019 disk (<filename>initrd</filename>).
4020 </para>
4021
4022 <para>
4023 The <filename>INITRD</filename> variable is an optional
4024 variable used with the
4025 <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link>
4026 class.
4027 </para>
4028 </glossdef>
4029 </glossentry>
4030
4031 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
4032 <glossdef>
4033 <para>
4034 The filename of the initialization script as installed to
4035 <filename>${sysconfdir}/init.d</filename>.
4036 </para>
4037 <para>
4038 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
4039 The variable is mandatory.
4040 </para>
4041 </glossdef>
4042 </glossentry>
4043
4044 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
4045 <glossdef>
4046 <para>
4047 A list of the packages that contain initscripts.
4048 If multiple packages are specified, you need to append the package name
4049 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
4050 <para>
4051 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
4052 The variable is optional and defaults to the
4053 <link linkend='var-PN'><filename>PN</filename></link> variable.
4054 </para>
4055 </glossdef>
4056 </glossentry>
4057
4058 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
4059 <glossdef>
4060 <para>
4061 Specifies the options to pass to <filename>update-rc.d</filename>.
4062 Here is an example:
4063 <literallayout class='monospaced'>
4064 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
4065 </literallayout>
4066 In this example, the script has a runlevel of 99,
4067 starts the script in initlevels 2 and 5, and
4068 stops the script in levels 0, 1 and 6.
4069 </para>
4070 <para>
4071 The variable is mandatory and is used in recipes when using
4072 <filename>update-rc.d.bbclass</filename>.
4073 </para>
4074 </glossdef>
4075 </glossentry>
4076
4077 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
4078 <glossdef>
4079 <para>
4080 Specifies the QA checks to skip for a specific package
4081 within a recipe.
4082 For example, to skip the check for symbolic link
4083 <filename>.so</filename> files in the main package of a
4084 recipe, add the following to the recipe.
4085 The package name override must be used, which in this
4086 example is <filename>${PN}</filename>:
4087 <literallayout class='monospaced'>
4088 INSANE_SKIP_${PN} += "dev-so"
4089 </literallayout>
4090 </para>
4091 <para>
4092 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
4093 section for a list of the valid QA checks you can
4094 specify using this variable.
4095 </para>
4096 </glossdef>
4097 </glossentry>
4098
4099 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
4100 <glossdef>
4101 <para>
4102 When the IPK backend is in use and package management
4103 is enabled on the target, you can use this variable to
4104 set up <filename>opkg</filename> in the target image
4105 to point to package feeds on a nominated server.
4106 Once the feed is established, you can perform
4107 installations or upgrades using the package manager
4108 at runtime.
4109 </para>
4110 </glossdef>
4111 </glossentry>
4112
4113<!--
4114 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
4115 <glossdef>
4116 <para>
4117 An environment variable that defines the directory where
4118 post installation hooks are installed for the
4119 post install environment.
4120 This variable is fixed as follows:
4121 <literallayout class='monospaced'>
4122 ${WORKDIR}/intercept_scripts
4123 </literallayout>
4124 </para>
4125
4126 <para>
4127 After installation of a target's root filesystem,
4128 post installation scripts, which are essentially bash scripts,
4129 are all executed just a single time.
4130 Limiting execution of these scripts minimizes installation
4131 time that would be lengthened due to certain packages
4132 triggering redundant operations.
4133 For example, consider the installation of font packages
4134 as a common example.
4135 Without limiting the execution of post installation scripts,
4136 all font directories would be rescanned to create the
4137 cache after each individual font package was installed.
4138 </para>
4139
4140 <para>
4141 Do not edit the <filename>INTERCEPT_DIR</filename>
4142 variable.
4143 </para>
4144 </glossdef>
4145 </glossentry>
4146-->
4147
4148 </glossdiv>
4149
4150<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
4151<!-- </glossdiv>-->
4152
4153 <glossdiv id='var-glossary-k'><title>K</title>
4154
4155 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
4156 <glossdef>
4157 <para>
4158 Defines the kernel architecture used when assembling
4159 the configuration.
4160 Architectures supported for this release are:
4161 <literallayout class='monospaced'>
4162 powerpc
4163 i386
4164 x86_64
4165 arm
4166 qemu
4167 mips
4168 </literallayout>
4169 </para>
4170
4171 <para>
4172 You define the <filename>KARCH</filename> variable in the
4173 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
4174 </para>
4175 </glossdef>
4176 </glossentry>
4177
4178 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
4179 <glossdef>
4180 <para>
4181 A regular expression used by the build process to explicitly
4182 identify the kernel branch that is validated, patched
4183 and configured during a build.
4184 The <filename>KBRANCH</filename> variable is optional.
4185 You can use it to trigger checks to ensure the exact kernel
4186 branch you want is being used by the build process.
4187 </para>
4188
4189 <para>
4190 Values for this variable are set in the kernel's recipe
4191 file and the kernel's append file.
4192 For example, if you are using the Yocto Project kernel that
4193 is based on the Linux 3.10 kernel, the kernel recipe file
4194 is the
4195 <filename>meta/recipes-kernel/linux/linux-yocto_3.10.bb</filename>
4196 file.
4197 Following is the default value for <filename>KBRANCH</filename>
4198 and the default override for the architectures the Yocto
4199 Project supports:
4200 <literallayout class='monospaced'>
4201 KBRANCH_DEFAULT = "standard/base"
4202 KBRANCH = "${KBRANCH_DEFAULT}"
4203 </literallayout>
4204 This branch exists in the <filename>linux-yocto-3.10</filename>
4205 kernel Git repository
4206 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.10/refs/heads'></ulink>.
4207 </para>
4208
4209 <para>
4210 This variable is also used from the kernel's append file
4211 to identify the kernel branch specific to a particular
4212 machine or target hardware.
4213 The kernel's append file is located in the BSP layer for
4214 a given machine.
4215 For example, the kernel append file for the Crown Bay BSP is in the
4216 <filename>meta-intel</filename> Git repository and is named
4217 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend</filename>.
4218 Here are the related statements from the append file:
4219 <literallayout class='monospaced'>
4220 COMPATIBLE_MACHINE_crownbay = "crownbay"
4221 KMACHINE_crownbay = "crownbay"
4222 KBRANCH_crownbay = "standard/crownbay"
4223 KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb"
4224
4225 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
4226 KMACHINE_crownbay-noemgd = "crownbay"
4227 KBRANCH_crownbay-noemgd = "standard/crownbay"
4228 KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb"
4229 </literallayout>
4230 The <filename>KBRANCH_*</filename> statements identify
4231 the kernel branch to use when building for the Crown
4232 Bay BSP.
4233 In this case there are two identical statements: one
4234 for each type of Crown Bay machine.
4235 </para>
4236 </glossdef>
4237 </glossentry>
4238
4239 <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
4240 <glossdef>
4241 <para>
4242 Defines the Linux kernel source repository's default
4243 branch used to build the Linux kernel.
4244 The <filename>KBRANCH_DEFAULT</filename> value is
4245 the default value for
4246 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
4247 Unless you specify otherwise,
4248 <filename>KBRANCH_DEFAULT</filename> initializes to
4249 "master".
4250 </para>
4251 </glossdef>
4252 </glossentry>
4253
4254 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
4255 <glossdef>
4256 <para>
4257 Specifies additional <filename>make</filename>
4258 command-line arguments the OpenEmbedded build system
4259 passes on when compiling the kernel.
4260 </para>
4261 </glossdef>
4262 </glossentry>
4263
4264 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
4265 <glossdef>
4266 <para>Includes additional metadata from the Yocto Project kernel Git repository.
4267 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
4268 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4269 is provided through
4270 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
4271 and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
4272 You can use the <filename>KERNEL_FEATURES</filename> variable to further
4273 add metadata for all BSPs.</para>
4274 <para>The metadata you add through this variable includes config fragments and
4275 features descriptions,
4276 which usually includes patches as well as config fragments.
4277 You typically override the <filename>KERNEL_FEATURES</filename> variable
4278 for a specific machine.
4279 In this way, you can provide validated, but optional, sets of kernel
4280 configurations and features.</para>
4281 <para>For example, the following adds <filename>netfilter</filename> to all
4282 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
4283 machine:
4284 <literallayout class='monospaced'>
4285 # Add netfilter to all linux-yocto kernels
4286 KERNEL_FEATURES="features/netfilter"
4287
4288 # Add sound support to the qemux86 machine
4289 KERNEL_FEATURES_append_qemux86=" cfg/sound"
4290 </literallayout></para>
4291 </glossdef>
4292 </glossentry>
4293
4294 <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm>
4295 <glossdef>
4296 <para>
4297 The base name of the kernel image.
4298 This variable is set in the
4299 <link linkend='ref-classes-kernel'>kernel</link> class
4300 as follows:
4301 <literallayout class='monospaced'>
4302 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
4303 </literallayout>
4304 See the
4305 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>,
4306 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
4307 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
4308 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
4309 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
4310 and
4311 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
4312 variables for additional information.
4313 </para>
4314 </glossdef>
4315 </glossentry>
4316
4317 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
4318 <glossdef>
4319 <para>The type of kernel to build for a device, usually set by the
4320 machine configuration files and defaults to "zImage".
4321 This variable is used
4322 when building the kernel and is passed to <filename>make</filename> as the target to
4323 build.</para>
4324 </glossdef>
4325 </glossentry>
4326
4327 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
4328 <glossdef>
4329 <para>
4330 The location of the kernel sources.
4331 This variable is set to the value of the
4332 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
4333 within the <filename>module.bbclass</filename> class.
4334 For information on how this variable is used, see the
4335 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
4336 section.
4337 </para>
4338
4339 <para>
4340 To help maximize compatibility with out-of-tree drivers
4341 used to build modules, the OpenEmbedded build system also
4342 recognizes and uses the
4343 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
4344 variable, which is identical to the
4345 <filename>KERNEL_PATH</filename> variable.
4346 Both variables are common variables used by external
4347 Makefiles to point to the kernel source directory.
4348 </para>
4349 </glossdef>
4350 </glossentry>
4351
4352 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
4353 <glossdef>
4354 <para>
4355 The location of the kernel sources.
4356 This variable is set to the value of the
4357 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
4358 within the <filename>module.bbclass</filename> class.
4359 For information on how this variable is used, see the
4360 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
4361 section.
4362 </para>
4363
4364 <para>
4365 To help maximize compatibility with out-of-tree drivers
4366 used to build modules, the OpenEmbedded build system also
4367 recognizes and uses the
4368 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
4369 variable, which is identical to the
4370 <filename>KERNEL_SRC</filename> variable.
4371 Both variables are common variables used by external
4372 Makefiles to point to the kernel source directory.
4373 </para>
4374 </glossdef>
4375 </glossentry>
4376
4377 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
4378 <glossdef>
4379 <para>
4380 Provides a short description of a configuration fragment.
4381 You use this variable in the <filename>.scc</filename>
4382 file that describes a configuration fragment file.
4383 Here is the variable used in a file named
4384 <filename>smp.scc</filename> to describe SMP being
4385 enabled:
4386 <literallayout class='monospaced'>
4387 define KFEATURE_DESCRIPTION "Enable SMP"
4388 </literallayout>
4389 </para>
4390 </glossdef>
4391 </glossentry>
4392
4393 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
4394 <glossdef>
4395 <para>
4396 The machine as known by the kernel.
4397 Sometimes the machine name used by the kernel does not match the machine name
4398 used by the OpenEmbedded build system.
4399 For example, the machine name that the OpenEmbedded build system understands as
4400 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
4401 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
4402 For cases like these, the <filename>KMACHINE</filename> variable maps the
4403 kernel machine name to the OpenEmbedded build system machine name.
4404 </para>
4405
4406 <para>
4407 Kernel machine names are initially defined in the
4408 Yocto Linux Kernel's <filename>meta</filename> branch.
4409 From the <filename>meta</filename> branch, look in
4410 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
4411 For example, from the <filename>meta</filename> branch in the
4412 <filename>linux-yocto-3.0</filename> kernel, the
4413 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
4414 has the following:
4415 <literallayout class='monospaced'>
4416 define KMACHINE cedartrail
4417 define KTYPE standard
4418 define KARCH i386
4419
4420 include ktypes/standard
4421 branch cedartrail
4422
4423 include cedartrail.scc
4424 </literallayout>
4425 You can see that the kernel understands the machine name for
4426 the Cedar Trail Board Support Package (BSP) as
4427 <filename>cedartrail</filename>.
4428 </para>
4429
4430 <para>
4431 If you look in the Cedar Trail BSP layer in the
4432 <filename>meta-intel</filename>
4433 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
4434 at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
4435 you will find the following statements among others:
4436 <literallayout class='monospaced'>
4437 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
4438 KMACHINE_cedartrail = "cedartrail"
4439 KBRANCH_cedartrail = "yocto/standard/cedartrail"
4440 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
4441 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
4442
4443 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
4444 KMACHINE_cedartrail-nopvr = "cedartrail"
4445 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
4446 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
4447 </literallayout>
4448 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
4449 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
4450 names.
4451 </para>
4452
4453 <para>
4454 This append file uses two <filename>KMACHINE</filename> statements.
4455 The first is not really necessary but does ensure that the machine known to the
4456 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
4457 in the kernel also known as <filename>cedartrail</filename>:
4458 <literallayout class='monospaced'>
4459 KMACHINE_cedartrail = "cedartrail"
4460 </literallayout>
4461 </para>
4462
4463 <para>
4464 The second statement is a good example of why the <filename>KMACHINE</filename> variable
4465 is needed.
4466 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
4467 machine name to refer to the Cedar Trail BSP that does not support the proprietary
4468 PowerVR driver.
4469 The kernel, however, uses the machine name <filename>cedartrail</filename>.
4470 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
4471 the kernel's <filename>cedartrail</filename> name:
4472 <literallayout class='monospaced'>
4473 KMACHINE_cedartrail-nopvr = "cedartrail"
4474 </literallayout>
4475 </para>
4476
4477 <para>
4478 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
4479 Project kernel machine names and the OpenEmbedded machine names.
4480 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
4481 name you use is different than that used in the kernel.
4482 </para>
4483 </glossdef>
4484 </glossentry>
4485
4486 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
4487 <glossdef>
4488 <para>
4489 Defines the kernel type to be used in assembling the
4490 configuration.
4491 The linux-yocto recipes define "standard", "tiny",
4492 and "preempt-rt" kernel types.
4493 See the
4494 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4495 section in the Yocto Project Linux Kernel Development
4496 Manual for more information on kernel types.
4497 </para>
4498
4499 <para>
4500 You define the <filename>KTYPE</filename> variable in the
4501 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
4502 The value you use must match the value used for the
4503 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
4504 value used by the kernel recipe.
4505 </para>
4506 </glossdef>
4507 </glossentry>
4508 </glossdiv>
4509
4510 <glossdiv id='var-glossary-l'><title>L</title>
4511
4512 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
4513 <glossdef>
4514 <para>
4515 Provides a list of targets for automatic configuration.
4516 </para>
4517
4518 <para>
4519 See the
4520 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
4521 class for more information on how this variable is used.
4522 </para>
4523 </glossdef>
4524 </glossentry>
4525
4526 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
4527 <glossdef>
4528 <para>Lists the layers that this recipe depends upon, separated by spaces.
4529 Optionally, you can specify a specific layer version for a dependency
4530 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
4531 to be compared against
4532 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
4533 in this case).
4534 An error will be produced if any dependency is missing or
4535 the version numbers do not match exactly (if specified).
4536 This variable is used in the <filename>conf/layer.conf</filename> file
4537 and must be suffixed with the name of the specific layer (e.g.
4538 <filename>LAYERDEPENDS_mylayer</filename>).</para>
4539 </glossdef>
4540 </glossentry>
4541
4542 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
4543 <glossdef>
4544 <para>When used inside the <filename>layer.conf</filename> configuration
4545 file, this variable provides the path of the current layer.
4546 This variable is not available outside of <filename>layer.conf</filename>
4547 and references are expanded immediately when parsing of the file completes.</para>
4548 </glossdef>
4549 </glossentry>
4550
4551 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
4552 <glossdef>
4553 <para>Optionally specifies the version of a layer as a single number.
4554 You can use this within
4555 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
4556 for another layer in order to depend on a specific version
4557 of the layer.
4558 This variable is used in the <filename>conf/layer.conf</filename> file
4559 and must be suffixed with the name of the specific layer (e.g.
4560 <filename>LAYERVERSION_mylayer</filename>).</para>
4561 </glossdef>
4562 </glossentry>
4563
4564 <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
4565 <glossdef>
4566 <para>
4567 Specifies the flags to pass to the linker.
4568 This variable is exported to an environment
4569 variable and thus made visible to the software being
4570 built during the compilation step.
4571 </para>
4572
4573 <para>
4574 Default initialization for <filename>LDFLAGS</filename>
4575 varies depending on what is being built:
4576 <itemizedlist>
4577 <listitem><para>
4578 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
4579 when building for the target
4580 </para></listitem>
4581 <listitem><para>
4582 <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
4583 when building for the build host (i.e.
4584 <filename>-native</filename>)
4585 </para></listitem>
4586 <listitem><para>
4587 <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
4588 when building for an SDK (i.e.
4589 <filename>nativesdk-</filename>)
4590 </para></listitem>
4591 </itemizedlist>
4592 </para>
4593 </glossdef>
4594 </glossentry>
4595
4596 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
4597 <glossdef>
4598 <para>
4599 Specifies the lead (or primary) compiled library file
4600 (<filename>.so</filename>) that the
4601 <link linkend='ref-classes-debian'><filename>debian</filename></link>
4602 class applies its naming policy to given a recipe that
4603 packages multiple libraries.
4604 </para>
4605
4606 <para>
4607 This variable works in conjunction with the
4608 <filename>debian</filename> class.
4609 </para>
4610 </glossdef>
4611 </glossentry>
4612
4613 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
4614 <glossdef>
4615 <para>Checksums of the license text in the recipe source code.</para>
4616 <para>This variable tracks changes in license text of the source
4617 code files.
4618 If the license text is changed, it will trigger a build
4619 failure, which gives the developer an opportunity to review any
4620 license change.</para>
4621 <para>
4622 This variable must be defined for all recipes (unless
4623 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
4624 is set to "CLOSED")</para>
4625 <para>For more information, see the
4626 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
4627 Tracking License Changes</link> section</para>
4628 </glossdef>
4629 </glossentry>
4630
4631 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
4632 <glossdef>
4633 <para>
4634 The list of source licenses for the recipe.
4635 Follow these rules:
4636 <itemizedlist>
4637 <listitem><para>Do not use spaces within individual
4638 license names.</para></listitem>
4639 <listitem><para>Separate license names using
4640 | (pipe) when there is a choice between licenses.
4641 </para></listitem>
4642 <listitem><para>Separate license names using
4643 &amp; (ampersand) when multiple licenses exist
4644 that cover different parts of the source.
4645 </para></listitem>
4646 <listitem><para>You can use spaces between license
4647 names.</para></listitem>
4648 <listitem><para>For standard licenses, use the names
4649 of the files in
4650 <filename>meta/files/common-licenses/</filename>
4651 or the
4652 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
4653 flag names defined in
4654 <filename>meta/conf/licenses.conf</filename>.
4655 </para></listitem>
4656 </itemizedlist>
4657 </para>
4658
4659 <para>
4660 Here are some examples:
4661 <literallayout class='monospaced'>
4662 LICENSE = "LGPLv2.1 | GPLv3"
4663 LICENSE = "MPL-1 &amp; LGPLv2.1"
4664 LICENSE = "GPLv2+"
4665 </literallayout>
4666 The first example is from the recipes for Qt, which the user
4667 may choose to distribute under either the LGPL version
4668 2.1 or GPL version 3.
4669 The second example is from Cairo where two licenses cover
4670 different parts of the source code.
4671 The final example is from <filename>sysstat</filename>,
4672 which presents a single license.
4673 </para>
4674
4675 <para>
4676 You can also specify licenses on a per-package basis to
4677 handle situations where components of the output have
4678 different licenses.
4679 For example, a piece of software whose code is
4680 licensed under GPLv2 but has accompanying documentation
4681 licensed under the GNU Free Documentation License 1.2 could
4682 be specified as follows:
4683 <literallayout class='monospaced'>
4684 LICENSE = "GFDL-1.2 &amp; GPLv2"
4685 LICENSE_${PN} = "GPLv2"
4686 LICENSE_${PN}-doc = "GFDL-1.2"
4687 </literallayout>
4688 </para>
4689 </glossdef>
4690 </glossentry>
4691
4692 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
4693 <glossdef>
4694 <para>Path to additional licenses used during the build.
4695 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
4696 to define the directory that holds common license text used during the build.
4697 The <filename>LICENSE_PATH</filename> variable allows you to extend that
4698 location to other areas that have additional licenses:
4699 <literallayout class='monospaced'>
4700 LICENSE_PATH += "/path/to/additional/common/licenses"
4701 </literallayout></para>
4702 </glossdef>
4703 </glossentry>
4704
4705 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
4706 <glossdef>
4707 <para>
4708 Defines the kernel type to be used in assembling the
4709 configuration.
4710 The linux-yocto recipes define "standard", "tiny", and
4711 "preempt-rt" kernel types.
4712 See the
4713 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4714 section in the Yocto Project Linux Kernel Development
4715 Manual for more information on kernel types.
4716 </para>
4717
4718 <para>
4719 If you do not specify a
4720 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
4721 "standard".
4722 Together with
4723 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
4724 the <filename>LINUX_KERNEL_TYPE</filename> variable
4725 defines the search
4726 arguments used by the kernel tools to find the appropriate
4727 description within the kernel
4728 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4729 with which to build out the sources and configuration.
4730 </para>
4731 </glossdef>
4732 </glossentry>
4733
4734 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
4735 <glossdef>
4736 <para>The Linux version from <filename>kernel.org</filename>
4737 on which the Linux kernel image being built using the
4738 OpenEmbedded build system is based.
4739 You define this variable in the kernel recipe.
4740 For example, the <filename>linux-yocto-3.4.bb</filename>
4741 kernel recipe found in
4742 <filename>meta/recipes-kernel/linux</filename>
4743 defines the variables as follows:
4744 <literallayout class='monospaced'>
4745 LINUX_VERSION ?= "3.4.24"
4746 </literallayout>
4747 The <filename>LINUX_VERSION</filename> variable is used to
4748 define <link linkend='var-PV'><filename>PV</filename></link>
4749 for the recipe:
4750 <literallayout class='monospaced'>
4751 PV = "${LINUX_VERSION}+git${SRCPV}"
4752 </literallayout></para>
4753 </glossdef>
4754 </glossentry>
4755
4756 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
4757 <glossdef>
4758 <para>A string extension compiled into the version
4759 string of the Linux kernel built with the OpenEmbedded
4760 build system.
4761 You define this variable in the kernel recipe.
4762 For example, the linux-yocto kernel recipes all define
4763 the variable as follows:
4764 <literallayout class='monospaced'>
4765 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
4766 </literallayout>
4767 Defining this variable essentially sets the
4768 Linux kernel configuration item
4769 <filename>CONFIG_LOCALVERSION</filename>, which is visible
4770 through the <filename>uname</filename> command.
4771 Here is an example that shows the extension assuming it
4772 was set as previously shown:
4773 <literallayout class='monospaced'>
4774 $ uname -r
4775 3.7.0-rc8-custom
4776 </literallayout>
4777 </para>
4778 </glossdef>
4779 </glossentry>
4780
4781 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
4782 <glossdef>
4783 <para>
4784 Specifies the directory to which the OpenEmbedded build
4785 system writes overall log files.
4786 The default directory is <filename>${TMPDIR}/log</filename>.
4787 </para>
4788 <para>
4789 For the directory containing logs specific to each task,
4790 see the <link linkend='var-T'><filename>T</filename></link>
4791 variable.
4792 </para>
4793 </glossdef>
4794 </glossentry>
4795
4796 </glossdiv>
4797
4798 <glossdiv id='var-glossary-m'><title>M</title>
4799
4800 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
4801 <glossdef>
4802 <para>
4803 Specifies the target device for which the image is built.
4804 You define <filename>MACHINE</filename> in the
4805 <filename>local.conf</filename> file found in the
4806 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
4807 By default, <filename>MACHINE</filename> is set to
4808 "qemux86", which is an x86-based architecture machine to
4809 be emulated using QEMU:
4810 <literallayout class='monospaced'>
4811 MACHINE ?= "qemux86"
4812 </literallayout>
4813 The variable corresponds to a machine configuration file of the
4814 same name, through which machine-specific configurations are set.
4815 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
4816 exists the corresponding <filename>qemux86.conf</filename> machine
4817 configuration file, which can be found in the
4818 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4819 in <filename>meta/conf/machine</filename>.
4820 </para>
4821
4822 <para>
4823 The list of machines supported by the Yocto Project as
4824 shipped include the following:
4825 <literallayout class='monospaced'>
4826 MACHINE ?= "qemuarm"
4827 MACHINE ?= "qemumips"
4828 MACHINE ?= "qemuppc"
4829 MACHINE ?= "qemux86"
4830 MACHINE ?= "qemux86-64"
4831 MACHINE ?= "genericx86"
4832 MACHINE ?= "genericx86-64"
4833 MACHINE ?= "beaglebone"
4834 MACHINE ?= "mpc8315e-rdb"
4835 MACHINE ?= "edgerouter"
4836 </literallayout>
4837 The last five are Yocto Project reference hardware boards, which
4838 are provided in the <filename>meta-yocto-bsp</filename> layer.
4839 <note>Adding additional Board Support Package (BSP) layers
4840 to your configuration adds new possible settings for
4841 <filename>MACHINE</filename>.
4842 </note>
4843 </para>
4844 </glossdef>
4845 </glossentry>
4846
4847 <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
4848 <glossdef>
4849 <para>
4850 Specifies the name of the machine-specific architecture.
4851 This variable is set automatically from
4852 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
4853 or
4854 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
4855 You should not hand-edit the
4856 <filename>MACHINE_ARCH</filename> variable.
4857 </para>
4858 </glossdef>
4859 </glossentry>
4860
4861 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
4862 <glossdef>
4863 <para></para>
4864 <para>
4865 A list of required machine-specific packages to install as part of
4866 the image being built.
4867 The build process depends on these packages being present.
4868 Furthermore, because this is a "machine essential" variable, the list of
4869 packages are essential for the machine to boot.
4870 The impact of this variable affects images based on
4871 <filename>packagegroup-core-boot</filename>,
4872 including the <filename>core-image-minimal</filename> image.
4873 </para>
4874 <para>
4875 This variable is similar to the
4876 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
4877 variable with the exception that the image being built has a build
4878 dependency on the variable's list of packages.
4879 In other words, the image will not build if a file in this list is not found.
4880 </para>
4881 <para>
4882 As an example, suppose the machine for which you are building requires
4883 <filename>example-init</filename> to be run during boot to initialize the hardware.
4884 In this case, you would use the following in the machine's
4885 <filename>.conf</filename> configuration file:
4886 <literallayout class='monospaced'>
4887 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4888 </literallayout>
4889 </para>
4890 </glossdef>
4891 </glossentry>
4892
4893 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
4894 <glossdef>
4895 <para></para>
4896 <para>
4897 A list of recommended machine-specific packages to install as part of
4898 the image being built.
4899 The build process does not depend on these packages being present.
4900 However, because this is a "machine essential" variable, the list of
4901 packages are essential for the machine to boot.
4902 The impact of this variable affects images based on
4903 <filename>packagegroup-core-boot</filename>,
4904 including the <filename>core-image-minimal</filename> image.
4905 </para>
4906 <para>
4907 This variable is similar to the
4908 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
4909 variable with the exception that the image being built does not have a build
4910 dependency on the variable's list of packages.
4911 In other words, the image will still build if a package in this list is not found.
4912 Typically, this variable is used to handle essential kernel modules, whose
4913 functionality may be selected to be built into the kernel rather than as a module,
4914 in which case a package will not be produced.
4915 </para>
4916 <para>
4917 Consider an example where you have a custom kernel where a specific touchscreen
4918 driver is required for the machine to be usable.
4919 However, the driver can be built as a module or
4920 into the kernel depending on the kernel configuration.
4921 If the driver is built as a module, you want it to be installed.
4922 But, when the driver is built into the kernel, you still want the
4923 build to succeed.
4924 This variable sets up a "recommends" relationship so that in the latter case,
4925 the build will not fail due to the missing package.
4926 To accomplish this, assuming the package for the module was called
4927 <filename>kernel-module-ab123</filename>, you would use the
4928 following in the machine's <filename>.conf</filename> configuration
4929 file:
4930 <literallayout class='monospaced'>
4931 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4932 </literallayout>
4933 </para>
4934 <para>
4935 Some examples of these machine essentials are flash, screen, keyboard, mouse,
4936 or touchscreen drivers (depending on the machine).
4937 </para>
4938 </glossdef>
4939 </glossentry>
4940
4941 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
4942 <glossdef>
4943 <para>
4944 A list of machine-specific packages to install as part of the
4945 image being built that are not essential for the machine to boot.
4946 However, the build process for more fully-featured images
4947 depends on the packages being present.
4948 </para>
4949 <para>
4950 This variable affects all images based on
4951 <filename>packagegroup-base</filename>, which does not include the
4952 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4953 images.
4954 </para>
4955 <para>
4956 The variable is similar to the
4957 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
4958 variable with the exception that the image being built has a build
4959 dependency on the variable's list of packages.
4960 In other words, the image will not build if a file in this list is not found.
4961 </para>
4962 <para>
4963 An example is a machine that has WiFi capability but is not
4964 essential for the machine to boot the image.
4965 However, if you are building a more fully-featured image, you want to enable
4966 the WiFi.
4967 The package containing the firmware for the WiFi hardware is always
4968 expected to exist, so it is acceptable for the build process to depend upon
4969 finding the package.
4970 In this case, assuming the package for the firmware was called
4971 <filename>wifidriver-firmware</filename>, you would use the following in the
4972 <filename>.conf</filename> file for the machine:
4973 <literallayout class='monospaced'>
4974 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4975 </literallayout>
4976 </para>
4977 </glossdef>
4978 </glossentry>
4979
4980 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
4981 <glossdef>
4982 <para></para>
4983 <para>
4984 A list of machine-specific packages to install as part of the
4985 image being built that are not essential for booting the machine.
4986 The image being built has no build dependency on this list of packages.
4987 </para>
4988 <para>
4989 This variable affects only images based on
4990 <filename>packagegroup-base</filename>, which does not include the
4991 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4992 images.
4993 </para>
4994 <para>
4995 This variable is similar to the
4996 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
4997 variable with the exception that the image being built does not have a build
4998 dependency on the variable's list of packages.
4999 In other words, the image will build if a file in this list is not found.
5000 </para>
5001 <para>
5002 An example is a machine that has WiFi capability but is not essential
5003 For the machine to boot the image.
5004 However, if you are building a more fully-featured image, you want to enable
5005 WiFi.
5006 In this case, the package containing the WiFi kernel module will not be produced
5007 if the WiFi driver is built into the kernel, in which case you still want the
5008 build to succeed instead of failing as a result of the package not being found.
5009 To accomplish this, assuming the package for the module was called
5010 <filename>kernel-module-examplewifi</filename>, you would use the
5011 following in the <filename>.conf</filename> file for the machine:
5012 <literallayout class='monospaced'>
5013 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
5014 </literallayout>
5015 </para>
5016 </glossdef>
5017 </glossentry>
5018
5019 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
5020 <glossdef>
5021 <para>
5022 Specifies the list of hardware features the
5023 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
5024 of supporting.
5025 For related information on enabling features, see the
5026 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
5027 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
5028 and
5029 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
5030 variables.
5031 </para>
5032
5033 <para>
5034 For a list of hardware features supported by the Yocto
5035 Project as shipped, see the
5036 "<link linkend='ref-features-machine'>Machine Features</link>"
5037 section.
5038 </para>
5039 </glossdef>
5040 </glossentry>
5041
5042 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
5043 <glossdef>
5044 <para>Features to be added to
5045 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
5046 if not also present in
5047 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
5048 </para>
5049
5050 <para>
5051 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
5052 It is not intended to be user-configurable.
5053 It is best to just reference the variable to see which machine features are
5054 being backfilled for all machine configurations.
5055 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
5056 more information.
5057 </para>
5058 </glossdef>
5059 </glossentry>
5060
5061 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
5062 <glossdef>
5063 <para>Features from
5064 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
5065 that should not be backfilled (i.e. added to
5066 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
5067 during the build.
5068 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
5069 more information.
5070 </para>
5071 </glossdef>
5072 </glossentry>
5073
5074 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
5075 <glossdef>
5076 <para>
5077 Lists overrides specific to the current machine.
5078 By default, this list includes the value
5079 of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
5080 You can extend the list to apply variable overrides for
5081 classes of machines.
5082 For example, all QEMU emulated machines (e.g. qemuarm,
5083 qemux86, and so forth) include a common file named
5084 <filename>meta/conf/machine/include/qemu.inc</filename>
5085 that prepends <filename>MACHINEOVERRIDES</filename> with
5086 the following variable override:
5087 <literallayout class='monospaced'>
5088 MACHINEOVERRIDES =. "qemuall:"
5089 </literallayout>
5090 Applying an override like <filename>qemuall</filename>
5091 affects all QEMU emulated machines elsewhere.
5092 Here is an example from the
5093 <filename>connman-conf</filename> recipe:
5094 <literallayout class='monospaced'>
5095 SRC_URI_append_qemuall = "file://wired.config \
5096 file://wired-setup \
5097 "
5098 </literallayout>
5099 </para>
5100 </glossdef>
5101 </glossentry>
5102
5103 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
5104 <glossdef>
5105 <para>The email address of the distribution maintainer.</para>
5106 </glossdef>
5107 </glossentry>
5108
5109 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
5110 <glossdef>
5111 <para>
5112 Specifies additional paths from which the OpenEmbedded
5113 build system gets source code.
5114 When the build system searches for source code, it first
5115 tries the local download directory.
5116 If that location fails, the build system tries locations
5117 defined by
5118 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
5119 the upstream source, and then locations specified by
5120 <filename>MIRRORS</filename> in that order.
5121 </para>
5122
5123 <para>
5124 Assuming your distribution
5125 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
5126 is "poky", the default value for
5127 <filename>MIRRORS</filename> is defined in the
5128 <filename>conf/distro/poky.conf</filename> file in the
5129 <filename>meta-yocto</filename> Git repository.
5130 </para>
5131 </glossdef>
5132 </glossentry>
5133
5134 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
5135 <glossdef>
5136 <para>
5137 Specifies a prefix has been added to
5138 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
5139 of a recipe or package, such as a Multilib version.
5140 The variable is used in places where the prefix needs to be
5141 added to or removed from a the name (e.g. the
5142 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
5143 <filename>MLPREFIX</filename> gets set when a prefix has been
5144 added to <filename>PN</filename>.
5145 </para>
5146 </glossdef>
5147 </glossentry>
5148
5149 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
5150 <glossdef>
5151 <para>
5152 Lists kernel modules that need to be auto-loaded during
5153 boot.
5154 </para>
5155
5156 <para>
5157 You can use this variable anywhere that it can be
5158 recognized by the kernel recipe or out-of-tree kernel
5159 module recipe (e.g. a machine configuration file, a
5160 distribution configuration file, an append file for the
5161 recipe, or the recipe itself).
5162 </para>
5163
5164 <para>
5165 Specify it as follows:
5166 <literallayout class='monospaced'>
5167 module_autoload_&lt;modname&gt; = "modname1 modname2 modname3"
5168 </literallayout>
5169 You must use the kernel module name override.
5170 </para>
5171
5172 <para>
5173 Including <filename>module_autoload</filename> causes the
5174 OpenEmbedded build system to populate the
5175 <filename>/etc/modules-load.d/modname.conf</filename>
5176 file with the list of modules to be auto-loaded on boot.
5177 The modules appear one-per-line in the file.
5178 Here is an example of the most common use case:
5179 <literallayout class='monospaced'>
5180 module_autoload_modname = "modname"
5181 </literallayout>
5182 </para>
5183
5184 <para>
5185 For information on how to populate the
5186 <filename>modname.conf</filename> file with
5187 <filename>modprobe.d</filename> syntax lines, see the
5188 <link linkend='var-module_conf'><filename>module_conf</filename></link>
5189 variable.
5190 </para>
5191 </glossdef>
5192 </glossentry>
5193
5194 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
5195 <glossdef>
5196 <para>
5197 Specifies <filename>modprobe.d</filename> syntax lines
5198 for inclusion in the
5199 <filename>/etc/modprobe.d/modname.conf</filename> file.
5200 </para>
5201
5202 <para>
5203 You can use this variable anywhere that it can be
5204 recognized by the kernel recipe or out-of-tree kernel
5205 module recipe (e.g. a machine configuration file, a
5206 distribution configuration file, an append file for the
5207 recipe, or the recipe itself).
5208 </para>
5209
5210 <para>
5211 Here is the general syntax:
5212 <literallayout class='monospaced'>
5213 module_conf_&lt;modname&gt; = "modprobe.d-syntax"
5214 </literallayout>
5215 You must use the kernel module name override.
5216 </para>
5217
5218 <para>
5219 Run <filename>man modprobe.d</filename> in the shell to
5220 find out more information on the exact syntax for lines
5221 you want to provide with <filename>module_conf</filename>.
5222 </para>
5223
5224 <para>
5225 Including <filename>module_conf</filename> causes the
5226 OpenEmbedded build system to populate the
5227 <filename>/etc/modprobe.d/modname.conf</filename>
5228 file with <filename>modprobe.d</filename> syntax lines.
5229 Here is an example:
5230 <literallayout class='monospaced'>
5231 module_conf_&lt;modname&gt; = "options modname arg1=val1 arg2=val2"
5232 </literallayout>
5233 </para>
5234
5235 <para>
5236 For information on how to specify kernel modules to
5237 auto-load on boot, see the
5238 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
5239 variable.
5240 </para>
5241 </glossdef>
5242 </glossentry>
5243
5244 <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm>
5245 <glossdef>
5246 <para>
5247 The base name of the kernel modules tarball.
5248 This variable is set in the
5249 <link linkend='ref-classes-kernel'>kernel</link> class
5250 as follows:
5251 <literallayout class='monospaced'>
5252 MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
5253 </literallayout>
5254 See the
5255 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
5256 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
5257 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
5258 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
5259 and
5260 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
5261 variables for additional information.
5262 </para>
5263 </glossdef>
5264 </glossentry>
5265
5266 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
5267 <glossdef>
5268 <para>
5269 Controls creation of the <filename>modules-*.tgz</filename>
5270 file.
5271 Set this variable to "0" to disable creation of this
5272 file, which contains all of the kernel modules resulting
5273 from a kernel build.
5274 </para>
5275 </glossdef>
5276 </glossentry>
5277
5278 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
5279 <glossdef>
5280 <para>
5281 Separates files for different machines such that you can build
5282 for multiple target machines using the same output directories.
5283 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
5284 for an example.
5285 </para>
5286 </glossdef>
5287 </glossentry>
5288
5289 </glossdiv>
5290
5291 <glossdiv id='var-glossary-n'><title>N</title>
5292
5293 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
5294 <glossdef>
5295 <para>
5296 A string identifying the host distribution.
5297 Strings consist of the host distributor ID
5298 followed by the release, as reported by the
5299 <filename>lsb_release</filename> tool
5300 or as read from <filename>/etc/lsb-release</filename>.
5301 For example, when running a build on Ubuntu 12.10, the value
5302 is "Ubuntu-12.10".
5303 If this information is unable to be determined, the value
5304 resolves to "Unknown".
5305 </para>
5306 <para>
5307 This variable is used by default to isolate native shared
5308 state packages for different distributions (e.g. to avoid
5309 problems with <filename>glibc</filename> version
5310 incompatibilities).
5311 Additionally, the variable is checked against
5312 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
5313 if that variable is set.
5314 </para>
5315 </glossdef>
5316 </glossentry>
5317
5318 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
5319 <glossdef>
5320 <para>
5321 Prevents installation of all "recommended-only" packages.
5322 Recommended-only packages are packages installed only
5323 through the
5324 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
5325 variable).
5326 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
5327 to "1" turns this feature on:
5328 <literallayout class='monospaced'>
5329 NO_RECOMMENDATIONS = "1"
5330 </literallayout>
5331 You can set this variable globally in your
5332 <filename>local.conf</filename> file or you can attach it to
5333 a specific image recipe by using the recipe name override:
5334 <literallayout class='monospaced'>
5335 NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
5336 </literallayout>
5337 </para>
5338
5339 <para>
5340 It is important to realize that if you choose to not install
5341 packages using this variable and some other packages are
5342 dependent on them (i.e. listed in a recipe's
5343 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5344 variable), the OpenEmbedded build system ignores your
5345 request and will install the packages to avoid dependency
5346 errors.
5347 <note>
5348 Some recommended packages might be required for certain
5349 system functionality, such as kernel modules.
5350 It is up to you to add packages with the
5351 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
5352 variable.
5353 </note>
5354 </para>
5355
5356 <para>
5357 Support for this variable exists only when using the
5358 IPK and RPM packaging backend.
5359 Support does not exist for DEB.
5360 </para>
5361
5362 <para>
5363 See the
5364 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
5365 and the
5366 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
5367 variables for related information.
5368 </para>
5369 </glossdef>
5370 </glossentry>
5371
5372 <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm>
5373 <glossdef>
5374 <para>
5375 Causes the OpenEmbedded build system to skip building the
5376 <filename>.hddimg</filename> image.
5377 The <filename>NOHDD</filename> variable is used with the
5378 <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link>
5379 class.
5380 Set the variable to "1" to prevent the
5381 <filename>.hddimg</filename> image from being built.
5382 </para>
5383 </glossdef>
5384 </glossentry>
5385
5386 <glossentry id='var-NOISO'><glossterm>NOISO</glossterm>
5387 <glossdef>
5388 <para>
5389 Causes the OpenEmbedded build system to skip building the
5390 ISO image.
5391 The <filename>NOISO</filename> variable is used with the
5392 <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link>
5393 class.
5394 Set the variable to "1" to prevent the ISO image from
5395 being built.
5396 To enable building an ISO image, set the variable to "0".
5397 </para>
5398 </glossdef>
5399 </glossentry>
5400
5401 </glossdiv>
5402
5403 <glossdiv id='var-glossary-o'><title>O</title>
5404
5405 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
5406 <glossdef>
5407 <para>
5408 When a recipe inherits the
5409 <filename>binconfig.bbclass</filename> class, this variable
5410 specifies additional arguments passed to the "sed" command.
5411 The sed command alters any paths in configuration scripts
5412 that have been set up during compilation.
5413 Inheriting this class results in all paths in these scripts
5414 being changed to point into the
5415 <filename>sysroots/</filename> directory so that all builds
5416 that use the script will use the correct directories
5417 for the cross compiling layout.
5418 </para>
5419
5420 <para>
5421 See the <filename>meta/classes/binconfig.bbclass</filename>
5422 in the
5423 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
5424 for details on how this class applies these additional
5425 sed command arguments.
5426 For general information on the
5427 <filename>binconfig.bbclass</filename> class, see the
5428 "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
5429 section.
5430 </para>
5431 </glossdef>
5432 </glossentry>
5433
5434 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
5435 <glossdef>
5436 <para>
5437 An internal variable used to tell the OpenEmbedded build
5438 system what Python modules to import for every Python
5439 function run by the system.
5440 </para>
5441
5442 <note>
5443 Do not set this variable.
5444 It is for internal use only.
5445 </note>
5446 </glossdef>
5447 </glossentry>
5448
5449 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
5450 <glossdef>
5451 <para>
5452 Controls how the OpenEmbedded build system spawns
5453 interactive terminals on the host development system
5454 (e.g. using the BitBake command with the
5455 <filename>-c devshell</filename> command-line option).
5456 For more information, see the
5457 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
5458 in the Yocto Project Development Manual.
5459 </para>
5460
5461 <para>
5462 You can use the following values for the
5463 <filename>OE_TERMINAL</filename> variable:
5464 <literallayout class='monospaced'>
5465 auto
5466 gnome
5467 xfce
5468 rxvt
5469 screen
5470 konsole
5471 none
5472 </literallayout>
5473 <note>Konsole support only works for KDE 3.x.
5474 Also, "auto" is the default behavior for
5475 <filename>OE_TERMINAL</filename></note>
5476 </para>
5477 </glossdef>
5478 </glossentry>
5479
5480 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
5481 <glossdef>
5482 <para>
5483 The directory from which the top-level build environment
5484 setup script is sourced.
5485 The Yocto Project makes two top-level build environment
5486 setup scripts available:
5487 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
5488 and
5489 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
5490 When you run one of these scripts, the
5491 <filename>OEROOT</filename> variable resolves to the
5492 directory that contains the script.
5493 </para>
5494
5495 <para>
5496 For additional information on how this variable is used,
5497 see the initialization scripts.
5498 </para>
5499 </glossdef>
5500 </glossentry>
5501
5502 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
5503 <glossdef>
5504 <para>
5505 Declares the oldest version of the Linux kernel that the
5506 produced binaries must support.
5507 This variable is passed into the build of the Embedded
5508 GNU C Library (<filename>eglibc</filename>).
5509 </para>
5510
5511 <para>
5512 The default for this variable comes from the
5513 <filename>meta/conf/bitbake.conf</filename> configuration
5514 file.
5515 You can override this default by setting the variable
5516 in a custom distribution configuration file.
5517 </para>
5518 </glossdef>
5519 </glossentry>
5520
5521 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
5522 <glossdef>
5523 <para>
5524 BitBake uses <filename>OVERRIDES</filename> to control
5525 what variables are overridden after BitBake parses
5526 recipes and configuration files.
5527 You can find more information on how overrides are handled
5528 in the BitBake Manual that is located at
5529 <filename>bitbake/doc/manual</filename> in the
5530 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5531 </para>
5532 </glossdef>
5533 </glossentry>
5534 </glossdiv>
5535
5536 <glossdiv id='var-glossary-p'><title>P</title>
5537
5538 <glossentry id='var-P'><glossterm>P</glossterm>
5539 <glossdef>
5540 <para>The recipe name and version.
5541 <filename>P</filename> is comprised of the following:
5542 <literallayout class='monospaced'>
5543 ${PN}-${PV}
5544 </literallayout></para>
5545 </glossdef>
5546 </glossentry>
5547
5548 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
5549 <glossdef>
5550 <para>
5551 The architecture of the resulting package or packages.
5552 </para>
5553
5554 <para>
5555 By default, the value of this variable is set to
5556 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
5557 when building for the target,
5558 <filename>BUILD_ARCH</filename> when building for the
5559 build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
5560 for the SDK.
5561 However, if your recipe's output packages are built
5562 specific to the target machine rather than general for
5563 the architecture of the machine, you should set
5564 <filename>PACKAGE_ARCH</filename> to the value of
5565 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
5566 in the recipe as follows:
5567 <literallayout class='monospaced'>
5568 PACKAGE_ARCH = "${MACHINE_ARCH}"
5569 </literallayout>
5570 </para>
5571 </glossdef>
5572 </glossentry>
5573
5574 <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
5575 <glossdef>
5576 <para>
5577 Specifies a list of architectures compatible with
5578 the target machine.
5579 This variable is set automatically and should not
5580 normally be hand-edited.
5581 Entries are separated using spaces and listed in order
5582 of priority.
5583 The default value for
5584 <filename>PACKAGE_ARCHS</filename> is "all any noarch
5585 ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
5586 </para>
5587 </glossdef>
5588 </glossentry>
5589
5590
5591
5592 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
5593 <glossdef>
5594 <para>Enables easily adding packages to
5595 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
5596 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
5597 so that those added packages can pick up files that would normally be
5598 included in the default package.</para>
5599 </glossdef>
5600 </glossentry>
5601
5602 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
5603 <glossdef>
5604 <para>
5605 This variable, which is set in the
5606 <filename>local.conf</filename> configuration file found in
5607 the <filename>conf</filename> folder of the
5608 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
5609 specifies the package manager the OpenEmbedded build system
5610 uses when packaging data.
5611 </para>
5612
5613 <para>
5614 You can provide one or more of the following arguments for
5615 the variable:
5616 <literallayout class='monospaced'>
5617 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
5618 </literallayout>
5619 The build system uses only the first argument in the list
5620 as the package manager when creating your image or SDK.
5621 However, packages will be created using any additional
5622 packaging classes you specify.
5623 For example, if you use the following in your
5624 <filename>local.conf</filename> file:
5625 <literallayout class='monospaced'>
5626 PACKAGE_CLASSES ?= "package_ipk package_tar"
5627 </literallayout>
5628 The OpenEmbedded build system uses the IPK package manager
5629 to create your image or SDK as well as generating
5630 TAR packages.
5631 </para>
5632
5633 <para>
5634 You cannot specify the
5635 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
5636 class first in the list.
5637 Files using the <filename>.tar</filename> format cannot
5638 be used as a substitute packaging format
5639 for DEB, RPM, and IPK formatted files for your image or SDK.
5640 </para>
5641
5642 <para>
5643 For information on packaging and build performance effects
5644 as a result of the package manager in use, see the
5645 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
5646 section.
5647 </para>
5648 </glossdef>
5649 </glossentry>
5650
5651 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
5652 <glossdef>
5653 <para>
5654 Lists packages that should not be installed into an image.
5655 For example:
5656 <literallayout class='monospaced'>
5657 PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
5658 </literallayout>
5659 You can set this variable globally in your
5660 <filename>local.conf</filename> file or you can attach it to
5661 a specific image recipe by using the recipe name override:
5662 <literallayout class='monospaced'>
5663 PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
5664 </literallayout>
5665 </para>
5666
5667 <para>
5668 If you choose to not install
5669 a package using this variable and some other package is
5670 dependent on it (i.e. listed in a recipe's
5671 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5672 variable), the OpenEmbedded build system generates a fatal
5673 installation error.
5674 Because the build system halts the process with a fatal
5675 error, you can use the variable with an iterative
5676 development process to remove specific components from a
5677 system.
5678 </para>
5679
5680 <para>
5681 Support for this variable exists only when using the
5682 IPK and RPM packaging backend.
5683 Support does not exist for DEB.
5684 </para>
5685
5686 <para>
5687 See the
5688 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
5689 and the
5690 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
5691 variables for related information.
5692 </para>
5693 </glossdef>
5694 </glossentry>
5695
5696 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
5697 <glossdef>
5698 <para>Specifies the list of architectures compatible with the device CPU.
5699 This variable is useful when you build for several different devices that use
5700 miscellaneous processors such as XScale and ARM926-EJS).</para>
5701 </glossdef>
5702 </glossentry>
5703
5704 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
5705 <glossdef>
5706
5707 <para>
5708 The <filename>PACKAGE_GROUP</filename> variable has been
5709 renamed to
5710 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
5711 See the variable description for
5712 <filename>FEATURE_PACKAGES</filename> for information.
5713 </para>
5714
5715 <para>
5716 If if you use the <filename>PACKAGE_GROUP</filename>
5717 variable, the OpenEmbedded build system issues a warning
5718 message.
5719 </para>
5720 </glossdef>
5721 </glossentry>
5722
5723 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
5724 <glossdef>
5725 <para>
5726 The final list of packages passed to the package manager
5727 for installation into the image.
5728 </para>
5729
5730 <para>
5731 Because the package manager controls actual installation
5732 of all packages, the list of packages passed using
5733 <filename>PACKAGE_INSTALL</filename> is not the final list
5734 of packages that are actually installed.
5735 This variable is internal to the image construction
5736 code.
5737 Consequently, in general, you should use the
5738 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
5739 variable to specify packages for installation.
5740 The exception to this is when working with
5741 the
5742 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5743 image.
5744 When working with an initial RAM disk (initramfs)
5745 image, use the <filename>PACKAGE_INSTALL</filename>
5746 variable.
5747 </para>
5748 </glossdef>
5749 </glossentry>
5750
5751 <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
5752 <glossdef>
5753 <para>
5754 Specifies a list of functions run to pre-process the
5755 <link linkend='var-PKGD'><filename>PKGD</filename></link>
5756 directory prior to splitting the files out to individual
5757 packages.
5758 </para>
5759 </glossdef>
5760 </glossentry>
5761
5762 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
5763 <glossdef>
5764 <para>
5765 This variable provides a means of enabling or disabling
5766 features of a recipe on a per-recipe basis.
5767 <filename>PACKAGECONFIG</filename> blocks are defined
5768 in recipes when you specify features and then arguments
5769 that define feature behaviors.
5770 Here is the basic block structure:
5771 <literallayout class='monospaced'>
5772 PACKAGECONFIG ??= "f1 f2 f3 ..."
5773 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
5774 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
5775 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
5776 </literallayout>
5777 The <filename>PACKAGECONFIG</filename>
5778 variable itself specifies a space-separated list of the
5779 features to enable.
5780 Following the features, you can determine the behavior of
5781 each feature by providing up to four order-dependent
5782 arguments, which are separated by commas.
5783 You can omit any argument you like but must retain the
5784 separating commas.
5785 The order is important and specifies the following:
5786 <orderedlist>
5787 <listitem><para>Extra arguments
5788 that should be added to the configure script
5789 argument list
5790 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
5791 if the feature is enabled.</para></listitem>
5792 <listitem><para>Extra arguments
5793 that should be added to <filename>EXTRA_OECONF</filename>
5794 if the feature is disabled.
5795 </para></listitem>
5796 <listitem><para>Additional build dependencies
5797 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
5798 that should be added if the feature is enabled.
5799 </para></listitem>
5800 <listitem><para>Additional runtime dependencies
5801 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5802 that should be added if the feature is enabled.
5803 </para></listitem>
5804 </orderedlist>
5805 </para>
5806
5807 <para>
5808 Consider the following
5809 <filename>PACKAGECONFIG</filename> block taken from the
5810 <filename>librsvg</filename> recipe.
5811 In this example the feature is <filename>croco</filename>,
5812 which has three arguments that determine the feature's
5813 behavior.
5814 <literallayout class='monospaced'>
5815 PACKAGECONFIG ??= "croco"
5816 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
5817 </literallayout>
5818 The <filename>--with-croco</filename> and
5819 <filename>libcroco</filename> arguments apply only if
5820 the feature is enabled.
5821 In this case, <filename>--with-croco</filename> is
5822 added to the configure script argument list and
5823 <filename>libcroco</filename> is added to
5824 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
5825 On the other hand, if the feature is disabled say through
5826 a <filename>.bbappend</filename> file in another layer, then
5827 the second argument <filename>--without-croco</filename> is
5828 added to the configure script rather than
5829 <filename>--with-croco</filename>.
5830 </para>
5831
5832 <para>
5833 The basic <filename>PACKAGECONFIG</filename> structure
5834 previously described holds true regardless of whether you
5835 are creating a block or changing a block.
5836 When creating a block, use the structure inside your
5837 recipe.
5838 </para>
5839
5840 <para>
5841 If you want to change an existing
5842 <filename>PACKAGECONFIG</filename> block, you can do so
5843 one of two ways:
5844 <itemizedlist>
5845 <listitem><para><emphasis>Append file:</emphasis>
5846 Create an append file named
5847 <filename>&lt;recipename&gt;.bbappend</filename> in your
5848 layer and override the value of
5849 <filename>PACKAGECONFIG</filename>.
5850 You can either completely override the variable:
5851 <literallayout class='monospaced'>
5852 PACKAGECONFIG="f4 f5"
5853 </literallayout>
5854 Or, you can just append the variable:
5855 <literallayout class='monospaced'>
5856 PACKAGECONFIG_append = " f4"
5857 </literallayout></para></listitem>
5858 <listitem><para><emphasis>Configuration file:</emphasis>
5859 This method is identical to changing the block
5860 through an append file except you edit your
5861 <filename>local.conf</filename> or
5862 <filename>&lt;mydistro&gt;.conf</filename> file.
5863 As with append files previously described,
5864 you can either completely override the variable:
5865 <literallayout class='monospaced'>
5866 PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
5867 </literallayout>
5868 Or, you can just amend the variable:
5869 <literallayout class='monospaced'>
5870 PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
5871 </literallayout></para></listitem>
5872 </itemizedlist>
5873 </para>
5874 </glossdef>
5875 </glossentry>
5876
5877 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
5878 <glossdef>
5879 <para>The list of packages to be created from the recipe.
5880 The default value is the following:
5881 <literallayout class='monospaced'>
5882 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
5883 </literallayout></para>
5884 </glossdef>
5885 </glossentry>
5886
5887 <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
5888 <glossdef>
5889 <para>
5890 Specifies a list of functions run to perform additional
5891 splitting of files into individual packages.
5892 Recipes can either prepend to this variable or prepend
5893 to the <filename>populate_packages</filename> function
5894 in order to perform additional package splitting.
5895 In either case, the function should set
5896 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
5897 <link linkend='var-FILES'><filename>FILES</filename></link>,
5898 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5899 and other packaging variables appropriately in order to
5900 perform the desired splitting.
5901 </para>
5902 </glossdef>
5903 </glossentry>
5904
5905 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
5906 <glossdef>
5907 <para>
5908 A promise that your recipe satisfies runtime dependencies
5909 for optional modules that are found in other recipes.
5910 <filename>PACKAGES_DYNAMIC</filename>
5911 does not actually satisfy the dependencies, it only states that
5912 they should be satisfied.
5913 For example, if a hard, runtime dependency
5914 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5915 of another package is satisfied
5916 at build time through the <filename>PACKAGES_DYNAMIC</filename>
5917 variable, but a package with the module name is never actually
5918 produced, then the other package will be broken.
5919 Thus, if you attempt to include that package in an image,
5920 you will get a dependency failure from the packaging system
5921 during the
5922 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
5923 task.
5924 </para>
5925 <para>
5926 Typically, if there is a chance that such a situation can
5927 occur and the package that is not created is valid
5928 without the dependency being satisfied, then you should use
5929 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
5930 (a soft runtime dependency) instead of
5931 <filename>RDEPENDS</filename>.
5932 </para>
5933
5934 <para>
5935 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
5936 variable when you are splitting packages, see the
5937 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
5938 in the Yocto Project Development Manual.
5939 </para>
5940 </glossdef>
5941 </glossentry>
5942
5943 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
5944 <glossdef>
5945 <para>
5946 Extra options passed to the <filename>make</filename>
5947 command during the
5948 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
5949 task in order to specify parallel compilation on the local
5950 build host.
5951 This variable is usually in the form "-j &lt;x&gt;",
5952 where x represents the maximum number of parallel threads
5953 <filename>make</filename> can run.
5954 </para>
5955
5956 <para>
5957 If your development host supports multiple cores, a good
5958 rule of thumb is to set this variable to twice the number
5959 of cores on the host.
5960 If you do not set <filename>PARALLEL_MAKE</filename>, it
5961 defaults to the number of cores your build system has.
5962 <note>
5963 Individual recipes might clear out this variable if
5964 the software being built has problems running its
5965 <filename>make</filename> process in parallel.
5966 </note>
5967 </para>
5968 </glossdef>
5969 </glossentry>
5970
5971 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
5972 <glossdef>
5973 <para>
5974 Extra options passed to the
5975 <filename>make install</filename> command during the
5976 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
5977 task in order to specify parallel installation.
5978 This variable defaults to the value of
5979 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
5980 <note>
5981 Individual recipes might clear out this variable if
5982 the software being built has problems running its
5983 <filename>make install</filename> process in parallel.
5984 </note>
5985 </para>
5986 </glossdef>
5987 </glossentry>
5988
5989 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
5990 <glossdef>
5991 <para>
5992 Determines the action to take when a patch fails.
5993 You can set this variable to one of two values: "noop" and
5994 "user".
5995 </para>
5996
5997 <para>
5998 The default value of "noop" causes the build to simply fail
5999 when the OpenEmbedded build system cannot successfully
6000 apply a patch.
6001 Setting the value to "user" causes the build system to
6002 launch a shell and places you in the right location so that
6003 you can manually resolve the conflicts.
6004 </para>
6005
6006 <para>
6007 Set this variable in your
6008 <filename>local.conf</filename> file.
6009 </para>
6010 </glossdef>
6011 </glossentry>
6012
6013 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
6014 <glossdef>
6015 <para>
6016 Specifies the utility used to apply patches for a recipe
6017 during the
6018 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
6019 task.
6020 You can specify one of three utilities: "patch", "quilt", or
6021 "git".
6022 The default utility used is "quilt" except for the
6023 quilt-native recipe itself.
6024 Because the quilt tool is not available at the
6025 time quilt-native is being patched, it uses "patch".
6026 </para>
6027
6028 <para>
6029 If you wish to use an alternative patching tool, set the
6030 variable in the recipe using one of the following:
6031 <literallayout class='monospaced'>
6032 PATCHTOOL = "patch"
6033 PATCHTOOL = "quilt"
6034 PATCHTOOL = "git"
6035 </literallayout>
6036 </para>
6037 </glossdef>
6038 </glossentry>
6039
6040 <glossentry id='var-PE'><glossterm>PE</glossterm>
6041 <glossdef>
6042 <para>
6043 The epoch of the recipe.
6044 By default, this variable is unset.
6045 The variable is used to make upgrades possible when the
6046 versioning scheme changes in some backwards incompatible
6047 way.
6048 </para>
6049 </glossdef>
6050 </glossentry>
6051
6052 <glossentry id='var-PF'><glossterm>PF</glossterm>
6053 <glossdef>
6054 <para>Specifies the recipe or package name and includes all version and revision
6055 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
6056 <filename>bash-4.2-r1/</filename>).
6057 This variable is comprised of the following:
6058 <literallayout class='monospaced'>
6059 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
6060 </literallayout></para>
6061 </glossdef>
6062 </glossentry>
6063
6064 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
6065 <glossdef>
6066 <para>
6067 When a recipe inherits the
6068 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
6069 class, this variable identifies packages that contain
6070 the pixbuf loaders used with
6071 <filename>gdk-pixbuf</filename>.
6072 By default, the <filename>pixbufcache</filename> class
6073 assumes that the loaders are in the recipe's main package
6074 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
6075 Use this variable if the loaders you need are in a package
6076 other than that main package.
6077 </para>
6078 </glossdef>
6079 </glossentry>
6080
6081 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
6082 <glossdef>
6083 <para>
6084 The name of the resulting package created by the
6085 OpenEmbedded build system.
6086 <note>
6087 When using the <filename>PKG</filename> variable, you
6088 must use a package name override.
6089 </note>
6090 For example, when the
6091 <link linkend='ref-classes-debian'><filename>debian</filename></link>
6092 class renames the output package, it does so by setting
6093 <filename>PKG_&lt;packagename&gt;</filename>.
6094 </para>
6095 </glossdef>
6096 </glossentry>
6097
6098 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
6099 <glossdef>
6100 <para>
6101 Points to the destination directory for files to be
6102 packaged before they are split into individual packages.
6103 This directory defaults to the following:
6104 <literallayout class='monospaced'>
6105 ${WORKDIR}/package
6106 </literallayout>
6107 Do not change this default.
6108 </para>
6109 </glossdef>
6110 </glossentry>
6111
6112 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
6113 <glossdef>
6114 <para>
6115 Points to a shared, global-state directory that holds data
6116 generated during the packaging process.
6117 During the packaging process, the
6118 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
6119 task packages data for each recipe and installs it into
6120 this temporary, shared area.
6121 This directory defaults to the following:
6122 <literallayout class='monospaced'>
6123 ${STAGING_DIR_HOST}/pkgdata
6124 </literallayout>
6125 Do not change this default.
6126 </para>
6127 </glossdef>
6128 </glossentry>
6129
6130 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
6131 <glossdef>
6132 <para>
6133 Points to the parent directory for files to be packaged
6134 after they have been split into individual packages.
6135 This directory defaults to the following:
6136 <literallayout class='monospaced'>
6137 ${WORKDIR}/packages-split
6138 </literallayout>
6139 Under this directory, the build system creates
6140 directories for each package specified in
6141 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
6142 Do not change this default.
6143 </para>
6144 </glossdef>
6145 </glossentry>
6146
6147 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
6148 <glossdef>
6149 <para>
6150 Points to a temporary work area used by the
6151 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
6152 task to write output from the
6153 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
6154 task.
6155 The <filename>PKGDESTWORK</filename> location defaults to
6156 the following:
6157 <literallayout class='monospaced'>
6158 ${WORKDIR}/pkgdata
6159 </literallayout>
6160 The <filename>do_packagedata</filename> task then packages
6161 the data in the temporary work area and installs it into a
6162 shared directory pointed to by
6163 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
6164 </para>
6165
6166 <para>
6167 Do not change this default.
6168 </para>
6169 </glossdef>
6170 </glossentry>
6171
6172 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
6173 <glossdef>
6174 <para>
6175 The epoch of the output package built by the
6176 OpenEmbedded build system.
6177 By default, <filename>PKGE</filename> is set to
6178 <link linkend='var-PE'><filename>PE</filename></link>.
6179 </para>
6180 </glossdef>
6181 </glossentry>
6182
6183 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
6184 <glossdef>
6185 <para>
6186 The revision of the output package built by the
6187 OpenEmbedded build system.
6188 By default, <filename>PKGR</filename> is set to
6189 <link linkend='var-PR'><filename>PR</filename></link>.
6190 </para>
6191 </glossdef>
6192 </glossentry>
6193
6194 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
6195 <glossdef>
6196 <para>
6197 The version of the output package built by the
6198 OpenEmbedded build system.
6199 By default, <filename>PKGV</filename> is set to
6200 <link linkend='var-PV'><filename>PV</filename></link>.
6201 </para>
6202 </glossdef>
6203 </glossentry>
6204
6205 <glossentry id='var-PN'><glossterm>PN</glossterm>
6206 <glossdef>
6207 <para>This variable can have two separate functions depending on the context: a recipe
6208 name or a resulting package name.</para>
6209 <para><filename>PN</filename> refers to a recipe name in the context of a file used
6210 by the OpenEmbedded build system as input to create a package.
6211 The name is normally extracted from the recipe file name.
6212 For example, if the recipe is named
6213 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
6214 will be "expat".</para>
6215 <para>
6216 The variable refers to a package name in the context of a file created or produced by the
6217 OpenEmbedded build system.</para>
6218 <para>If applicable, the <filename>PN</filename> variable also contains any special
6219 suffix or prefix.
6220 For example, using <filename>bash</filename> to build packages for the native
6221 machine, <filename>PN</filename> is <filename>bash-native</filename>.
6222 Using <filename>bash</filename> to build packages for the target and for Multilib,
6223 <filename>PN</filename> would be <filename>bash</filename> and
6224 <filename>lib64-bash</filename>, respectively.
6225 </para>
6226 </glossdef>
6227 </glossentry>
6228
6229 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
6230 <glossdef>
6231 <para>
6232 Lists recipes you do not want the OpenEmbedded build system
6233 to build.
6234 This variable works in conjunction with the
6235 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
6236 class, which the recipe must inherit globally.
6237 </para>
6238
6239 <para>
6240 To prevent a recipe from being built, inherit the class
6241 globally and use the variable in your
6242 <filename>local.conf</filename> file.
6243 Here is an example that prevents
6244 <filename>myrecipe</filename> from being built:
6245 <literallayout class='monospaced'>
6246 INHERIT += "blacklist"
6247 PNBLACKLIST[myrecipe] = "Not supported by our organization."
6248 </literallayout>
6249 </para>
6250 </glossdef>
6251 </glossentry>
6252
6253 <glossentry id='var-PR'><glossterm>PR</glossterm>
6254 <glossdef>
6255 <para>
6256 The revision of the recipe.
6257 The default value for this variable is "r0".
6258 </para>
6259 </glossdef>
6260 </glossentry>
6261
6262 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
6263 <glossdef>
6264 <para>
6265 If multiple recipes provide an item, this variable
6266 determines which recipe should be given preference.
6267 You should always suffix the variable with the name of the
6268 provided item, and you should set it to the
6269 <link linkend='var-PN'><filename>PN</filename></link>
6270 of the recipe to which you want to give precedence.
6271 Some examples:
6272 <literallayout class='monospaced'>
6273 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
6274 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
6275 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
6276 </literallayout>
6277 </para>
6278 </glossdef>
6279 </glossentry>
6280
6281 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
6282 <glossdef>
6283 <para>
6284 If there are multiple versions of recipes available, this
6285 variable determines which recipe should be given preference.
6286 You must always suffix the variable with the
6287 <link linkend='var-PN'><filename>PN</filename></link>
6288 you want to select, and you should set the
6289 <link linkend='var-PV'><filename>PV</filename></link>
6290 accordingly for precedence.
6291 You can use the "<filename>%</filename>" character as a
6292 wildcard to match any number of characters, which can be
6293 useful when specifying versions that contain long revision
6294 numbers that could potentially change.
6295 Here are two examples:
6296 <literallayout class='monospaced'>
6297 PREFERRED_VERSION_python = "2.7.3"
6298 PREFERRED_VERSION_linux-yocto = "3.10%"
6299 </literallayout>
6300 </para>
6301 </glossdef>
6302 </glossentry>
6303
6304 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
6305 <glossdef>
6306 <para>
6307 Specifies additional paths from which the OpenEmbedded
6308 build system gets source code.
6309 When the build system searches for source code, it first
6310 tries the local download directory.
6311 If that location fails, the build system tries locations
6312 defined by <filename>PREMIRRORS</filename>, the upstream
6313 source, and then locations specified by
6314 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
6315 in that order.
6316 </para>
6317
6318 <para>
6319 Assuming your distribution
6320 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
6321 is "poky", the default value for
6322 <filename>PREMIRRORS</filename> is defined in the
6323 <filename>conf/distro/poky.conf</filename> file in the
6324 <filename>meta-yocto</filename> Git repository.
6325 </para>
6326
6327 <para>
6328 Typically, you could add a specific server for the
6329 build system to attempt before any others by adding
6330 something like the following to the
6331 <filename>local.conf</filename> configuration file in the
6332 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
6333 <literallayout class='monospaced'>
6334 PREMIRRORS_prepend = "\
6335 git://.*/.* http://www.yoctoproject.org/sources/ \n \
6336 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
6337 http://.*/.* http://www.yoctoproject.org/sources/ \n \
6338 https://.*/.* http://www.yoctoproject.org/sources/ \n"
6339 </literallayout>
6340 These changes cause the build system to intercept
6341 Git, FTP, HTTP, and HTTPS requests and direct them to
6342 the <filename>http://</filename> sources mirror.
6343 You can use <filename>file://</filename> URLs to point
6344 to local directories or network shares as well.
6345 </para>
6346 </glossdef>
6347 </glossentry>
6348
6349 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
6350 <glossdef>
6351
6352 <para>
6353 The <filename>PRINC</filename> variable has been deprecated
6354 and triggers a warning if detected during a build.
6355 For
6356 <link linkend='var-PR'><filename>PR</filename></link>
6357 increments on changes, use the PR service instead.
6358 You can find out more about this service in the
6359 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
6360 section in the Yocto Project Development Manual.
6361 </para>
6362<!--
6363
6364 <para>
6365 Causes the
6366 <link linkend='var-PR'><filename>PR</filename></link>
6367 variable of <filename>.bbappend</filename> files to
6368 dynamically increment.
6369 This increment minimizes the impact of layer ordering.
6370 </para>
6371
6372 <para>
6373 In order to ensure multiple <filename>.bbappend</filename>
6374 files can co-exist,
6375 <filename>PRINC</filename> should be self-referencing.
6376 This variable defaults to 0.
6377 </para>
6378
6379 <para>
6380 Following is an example that increments
6381 <filename>PR</filename> by two:
6382 <literallayout class='monospaced'>
6383 PRINC := "${@int(PRINC) + 2}"
6384 </literallayout>
6385 It is advisable not to use strings such as ".= '.1'" with the variable because
6386 this usage is very sensitive to layer ordering.
6387 You should avoid explicit assignments as they cannot
6388 adequately represent multiple
6389 <filename>.bbappend</filename> files.
6390 </para>
6391-->
6392 </glossdef>
6393 </glossentry>
6394
6395 <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
6396 <glossdef>
6397 <para>
6398 Specifies libraries installed within a recipe that
6399 should be ignored by the OpenEmbedded build system's
6400 shared library resolver.
6401 This variable is typically used when software being
6402 built by a recipe has its own private versions of a
6403 library normally provided by another recipe.
6404 In this case, you would not want the package containing
6405 the private libraries to be set as a dependency on other
6406 unrelated packages that should instead depend on the
6407 package providing the standard version of the library.
6408 </para>
6409
6410 <para>
6411 Libraries specified in this variable should be specified
6412 by their file name.
6413 For example, from the Firefox recipe in meta-browser:
6414 <literallayout class='monospaced'>
6415 PRIVATE_LIBS = "libmozjs.so \
6416 libxpcom.so \
6417 libnspr4.so \
6418 libxul.so \
6419 libmozalloc.so \
6420 libplc4.so \
6421 libplds4.so"
6422 </literallayout>
6423 </para>
6424 </glossdef>
6425 </glossentry>
6426
6427 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
6428 <glossdef>
6429 <para>
6430 A list of aliases by which a particular recipe can be
6431 known.
6432 By default, a recipe's own
6433 <filename><link linkend='var-PN'>PN</link></filename>
6434 is implicitly already in its <filename>PROVIDES</filename>
6435 list.
6436 If a recipe uses <filename>PROVIDES</filename>, the
6437 additional aliases are synonyms for the recipe and can
6438 be useful satisfying dependencies of other recipes during
6439 the build as specified by
6440 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
6441 </para>
6442
6443 <para>
6444 Consider the following example
6445 <filename>PROVIDES</filename> statement from a recipe
6446 file <filename>libav_0.8.11.bb</filename>:
6447 <literallayout class='monospaced'>
6448 PROVIDES += "libpostproc"
6449 </literallayout>
6450 The <filename>PROVIDES</filename> statement results in
6451 the "libav" recipe also being known as "libpostproc".
6452 </para>
6453 </glossdef>
6454 </glossentry>
6455
6456 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
6457 <glossdef>
6458 <para>
6459 The network based
6460 <link linkend='var-PR'><filename>PR</filename></link>
6461 service host and port.
6462 </para>
6463
6464 <para>
6465 The <filename>conf/local.conf.sample.extended</filename>
6466 configuration file in the
6467 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
6468 shows how the <filename>PRSERV_HOST</filename> variable is
6469 set:
6470 <literallayout class='monospaced'>
6471 PRSERV_HOST = "localhost:0"
6472 </literallayout>
6473 You must set the variable if you want to automatically
6474 start a local
6475 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
6476 You can set <filename>PRSERV_HOST</filename> to other
6477 values to use a remote PR service.
6478 </para>
6479 </glossdef>
6480 </glossentry>
6481
6482 <glossentry id='var-PV'><glossterm>PV</glossterm>
6483 <glossdef>
6484 <para>
6485 The version of the recipe.
6486 The version is normally extracted from the recipe filename.
6487 For example, if the recipe is named
6488 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
6489 will be "2.0.1".
6490 <filename>PV</filename> is generally not overridden within
6491 a recipe unless it is building an unstable (i.e. development) version from a source code repository
6492 (e.g. Git or Subversion).
6493 </para>
6494 </glossdef>
6495 </glossentry>
6496
6497 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
6498 <glossdef>
6499 <para>
6500 When used by recipes that inherit the
6501 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
6502 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
6503 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
6504 or
6505 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
6506 classes, denotes the Application Binary Interface (ABI)
6507 currently in use for Python.
6508 By default, the ABI is "m".
6509 You do not have to set this variable as the OpenEmbedded
6510 build system sets it for you.
6511 </para>
6512
6513 <para>
6514 The OpenEmbedded build system uses the ABI to construct
6515 directory names used when installing the Python headers
6516 and libraries in sysroot
6517 (e.g. <filename>.../python3.3m/...</filename>).
6518 </para>
6519
6520 <para>
6521 Recipes that inherit the
6522 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
6523 class during cross-builds also use this variable to
6524 locate the headers and libraries of the appropriate Python
6525 that the extension is targeting.
6526 </para>
6527 </glossdef>
6528 </glossentry>
6529
6530 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
6531 <glossdef>
6532 <para>
6533 When used by recipes that inherit the
6534 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
6535 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
6536 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
6537 or
6538 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
6539 classes, specifies the major Python version being built.
6540 For Python 2.x, <filename>PYTHON_PN</filename> would
6541 be "python2". For Python 3.x, the variable would be
6542 "python3".
6543 You do not have to set this variable as the
6544 OpenEmbedded build system automatically sets it for you.
6545 </para>
6546
6547 <para>
6548 The variable allows recipes to use common infrastructure
6549 such as the following:
6550 <literallayout class='monospaced'>
6551 DEPENDS += "${PYTHON_PN}-native"
6552 </literallayout>
6553 In the previous example, the version of the dependency
6554 is <filename>PYTHON_PN</filename>.
6555 </para>
6556 </glossdef>
6557 </glossentry>
6558
6559 </glossdiv>
6560
6561 <glossdiv id='var-glossary-q'><title>Q</title>
6562
6563 <glossentry id='var-QMAKE_PROFILES'><glossterm>QMAKE_PROFILES</glossterm>
6564 <glossdef>
6565 <para>
6566 Specifies your own subset of <filename>.pro</filename>
6567 files to be built for use with
6568 <filename>qmake</filename>.
6569 If you do not set this variable, all
6570 <filename>.pro</filename> files in the directory pointed to
6571 by <link linkend='var-S'><filename>S</filename></link>
6572 will be built by default.
6573 </para>
6574
6575 <para>
6576 This variable is used with recipes that inherit the
6577 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
6578 class or other classes that inherit
6579 <filename>qmake_base</filename>.
6580 </para>
6581 </glossdef>
6582 </glossentry>
6583
6584 </glossdiv>
6585
6586 <glossdiv id='var-glossary-r'><title>R</title>
6587
6588 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
6589 <glossdef>
6590 <para>
6591 The list of packages that conflict with packages.
6592 Note that packages will not be installed if conflicting
6593 packages are not first removed.
6594 </para>
6595
6596 <para>
6597 Like all package-controlling variables, you must always use
6598 them in conjunction with a package name override.
6599 Here is an example:
6600 <literallayout class='monospaced'>
6601 RCONFLICTS_${PN} = "another-conflicting-package-name"
6602 </literallayout>
6603 </para>
6604
6605 <para>
6606 BitBake, which the OpenEmbedded build system uses, supports
6607 specifying versioned dependencies.
6608 Although the syntax varies depending on the packaging
6609 format, BitBake hides these differences from you.
6610 Here is the general syntax to specify versions with
6611 the <filename>RCONFLICTS</filename> variable:
6612 <literallayout class='monospaced'>
6613 RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6614 </literallayout>
6615 For <filename>operator</filename>, you can specify the
6616 following:
6617 <literallayout class='monospaced'>
6618 =
6619 &lt;
6620 &gt;
6621 &lt;=
6622 &gt;=
6623 </literallayout>
6624 For example, the following sets up a dependency on version
6625 1.2 or greater of the package <filename>foo</filename>:
6626 <literallayout class='monospaced'>
6627 RCONFLICTS_${PN} = "foo (>= 1.2)"
6628 </literallayout>
6629 </para>
6630 </glossdef>
6631 </glossentry>
6632
6633 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
6634 <glossdef>
6635 <para>
6636 Lists a package's runtime dependencies (i.e. other packages)
6637 that must be installed in order for the built package to run
6638 correctly.
6639 If a package in this list cannot be found during the build,
6640 you will get a build error.
6641 </para>
6642
6643 <para>
6644 When you use the <filename>RDEPENDS</filename> variable
6645 in a recipe, you are essentially stating that the recipe's
6646 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
6647 task depends on the existence of a specific package.
6648 Consider this simple example for two recipes named "a" and
6649 "b" that produce similarly named IPK packages.
6650 In this example, the <filename>RDEPENDS</filename>
6651 statement appears in the "a" recipe:
6652 <literallayout class='monospaced'>
6653 RDEPENDS_${PN} = "b"
6654 </literallayout>
6655 Here, the dependency is such that the
6656 <filename>do_build</filename> task for recipe "a" depends
6657 on the
6658 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
6659 task of recipe "b".
6660 This means the package file for "b" must be available when
6661 the output for recipe "a" has been completely built.
6662 More importantly, package "a" will be marked as depending
6663 on package "b" in a manner that is understood by the
6664 package manager.
6665 </para>
6666
6667 <para>
6668 The names of the packages you list within
6669 <filename>RDEPENDS</filename> must be the names of other
6670 packages - they cannot be recipe names.
6671 Although package names and recipe names usually match,
6672 the important point here is that you are
6673 providing package names within the
6674 <filename>RDEPENDS</filename> variable.
6675 For an example of the default list of packages created from
6676 a recipe, see the
6677 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
6678 variable.
6679 </para>
6680
6681 <para>
6682 Because the <filename>RDEPENDS</filename> variable applies
6683 to packages being built, you should always use the variable
6684 in a form with an attached package name.
6685 For example, suppose you are building a development package
6686 that depends on the <filename>perl</filename> package.
6687 In this case, you would use the following
6688 <filename>RDEPENDS</filename> statement:
6689 <literallayout class='monospaced'>
6690 RDEPENDS_${PN}-dev += "perl"
6691 </literallayout>
6692 In the example, the development package depends on
6693 the <filename>perl</filename> package.
6694 Thus, the <filename>RDEPENDS</filename> variable has the
6695 <filename>${PN}-dev</filename> package name as part of the
6696 variable.
6697 </para>
6698
6699 <para>
6700 The package name you attach to the
6701 <filename>RDEPENDS</filename> variable must appear
6702 as it would in the <filename>PACKAGES</filename>
6703 namespace before any renaming of the output package by
6704 classes like
6705 <link linkend='ref-classes-debian'><filename>debian.bbclass</filename></link>.
6706 </para>
6707
6708 <para>
6709 In many cases you do not need to explicitly add
6710 runtime dependencies using
6711 <filename>RDEPENDS</filename> since some automatic
6712 handling occurs:
6713 <itemizedlist>
6714 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
6715 a runtime package contains a shared library
6716 (<filename>.so</filename>), the build
6717 processes the library in order to determine other
6718 libraries to which it is dynamically linked.
6719 The build process adds these libraries to
6720 <filename>RDEPENDS</filename> when creating the runtime
6721 package.</para></listitem>
6722 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
6723 the package ships a <filename>pkg-config</filename>
6724 information file, the build process uses this file
6725 to add items to the <filename>RDEPENDS</filename>
6726 variable to create the runtime packages.
6727 </para></listitem>
6728 </itemizedlist>
6729 </para>
6730
6731 <para>
6732 BitBake, which the OpenEmbedded build system uses, supports
6733 specifying versioned dependencies.
6734 Although the syntax varies depending on the packaging
6735 format, BitBake hides these differences from you.
6736 Here is the general syntax to specify versions with
6737 the <filename>RDEPENDS</filename> variable:
6738 <literallayout class='monospaced'>
6739 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6740 </literallayout>
6741 For <filename>operator</filename>, you can specify the
6742 following:
6743 <literallayout class='monospaced'>
6744 =
6745 &lt;
6746 &gt;
6747 &lt;=
6748 &gt;=
6749 </literallayout>
6750 For example, the following sets up a dependency on version
6751 1.2 or greater of the package <filename>foo</filename>:
6752 <literallayout class='monospaced'>
6753 RDEPENDS_${PN} = "foo (>= 1.2)"
6754 </literallayout>
6755 </para>
6756
6757 <para>
6758 For information on build-time dependencies, see the
6759 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
6760 variable.
6761 </para>
6762 </glossdef>
6763 </glossentry>
6764
6765 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
6766 <glossdef>
6767 <para>
6768 When a recipe inherits the
6769 <filename>distro_features_check</filename> class, this
6770 variable identifies distribution features that must
6771 exist in the current configuration in order for the
6772 OpenEmbedded build system to build the recipe.
6773 In other words, if the
6774 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
6775 lists a feature that does not appear in
6776 <filename>DISTRO_FEATURES</filename> within the
6777 current configuration, an error occurs and the
6778 build stops.
6779 </para>
6780 </glossdef>
6781 </glossentry>
6782
6783 <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
6784 <glossdef>
6785 <para>
6786 Reclaims disk space by removing previously built
6787 versions of the same image from the
6788 <filename>images</filename> directory pointed to by the
6789 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
6790 variable.
6791 </para>
6792
6793 <para>
6794 Set this variable to "1" in your
6795 <filename>local.conf</filename> file to remove these
6796 images.
6797 </para>
6798 </glossdef>
6799 </glossentry>
6800
6801 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
6802 <glossdef>
6803 <para>
6804 With <filename>rm_work</filename> enabled, this
6805 variable specifies a list of recipes whose work directories
6806 should not be removed.
6807 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
6808 section for more details.
6809 </para>
6810 </glossdef>
6811 </glossentry>
6812
6813 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
6814 <glossdef>
6815 <para>
6816 Defines the root home directory.
6817 By default, this directory is set as follows in the
6818 BitBake configuration file:
6819 <literallayout class='monospaced'>
6820 ROOT_HOME ??= "/home/root"
6821 </literallayout>
6822 <note>
6823 This default value is likely used because some
6824 embedded solutions prefer to have a read-only root
6825 filesystem and prefer to keep writeable data in one
6826 place.
6827 </note>
6828 </para>
6829
6830 <para>
6831 You can override the default by setting the variable
6832 in any layer or in the <filename>local.conf</filename> file.
6833 Because the default is set using a "weak" assignment
6834 (i.e. "??="), you can use either of the following forms
6835 to define your override:
6836 <literallayout class='monospaced'>
6837 ROOT_HOME = "/root"
6838 ROOT_HOME ?= "/root"
6839 </literallayout>
6840 These override examples use <filename>/root</filename>,
6841 which is probably the most commonly used override.
6842 </para>
6843 </glossdef>
6844 </glossentry>
6845
6846 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
6847 <glossdef>
6848 <para>
6849 Indicates a filesystem image to include as the root
6850 filesystem.
6851 </para>
6852
6853 <para>
6854 The <filename>ROOTFS</filename> variable is an optional
6855 variable used with the
6856 <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link>
6857 class.
6858 </para>
6859 </glossdef>
6860 </glossentry>
6861
6862 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
6863 <glossdef>
6864 <para>
6865 Added by classes to run post processing commands once the
6866 OpenEmbedded build system has created the root filesystem.
6867 You can specify shell commands separated by semicolons:
6868 <literallayout class='monospaced'>
6869 ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
6870 </literallayout>
6871 If you need to pass the path to the root filesystem within
6872 the command, you can use
6873 <filename>${IMAGE_ROOTFS}</filename>, which points to
6874 the root filesystem image.
6875 See the
6876 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6877 variable for more information.
6878 </para>
6879 </glossdef>
6880 </glossentry>
6881
6882 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
6883 <glossdef>
6884 <para>
6885 A list of package name aliases that a package also provides.
6886 These aliases are useful for satisfying runtime dependencies
6887 of other packages both during the build and on the target
6888 (as specified by
6889 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
6890 <note>
6891 A package's own name is implicitly already in its
6892 <filename>RPROVIDES</filename> list.
6893 </note>
6894 </para>
6895 <para>
6896 As with all package-controlling variables, you must always
6897 use the variable in conjunction with a package name override.
6898 Here is an example:
6899 <literallayout class='monospaced'>
6900 RPROVIDES_${PN} = "widget-abi-2"
6901 </literallayout>
6902 </para>
6903 </glossdef>
6904 </glossentry>
6905
6906 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
6907 <glossdef>
6908 <para>
6909 A list of packages that extends the usability of a package
6910 being built.
6911 The package being built does not depend on this list of
6912 packages in order to successfully build, but needs them for
6913 the extended usability.
6914 To specify runtime dependencies for packages, see the
6915 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
6916 variable.
6917 </para>
6918
6919 <para>
6920 The OpenEmbedded build process automatically installs the
6921 list of packages as part of the built package.
6922 However, you can remove these packages later if you want.
6923 If, during the build, a package from the
6924 <filename>RRECOMMENDS</filename> list cannot be
6925 found, the build process continues without an error.
6926 </para>
6927
6928 <para>
6929 You can also prevent packages in the list from being
6930 installed by using several variables.
6931 See the
6932 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
6933 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
6934 and
6935 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
6936 variables for more information.
6937 </para>
6938
6939 <para>
6940 Because the <filename>RRECOMMENDS</filename> variable
6941 applies to packages being built, you should always attach
6942 an override to the variable to specify the particular
6943 package whose usability is being extended.
6944 For example, suppose you are building a development package
6945 that is extended to support wireless functionality.
6946 In this case, you would use the following:
6947 <literallayout class='monospaced'>
6948 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
6949 </literallayout>
6950 In the example, the package name
6951 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
6952 must appear as it would in the
6953 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
6954 namespace before any renaming of the output package by
6955 classes such as <filename>debian.bbclass</filename>.
6956 </para>
6957
6958 <para>
6959 BitBake, which the OpenEmbedded build system uses, supports
6960 specifying versioned recommends.
6961 Although the syntax varies depending on the packaging
6962 format, BitBake hides these differences from you.
6963 Here is the general syntax to specify versions with
6964 the <filename>RRECOMMENDS</filename> variable:
6965 <literallayout class='monospaced'>
6966 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6967 </literallayout>
6968 For <filename>operator</filename>, you can specify the
6969 following:
6970 <literallayout class='monospaced'>
6971 =
6972 &lt;
6973 &gt;
6974 &lt;=
6975 &gt;=
6976 </literallayout>
6977 For example, the following sets up a recommend on version
6978 1.2 or greater of the package <filename>foo</filename>:
6979 <literallayout class='monospaced'>
6980 RRECOMMENDS_${PN} = "foo (>= 1.2)"
6981 </literallayout>
6982 </para>
6983 </glossdef>
6984 </glossentry>
6985
6986 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
6987 <glossdef>
6988 <para>
6989 A list of packages replaced by a package.
6990 The package manager uses this variable to determine which
6991 package should be installed to replace other package(s)
6992 during an upgrade.
6993 In order to also have the other package(s) removed at the
6994 same time, you must add the name of the other
6995 package to the
6996 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
6997 </para>
6998 <para>
6999 As with all package-controlling variables, you must use
7000 this variable in conjunction with a package name
7001 override.
7002 Here is an example:
7003 <literallayout class='monospaced'>
7004 RREPLACES_${PN} = "other-package-being-replaced"
7005 </literallayout>
7006 </para>
7007
7008 <para>
7009 BitBake, which the OpenEmbedded build system uses, supports
7010 specifying versioned replacements.
7011 Although the syntax varies depending on the packaging
7012 format, BitBake hides these differences from you.
7013 Here is the general syntax to specify versions with
7014 the <filename>RREPLACES</filename> variable:
7015 <literallayout class='monospaced'>
7016 RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
7017 </literallayout>
7018 For <filename>operator</filename>, you can specify the
7019 following:
7020 <literallayout class='monospaced'>
7021 =
7022 &lt;
7023 &gt;
7024 &lt;=
7025 &gt;=
7026 </literallayout>
7027 For example, the following sets up a replacement using
7028 version 1.2 or greater of the package
7029 <filename>foo</filename>:
7030 <literallayout class='monospaced'>
7031 RREPLACES_${PN} = "foo (>= 1.2)"
7032 </literallayout>
7033 </para>
7034 </glossdef>
7035 </glossentry>
7036
7037 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
7038 <glossdef>
7039 <para>
7040 A list of additional packages that you can suggest for
7041 installation by the package manager at the time a package
7042 is installed.
7043 Not all package managers support this functionality.
7044 </para>
7045 <para>
7046 As with all package-controlling variables, you must always
7047 use this variable in conjunction with a package name
7048 override.
7049 Here is an example:
7050 <literallayout class='monospaced'>
7051 RSUGGESTS_${PN} = "useful-package another-package"
7052 </literallayout>
7053 </para>
7054 </glossdef>
7055 </glossentry>
7056
7057 </glossdiv>
7058
7059 <glossdiv id='var-glossary-s'><title>S</title>
7060
7061 <glossentry id='var-S'><glossterm>S</glossterm>
7062 <glossdef>
7063 <para>
7064 The location in the
7065 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
7066 where unpacked recipe source code resides.
7067 This location is within the work directory
7068 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
7069 which is not static.
7070 The unpacked source location depends on the recipe name
7071 (<filename><link linkend='var-PN'>PN</link></filename>) and
7072 recipe version
7073 (<filename><link linkend='var-PV'>PV</link></filename>) as
7074 follows:
7075 <literallayout class='monospaced'>
7076 ${WORKDIR}/${PN}-${PV}
7077 </literallayout>
7078 As an example, assume a
7079 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
7080 top-level folder named <filename>poky</filename> and a
7081 default Build Directory at <filename>poky/build</filename>.
7082 In this case, the work directory the build system uses
7083 to keep the unpacked recipe for <filename>db</filename>
7084 is the following:
7085 <literallayout class='monospaced'>
7086 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
7087 </literallayout>
7088 </para>
7089 </glossdef>
7090 </glossentry>
7091
7092 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
7093 <glossdef>
7094 <para>
7095 A list of the host distribution identifiers that the
7096 build system has been tested against.
7097 Identifiers consist of the host distributor ID
7098 followed by the release,
7099 as reported by the <filename>lsb_release</filename> tool
7100 or as read from <filename>/etc/lsb-release</filename>.
7101 Separate the list items with explicit newline
7102 characters (<filename>\n</filename>).
7103 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
7104 and the current value of
7105 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
7106 does not appear in the list, then the build system reports
7107 a warning that indicates the current host distribution has
7108 not been tested as a build host.
7109 </para>
7110 </glossdef>
7111 </glossentry>
7112
7113 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
7114 <glossdef>
7115 <para>
7116 The target architecture for the SDK.
7117 Typically, you do not directly set this variable.
7118 Instead, use
7119 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
7120 </para>
7121 </glossdef>
7122 </glossentry>
7123
7124 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
7125 <glossdef>
7126 <para>
7127 The directory set up and used by the
7128 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
7129 to which the SDK is deployed.
7130 The <filename>populate_sdk_base</filename> class defines
7131 <filename>SDK_DEPLOY</filename> as follows:
7132 <literallayout class='monospaced'>
7133 SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk"
7134 </literallayout>
7135 </para>
7136 </glossdef>
7137 </glossentry>
7138
7139 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
7140 <glossdef>
7141 <para>
7142 The parent directory used by the OpenEmbedded build system
7143 when creating SDK output.
7144 The
7145 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
7146 class defines the variable as follows:
7147 <literallayout class='monospaced'>
7148 SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"
7149 </literallayout>
7150 <note>
7151 The <filename>SDK_DIR</filename> directory is a
7152 temporary directory as it is part of
7153 <filename>WORKDIR</filename>.
7154 The final output directory is
7155 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
7156 </note>
7157 </para>
7158 </glossdef>
7159 </glossentry>
7160
7161 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
7162 <glossdef>
7163 <para>
7164 The base name for SDK output files.
7165 The name is derived from the
7166 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
7167 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
7168 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
7169 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
7170 and
7171 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
7172 variables:
7173 <literallayout class='monospaced'>
7174 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
7175 </literallayout>
7176 </para>
7177 </glossdef>
7178 </glossentry>
7179
7180 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
7181 <glossdef>
7182 <para>
7183 The location used by the OpenEmbedded build system when
7184 creating SDK output.
7185 The
7186 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
7187 class defines the variable as follows:
7188 <literallayout class='monospaced'>
7189 SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"
7190 </literallayout>
7191 <note>
7192 The <filename>SDK_OUTPUT</filename> directory is a
7193 temporary directory as it is part of
7194 <filename>WORKDIR</filename> by way of
7195 <filename>SDK_DIR</filename>.
7196 The final output directory is
7197 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
7198 </note>
7199
7200 </para>
7201 </glossdef>
7202 </glossentry>
7203
7204 <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
7205 <glossdef>
7206 <para>
7207 Specifies a list of architectures compatible with
7208 the SDK machine.
7209 This variable is set automatically and should not
7210 normally be hand-edited.
7211 Entries are separated using spaces and listed in order
7212 of priority.
7213 The default value for
7214 <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
7215 ${SDK_ARCH}-${SDKPKGSUFFIX}".
7216 </para>
7217 </glossdef>
7218 </glossentry>
7219
7220 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
7221 <glossdef>
7222 <para>Equivalent to
7223 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
7224 However, this variable applies to the SDK generated from an
7225 image using the following command:
7226 <literallayout class='monospaced'>
7227 $ bitbake -c populate_sdk imagename
7228 </literallayout>
7229 </para>
7230 </glossdef>
7231 </glossentry>
7232
7233 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
7234 <glossdef>
7235 <para>
7236 The machine for which the Application Development Toolkit
7237 (ADT) or SDK is built.
7238 In other words, the SDK or ADT is built such that it
7239 runs on the target you specify with the
7240 <filename>SDKMACHINE</filename> value.
7241 The value points to a corresponding
7242 <filename>.conf</filename> file under
7243 <filename>conf/machine-sdk/</filename>.
7244 </para>
7245
7246 <para>
7247 You can use "i686" and "x86_64" as possible values
7248 for this variable. The variable defaults to "i686"
7249 and is set in the local.conf file in the Build Directory.
7250 <literallayout class='monospaced'>
7251 SDKMACHINE ?= "i686"
7252 </literallayout>
7253 <note>
7254 You cannot set the <filename>SDKMACHINE</filename>
7255 variable in your distribution configuration file.
7256 If you do, the configuration will not take affect.
7257 </note>
7258 </para>
7259 </glossdef>
7260 </glossentry>
7261
7262 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
7263 <glossdef>
7264 <para>
7265 Defines the path offered to the user for installation
7266 of the SDK that is generated by the OpenEmbedded build
7267 system.
7268 The path appears as the default location for installing
7269 the SDK when you run the SDK's installation script.
7270 You can override the offered path when you run the
7271 script.
7272 </para>
7273 </glossdef>
7274 </glossentry>
7275
7276 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
7277 <glossdef>
7278 <para>The section in which packages should be categorized.
7279 Package management utilities can make use of this variable.</para>
7280 </glossdef>
7281 </glossentry>
7282
7283 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
7284 <glossdef>
7285 <para>
7286 Specifies the optimization flags passed to the C compiler
7287 when building for the target.
7288 The flags are passed through the default value of the
7289 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
7290 variable.
7291 </para>
7292
7293 <para>
7294 The <filename>SELECTED_OPTIMIZATION</filename> variable
7295 takes the value of
7296 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
7297 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
7298 If that is the case, the value of
7299 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
7300 </para>
7301 </glossdef>
7302 </glossentry>
7303
7304 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
7305 <glossdef>
7306 <para>
7307 Defines a serial console (TTY) to enable using getty.
7308 Provide a value that specifies the baud rate followed by
7309 the TTY device name separated by a space.
7310 You cannot specify more than one TTY device:
7311 <literallayout class='monospaced'>
7312 SERIAL_CONSOLE = "115200 ttyS0"
7313 </literallayout>
7314 <note>
7315 The <filename>SERIAL_CONSOLE</filename> variable
7316 is deprecated.
7317 Please use the
7318 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
7319 variable.
7320 </note>
7321 </para>
7322 </glossdef>
7323 </glossentry>
7324
7325 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
7326 <glossdef>
7327 <para>
7328 Defines the serial consoles (TTYs) to enable using getty.
7329 Provide a value that specifies the baud rate followed by
7330 the TTY device name separated by a semicolon.
7331 Use spaces to separate multiple devices:
7332 <literallayout class='monospaced'>
7333 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
7334 </literallayout>
7335 </para>
7336 </glossdef>
7337 </glossentry>
7338
7339 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
7340 <glossdef>
7341 <para>
7342 Similar to
7343 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
7344 except the device is checked for existence before attempting
7345 to enable it.
7346 This variable is currently only supported with SysVinit
7347 (i.e. not with systemd).
7348 </para>
7349 </glossdef>
7350 </glossentry>
7351
7352 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
7353 <glossdef>
7354 <para>
7355 A list of recipe dependencies that should not be used to
7356 determine signatures of tasks from one recipe when they
7357 depend on tasks from another recipe.
7358 For example:
7359 <literallayout class='monospaced'>
7360 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
7361 </literallayout>
7362 In this example, <filename>intone</filename> depends on
7363 <filename>mplayer2</filename>.
7364 </para>
7365
7366 <para>
7367 Use of this variable is one mechanism to remove dependencies
7368 that affect task signatures and thus force rebuilds when a
7369 recipe changes.
7370 <note><title>Caution</title>
7371 If you add an inappropriate dependency for a recipe
7372 relationship, the software might break during
7373 runtime if the interface of the second recipe was
7374 changed after the first recipe had been built.
7375 </note>
7376 </para>
7377 </glossdef>
7378 </glossentry>
7379
7380 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
7381 <glossdef>
7382 <para>
7383 A list of recipes that are completely stable and will
7384 never change.
7385 The ABI for the recipes in the list are presented by
7386 output from the tasks run to build the recipe.
7387 Use of this variable is one way to remove dependencies from
7388 one recipe on another that affect task signatures and
7389 thus force rebuilds when the recipe changes.
7390 <note><title>Caution</title>
7391 If you add an inappropriate variable to this list,
7392 the software might break at runtime if the
7393 interface of the recipe was changed after the other
7394 had been built.
7395 </note>
7396 </para>
7397 </glossdef>
7398 </glossentry>
7399
7400 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
7401 <glossdef>
7402 <para>
7403 Specifies the number of bits for the target system CPU.
7404 The value should be either "32" or "64".
7405 </para>
7406 </glossdef>
7407 </glossentry>
7408
7409 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
7410 <glossdef>
7411 <para>
7412 Specifies the endian byte order of the target system.
7413 The value should be either "le" for little-endian or "be" for big-endian.
7414 </para>
7415 </glossdef>
7416 </glossentry>
7417
7418 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
7419 <glossdef>
7420 <para>
7421 Groups together machines based upon the same family
7422 of SOC (System On Chip).
7423 You typically set this variable in a common
7424 <filename>.inc</filename> file that you include in the
7425 configuration files of all the machines.
7426 <note>
7427 You must include
7428 <filename>conf/machine/include/soc-family.inc</filename>
7429 for this variable to appear in
7430 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
7431 </note>
7432 </para>
7433 </glossdef>
7434 </glossentry>
7435
7436 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
7437 <glossdef>
7438 <para>
7439 Defines the suffix for shared libraries used on the
7440 target platform.
7441 By default, this suffix is ".so.*" for all Linux-based
7442 systems and is defined in the
7443 <filename>meta/conf/bitbake.conf</filename> configuration
7444 file.
7445 </para>
7446
7447 <para>
7448 You will see this variable referenced in the default values
7449 of <filename>FILES_${PN}</filename>.
7450 </para>
7451 </glossdef>
7452 </glossentry>
7453
7454 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
7455 <glossdef>
7456 <para>
7457 Defines the suffix for the development symbolic link
7458 (symlink) for shared libraries on the target platform.
7459 By default, this suffix is ".so" for Linux-based
7460 systems and is defined in the
7461 <filename>meta/conf/bitbake.conf</filename> configuration
7462 file.
7463 </para>
7464
7465 <para>
7466 You will see this variable referenced in the default values
7467 of <filename>FILES_${PN}-dev</filename>.
7468 </para>
7469 </glossdef>
7470 </glossentry>
7471
7472 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
7473 <glossdef>
7474 <para>
7475 Defines your own
7476 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
7477 from which to first fetch source before attempting to fetch
7478 from the upstream specified in
7479 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
7480 </para>
7481
7482 <para>
7483 To use this variable, you must globally inherit the
7484 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
7485 class and then provide the URL to your mirrors.
7486 Here is an example:
7487 <literallayout class='monospaced'>
7488 INHERIT += "own-mirrors"
7489 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
7490 </literallayout>
7491 <note>
7492 You can specify only a single URL in
7493 <filename>SOURCE_MIRROR_URL</filename>.
7494 </note>
7495 </para>
7496 </glossdef>
7497 </glossentry>
7498
7499 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
7500 <glossdef>
7501 <para>
7502 Maps commonly used license names to their SPDX counterparts
7503 found in <filename>meta/files/common-licenses/</filename>.
7504 For the default <filename>SPDXLICENSEMAP</filename>
7505 mappings, see the
7506 <filename>meta/conf/licenses.conf</filename> file.
7507 </para>
7508
7509 <para>
7510 For additional information, see the
7511 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
7512 variable.
7513 </para>
7514 </glossdef>
7515 </glossentry>
7516
7517 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
7518 <glossdef>
7519 <para>
7520 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
7521 OpenEmbedded build system to create variants of recipes or packages.
7522 The list specifies the prefixes to strip off during certain circumstances
7523 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
7524 </para>
7525 </glossdef>
7526 </glossentry>
7527
7528 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
7529 <glossdef>
7530 <para>The list of source files - local or remote.
7531 This variable tells the OpenEmbedded build system which bits
7532 to pull in for the build and how to pull them in.
7533 For example, if the recipe or append file only needs to
7534 fetch a tarball from the Internet, the recipe or
7535 append file uses a single <filename>SRC_URI</filename>
7536 entry.
7537 On the other hand, if the recipe or append file needs to
7538 fetch a tarball, apply two patches, and include a custom
7539 file, the recipe or append file would include four
7540 instances of the variable.</para>
7541 <para>The following list explains the available URI protocols:
7542 <itemizedlist>
7543 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
7544 Fetches files, which are usually files shipped with
7545 the
7546 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
7547 from the local machine.
7548 The path is relative to the
7549 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
7550 variable.
7551 Thus, the build system searches, in order, from the
7552 following directories, which are assumed to be a
7553 subdirectories of the directory in which the
7554 recipe file (<filename>.bb</filename>) or
7555 append file (<filename>.bbappend</filename>)
7556 resides:
7557 <itemizedlist>
7558 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
7559 The base recipe name without any special
7560 suffix or version numbers.
7561 </para></listitem>
7562 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
7563 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
7564 The base recipe name and version but without
7565 any special package name suffix.
7566 </para></listitem>
7567 <listitem><para><emphasis>files -</emphasis>
7568 Files within a directory, which is named
7569 <filename>files</filename> and is also
7570 alongside the recipe or append file.
7571 </para></listitem>
7572 </itemizedlist>
7573 <note>
7574 If you want the build system to pick up files
7575 specified through a
7576 <filename>SRC_URI</filename>
7577 statement from your append file, you need to be
7578 sure to extend the
7579 <filename>FILESPATH</filename>
7580 variable by also using the
7581 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
7582 variable from within your append file.
7583 </note>
7584 </para></listitem>
7585 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
7586 Bazaar revision control repository.</para></listitem>
7587 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
7588 Git revision control repository.</para></listitem>
7589 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
7590 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
7591 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
7592 a repo (Git) repository.</para></listitem>
7593 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
7594 an SVK revision control repository.</para></listitem>
7595 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
7596 the Internet using <filename>http</filename>.</para></listitem>
7597 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
7598 from the Internet using <filename>https</filename>.</para></listitem>
7599 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
7600 from the Internet using <filename>ftp</filename>.</para></listitem>
7601 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
7602 a CVS revision control repository.</para></listitem>
7603 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
7604 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
7605 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
7606 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
7607 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
7608 a secure shell.</para></listitem>
7609 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
7610 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
7611 </itemizedlist>
7612 </para>
7613 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
7614 Here are standard options:
7615 <itemizedlist>
7616 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
7617 the patch or not.
7618 The default action is to apply the patch.</para></listitem>
7619 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
7620 striplevel to use when applying the patch.
7621 The default level is 1.</para></listitem>
7622 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
7623 the directory in which the patch should be applied.
7624 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
7625 </para></listitem>
7626 </itemizedlist>
7627 </para>
7628 <para>Here are options specific to recipes building code from a revision control system:
7629 <itemizedlist>
7630 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
7631 Apply the patch only if
7632 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
7633 is equal to or greater than <filename>mindate</filename>.
7634 </para></listitem>
7635 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
7636 Apply the patch only if <filename>SRCDATE</filename>
7637 is not later than <filename>mindate</filename>.
7638 </para></listitem>
7639 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
7640 Apply the patch only if <filename>SRCREV</filename>
7641 is equal to or greater than <filename>minrev</filename>.
7642 </para></listitem>
7643 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
7644 Apply the patch only if <filename>SRCREV</filename>
7645 is not later than <filename>maxrev</filename>.
7646 </para></listitem>
7647 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
7648 Apply the patch only if <filename>SRCREV</filename>
7649 is equal to <filename>rev</filename>.
7650 </para></listitem>
7651 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
7652 Apply the patch only if <filename>SRCREV</filename>
7653 is not equal to <filename>rev</filename>.
7654 </para></listitem>
7655 </itemizedlist>
7656 </para>
7657 <para>Here are some additional options worth mentioning:
7658 <itemizedlist>
7659 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
7660 whether or not to unpack the file if it is an archive.
7661 The default action is to unpack the file.</para></listitem>
7662 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
7663 (or extracts its contents) into the specified
7664 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
7665 This option is useful for unusual tarballs or other archives that
7666 do not have their files already in a subdirectory within the archive.
7667 </para></listitem>
7668 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
7669 name to be used for association with <filename>SRC_URI</filename> checksums
7670 when you have more than one file specified in <filename>SRC_URI</filename>.
7671 </para></listitem>
7672 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
7673 the filename used when storing the downloaded file.</para></listitem>
7674 </itemizedlist>
7675 </para>
7676 </glossdef>
7677 </glossentry>
7678
7679 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
7680 <glossdef>
7681 <para></para>
7682 <para>
7683 By default, the OpenEmbedded build system automatically detects whether
7684 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
7685 contains files that are machine-specific.
7686 If so, the build system automatically changes
7687 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
7688 Setting this variable to "0" disables this behavior.
7689 </para>
7690 </glossdef>
7691 </glossentry>
7692
7693 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
7694 <glossdef>
7695 <para>
7696 The date of the source code used to build the package.
7697 This variable applies only if the source was fetched from a Source Code Manager (SCM).
7698 </para>
7699 </glossdef>
7700 </glossentry>
7701
7702 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
7703 <glossdef>
7704 <para>
7705 Returns the version string of the current package.
7706 This string is used to help define the value of
7707 <link linkend='var-PV'><filename>PV</filename></link>.
7708 </para>
7709
7710 <para>
7711 The <filename>SRCPV</filename> variable is defined in the
7712 <filename>meta/conf/bitbake.conf</filename> configuration
7713 file in the
7714 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
7715 as follows:
7716 <literallayout class='monospaced'>
7717 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7718 </literallayout>
7719 </para>
7720
7721 <para>
7722 Recipes that need to define <filename>PV</filename> do so
7723 with the help of the <filename>SRCPV</filename>.
7724 For example, the <filename>ofono</filename> recipe
7725 (<filename>ofono_git.bb</filename>) located in
7726 <filename>meta/recipes-connectivity</filename> in the
7727 Source Directory defines <filename>PV</filename> as
7728 follows:
7729 <literallayout class='monospaced'>
7730 PV = "0.12-git${SRCPV}"
7731 </literallayout>
7732 </para>
7733 </glossdef>
7734 </glossentry>
7735
7736 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
7737 <glossdef>
7738 <para>
7739 The revision of the source code used to build the package.
7740 This variable applies to Subversion, Git, Mercurial and Bazaar
7741 only.
7742 Note that if you wish to build a fixed revision and you wish
7743 to avoid performing a query on the remote repository every time
7744 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
7745 full revision identifier and not just a tag.
7746 </para>
7747 </glossdef>
7748 </glossentry>
7749
7750 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
7751 <glossdef>
7752 <para>The directory for the shared state cache.</para>
7753 </glossdef>
7754 </glossentry>
7755
7756 <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
7757 <glossdef>
7758 <para>
7759 If set to "1", allows fetches from
7760 mirrors that are specified in
7761 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
7762 to work even when fetching from the network has been
7763 disabled by setting <filename>BB_NO_NETWORK</filename>
7764 to "1".
7765 Using the
7766 <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
7767 variable is useful if you have set
7768 <filename>SSTATE_MIRRORS</filename> to point to an
7769 internal server for your shared state cache, but
7770 you want to disable any other fetching from the network.
7771 </para>
7772 </glossdef>
7773 </glossentry>
7774
7775 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
7776 <glossdef>
7777 <para>
7778 Configures the OpenEmbedded build system to search other
7779 mirror locations for prebuilt cache data objects before
7780 building out the data.
7781 This variable works like fetcher
7782 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
7783 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
7784 and points to the cache locations to check for the shared
7785 objects.
7786 </para>
7787
7788 <para>
7789 You can specify a filesystem directory or a remote URL such
7790 as HTTP or FTP.
7791 The locations you specify need to contain the shared state
7792 cache (sstate-cache) results from previous builds.
7793 The sstate-cache you point to can also be from builds on
7794 other machines.
7795 </para>
7796
7797 <para>
7798 If a mirror uses the same structure as
7799 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
7800 you need to add
7801 "PATH" at the end as shown in the examples below.
7802 The build system substitutes the correct path within the
7803 directory structure.
7804 <literallayout class='monospaced'>
7805 SSTATE_MIRRORS ?= "\
7806 file://.* http://someserver.tld/share/sstate/PATH \n \
7807 file://.* file:///some/local/dir/sstate/PATH"
7808 </literallayout>
7809 </para>
7810 </glossdef>
7811 </glossentry>
7812
7813 <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
7814 <glossdef>
7815 <para>
7816 Specifies the path to the <filename>/lib</filename>
7817 subdirectory of the sysroot directory for the
7818 build host.
7819 </para>
7820 </glossdef>
7821 </glossentry>
7822
7823 <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
7824 <glossdef>
7825 <para>
7826 Specifies the path to the <filename>/lib</filename>
7827 subdirectory of the sysroot directory for the target
7828 for which the current recipe is being built
7829 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
7830 </para>
7831 </glossdef>
7832 </glossentry>
7833
7834 <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
7835 <glossdef>
7836 <para>
7837 Specifies the path to the
7838 <filename>/usr/bin</filename> subdirectory of the
7839 sysroot directory for the target for which the current
7840 recipe is being built
7841 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
7842 </para>
7843 </glossdef>
7844 </glossentry>
7845
7846 <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
7847 <glossdef>
7848 <para>
7849 Specifies the path to the directory containing binary
7850 configuration scripts.
7851 These scripts provide configuration information for
7852 other software that wants to make use of libraries or
7853 include files provided by the software associated with
7854 the script.
7855 <note>
7856 This style of build configuration has been largely
7857 replaced by <filename>pkg-config</filename>.
7858 Consequently, if <filename>pkg-config</filename>
7859 is supported by the library to which you are linking,
7860 it is recommended you use
7861 <filename>pkg-config</filename> instead of a
7862 provided configuration script.
7863 </note>
7864 </para>
7865 </glossdef>
7866 </glossentry>
7867
7868 <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
7869 <glossdef>
7870 <para>
7871 Specifies the path to the
7872 <filename>/usr/bin</filename> subdirectory of the
7873 sysroot directory for the build host.
7874 </para>
7875 </glossdef>
7876 </glossentry>
7877
7878 <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
7879 <glossdef>
7880 <para>
7881 Specifies the path to the <filename>/usr/share</filename>
7882 subdirectory of the sysroot directory for the target
7883 for which the current recipe is being built
7884 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
7885 </para>
7886 </glossdef>
7887 </glossentry>
7888
7889 <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
7890 <glossdef>
7891 <para>
7892 Specifies the path to the top-level sysroots directory
7893 (i.e.
7894 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>).
7895 <note>
7896 Recipes should never write files directly under
7897 this directory because the OpenEmbedded build system
7898 manages the directory automatically.
7899 Instead, files should be installed to
7900 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
7901 within your recipe's
7902 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
7903 task and then the OpenEmbedded build system will
7904 stage a subset of those files into the sysroot.
7905 </note>
7906 </para>
7907 </glossdef>
7908 </glossentry>
7909
7910 <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
7911 <glossdef>
7912 <para>
7913 Specifies the path to the primary sysroot directory for
7914 which the target is being built.
7915 Depending on the type of recipe and the build target, the
7916 recipe's value is as follows:
7917 <itemizedlist>
7918 <listitem><para>For recipes building for the target
7919 machine, the value is "${STAGING_DIR}/${MACHINE}".
7920 </para></listitem>
7921 <listitem><para>For <filename>native</filename>
7922 recipes building
7923 for the build host, the value is empty given the
7924 assumption that when building for the build host,
7925 the build host's own directories should be used.
7926 </para></listitem>
7927 <listitem><para>For <filename>nativesdk</filename>
7928 recipes that Build for the SDK, the value is
7929 "${STAGING_DIR}/${MULTIMACH_HOST_SYS}".
7930 </para></listitem>
7931 </itemizedlist>
7932 </para>
7933 </glossdef>
7934 </glossentry>
7935
7936 <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
7937 <glossdef>
7938 <para>
7939 Specifies the path to the <filename>/usr/share</filename>
7940 subdirectory of the sysroot directory for the build host.
7941 </para>
7942 </glossdef>
7943 </glossentry>
7944
7945
7946
7947 <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
7948 <glossdef>
7949 <para>
7950 Specifies the path to the sysroot directory for the
7951 build host.
7952 </para>
7953 </glossdef>
7954 </glossentry>
7955
7956 <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
7957 <glossdef>
7958 <para>
7959 Specifies the path to the sysroot directory for the
7960 target for which the current recipe is being built.
7961 In most cases, this path is the
7962 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
7963 </para>
7964
7965 <para>
7966 Some recipes build binaries that can run on the target
7967 system but those binaries in turn generate code for
7968 another different system (e.g. cross-canadian recipes).
7969 Using terminology from GNU, the primary system is referred
7970 to as the "HOST" and the secondary, or different, system is
7971 referred to as the "TARGET".
7972 Thus, the binaries run on the "HOST" system and
7973 and generate binaries for the "TARGET" system.
7974 <filename>STAGING_DIR_TARGET</filename> points to the
7975 sysroot used for the "TARGET" system.
7976 </para>
7977 </glossdef>
7978 </glossentry>
7979
7980 <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
7981 <glossdef>
7982 <para>
7983 Specifies the path to the <filename>/etc</filename>
7984 subdirectory of the sysroot directory for the
7985 build host.
7986 </para>
7987 </glossdef>
7988 </glossentry>
7989
7990 <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
7991 <glossdef>
7992 <para>
7993 Specifies the path to the <filename>/usr</filename>
7994 subdirectory of the sysroot directory for the target
7995 for which the current recipe is being built
7996 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
7997 </para>
7998 </glossdef>
7999 </glossentry>
8000
8001 <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
8002 <glossdef>
8003 <para>
8004 Specifies the path to the
8005 <filename>/usr/include</filename> subdirectory of the
8006 sysroot directory for the target for which the current
8007 recipe being built
8008 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
8009 </para>
8010 </glossdef>
8011 </glossentry>
8012
8013 <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
8014 <glossdef>
8015 <para>
8016 Specifies the path to the <filename>/usr/include</filename>
8017 subdirectory of the sysroot directory for the build host.
8018 </para>
8019 </glossdef>
8020 </glossentry>
8021
8022 <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
8023 <glossdef>
8024 <para>
8025 Specifies the path to the <filename>/usr/lib</filename>
8026 subdirectory of the sysroot directory for the target for
8027 which the current recipe is being built
8028 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
8029 </para>
8030 </glossdef>
8031 </glossentry>
8032
8033 <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
8034 <glossdef>
8035 <para>
8036 Specifies the path to the <filename>/usr/lib</filename>
8037 subdirectory of the sysroot directory for the build host.
8038 </para>
8039 </glossdef>
8040 </glossentry>
8041
8042 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
8043 <glossdef>
8044 <para>
8045 The directory with kernel headers that are required to build out-of-tree
8046 modules.
8047 </para>
8048 </glossdef>
8049 </glossentry>
8050
8051 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
8052 <glossdef>
8053 <para>
8054 Specifies the base path used to create recipe stamp files.
8055 The path to an actual stamp file is constructed by evaluating this
8056 string and then appending additional information.
8057 Currently, the default assignment for <filename>STAMP</filename>
8058 as set in the <filename>meta/conf/bitbake.conf</filename> file
8059 is:
8060 <literallayout class='monospaced'>
8061 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
8062 </literallayout>
8063 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
8064 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
8065 <link linkend='var-PN'><filename>PN</filename></link>,
8066 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
8067 <link linkend='var-PV'><filename>PV</filename></link>, and
8068 <link linkend='var-PR'><filename>PR</filename></link> for related variable
8069 information.
8070 </para>
8071 </glossdef>
8072 </glossentry>
8073
8074 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
8075 <glossdef>
8076 <para>
8077 Specifies the base directory in which the OpenEmbedded
8078 build system places stamps.
8079 The default directory is
8080 <filename>${TMPDIR}/stamps</filename>.
8081 </para>
8082 </glossdef>
8083 </glossentry>
8084
8085 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
8086 <glossdef>
8087 <para>The short (72 characters or less) summary of the binary package for packaging
8088 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
8089 <filename>dpkg</filename>.
8090 By default, <filename>SUMMARY</filename> is used to define
8091 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
8092 variable if <filename>DESCRIPTION</filename> is not set
8093 in the recipe.
8094 </para>
8095 </glossdef>
8096 </glossentry>
8097
8098 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
8099 <glossdef>
8100 <para>
8101 Specifies the kernel boot default console.
8102 If you want to use a console other than the default,
8103 set this variable in your recipe as follows where "X" is
8104 the console number you want to use:
8105 <literallayout class='monospaced'>
8106 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
8107 </literallayout>
8108 </para>
8109
8110 <para>
8111 The
8112 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8113 class initially sets this variable to null but then checks
8114 for a value later.
8115 </para>
8116 </glossdef>
8117 </glossentry>
8118
8119 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
8120 <glossdef>
8121 <para>
8122 Lists additional options to add to the syslinux file.
8123 You need to set this variable in your recipe.
8124 If you want to list multiple options, separate the options
8125 with a semicolon character (<filename>;</filename>).
8126 </para>
8127
8128 <para>
8129 The
8130 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8131 class uses this variable to create a set of options.
8132 </para>
8133 </glossdef>
8134 </glossentry>
8135
8136 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
8137 <glossdef>
8138 <para>
8139 Specifies the alternate serial port or turns it off.
8140 To turn off serial, set this variable to an empty string
8141 in your recipe.
8142 The variable's default value is set in the
8143 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8144 as follows:
8145 <literallayout class='monospaced'>
8146 SYSLINUX_SERIAL ?= "0 115200"
8147 </literallayout>
8148 The class checks for and uses the variable as needed. </para>
8149 </glossdef>
8150 </glossentry>
8151
8152 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
8153 <glossdef>
8154 <para>
8155 An <filename>.LSS</filename> file used as the background
8156 for the VGA boot menu when you are using the boot menu.
8157 You need to set this variable in your recipe.
8158 </para>
8159
8160 <para>
8161 The
8162 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8163 class checks for this variable and if found, the
8164 OpenEmbedded build system installs the splash screen.
8165 </para>
8166 </glossdef>
8167 </glossentry>
8168
8169 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
8170 <glossdef>
8171 <para>
8172 Specifies the alternate console=tty... kernel boot argument.
8173 The variable's default value is set in the
8174 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
8175 as follows:
8176 <literallayout class='monospaced'>
8177 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
8178 </literallayout>
8179 The class checks for and uses the variable as needed.
8180 </para>
8181 </glossdef>
8182 </glossentry>
8183
8184 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
8185 <glossdef>
8186 <para>
8187 A list of functions to execute after files are staged into
8188 the sysroot.
8189 These functions are usually used to apply additional
8190 processing on the staged files, or to stage additional
8191 files.
8192 </para>
8193 </glossdef>
8194 </glossentry>
8195
8196 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
8197 <glossdef>
8198 <para>
8199 For recipes that inherit the
8200 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
8201 class, this variable specifies whether the service you have
8202 specified in
8203 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
8204 should be started automatically or not.
8205 By default, the service is enabled to automatically start
8206 at boot time.
8207 The default setting is in the
8208 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
8209 class as follows:
8210 <literallayout class='monospaced'>
8211 SYSTEMD_AUTO_ENABLE ??= "enable"
8212 </literallayout>
8213 You can disable the service by setting the variable to
8214 "disable".
8215 </para>
8216 </glossdef>
8217 </glossentry>
8218
8219 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
8220 <glossdef>
8221 <para>
8222 For recipes that inherit the
8223 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
8224 class, this variable locates the systemd unit files when
8225 they are not found in the main recipe's package.
8226 By default, the
8227 <filename>SYSTEMD_PACKAGES</filename> variable is set
8228 such that the systemd unit files are assumed to reside in
8229 the recipes main package:
8230 <literallayout class='monospaced'>
8231 SYSTEMD_PACKAGES ?= "${PN}"
8232 </literallayout>
8233 If these unit files are not in this recipe's main
8234 package, you need to use
8235 <filename>SYSTEMD_PACKAGES</filename> to list the package
8236 or packages in which the build system can find the systemd
8237 unit files.
8238 </para>
8239 </glossdef>
8240 </glossentry>
8241
8242 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
8243 <glossdef>
8244 <para>
8245 For recipes that inherit the
8246 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
8247 class, this variable specifies the systemd service name for
8248 a package.
8249 </para>
8250
8251 <para>
8252 When you specify this file in your recipe, use a package
8253 name override to indicate the package to which the value
8254 applies.
8255 Here is an example from the connman recipe:
8256 <literallayout class='monospaced'>
8257 SYSTEMD_SERVICE_${PN} = "connman.service"
8258 </literallayout>
8259 </para>
8260 </glossdef>
8261 </glossentry>
8262
8263 </glossdiv>
8264
8265 <glossdiv id='var-glossary-t'><title>T</title>
8266
8267 <glossentry id='var-T'><glossterm>T</glossterm>
8268 <glossdef>
8269 <para>This variable points to a directory were BitBake places
8270 temporary files, which consist mostly of task logs and
8271 scripts, when building a particular recipe.
8272 The variable is typically set as follows:
8273 <literallayout class='monospaced'>
8274 T = "${WORKDIR}/temp"
8275 </literallayout>
8276 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
8277 is the directory into which BitBake unpacks and builds the
8278 recipe.
8279 The default <filename>bitbake.conf</filename> file sets this variable.</para>
8280 <para>The <filename>T</filename> variable is not to be confused with
8281 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
8282 which points to the root of the directory tree where BitBake
8283 places the output of an entire build.
8284 </para>
8285 </glossdef>
8286 </glossentry>
8287
8288 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
8289 <glossdef>
8290 <para>
8291 The target machine's architecture.
8292 The OpenEmbedded build system supports many
8293 architectures.
8294 Here is an example list of architectures supported.
8295 This list is by no means complete as the architecture
8296 is configurable:
8297 <literallayout class='monospaced'>
8298 arm
8299 i586
8300 x86_64
8301 powerpc
8302 powerpc64
8303 mips
8304 mipsel
8305 </literallayout>
8306 For additional information on machine architectures, see
8307 the
8308 <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
8309 variable.
8310 </para>
8311 </glossdef>
8312 </glossentry>
8313
8314 <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
8315 <glossdef>
8316 <para>
8317 Specifies architecture-specific assembler flags for the
8318 target system.
8319 <filename>TARGET_AS_ARCH</filename> is initialized from
8320 <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
8321 by default in the BitBake configuration file
8322 (<filename>meta/conf/bitbake.conf</filename>):
8323 <literallayout class='monospaced'>
8324 TARGET_AS_ARCH = "${TUNE_ASARGS}"
8325 </literallayout>
8326 </para>
8327 </glossdef>
8328 </glossentry>
8329
8330 <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
8331 <glossdef>
8332 <para>
8333 Specifies architecture-specific C compiler flags for the
8334 target system.
8335 <filename>TARGET_CC_ARCH</filename> is initialized from
8336 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
8337 by default.
8338 <note>
8339 It is a common workaround to append
8340 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
8341 to <filename>TARGET_CC_ARCH</filename>
8342 in recipes that build software for the target that
8343 would not otherwise respect the exported
8344 <filename>LDFLAGS</filename> variable.
8345 </note>
8346 </para>
8347 </glossdef>
8348 </glossentry>
8349
8350 <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
8351 <glossdef>
8352 <para>
8353 This is a specific kernel compiler flag for a CPU or
8354 Application Binary Interface (ABI) tune.
8355 The flag is used rarely and only for cases where a
8356 userspace
8357 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
8358 is not compatible with the kernel compilation.
8359 The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
8360 allows the kernel (and associated modules) to use a
8361 different configuration.
8362 See the
8363 <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
8364 file in the
8365 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
8366 for an example.
8367 </para>
8368 </glossdef>
8369 </glossentry>
8370
8371 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
8372 <glossdef>
8373 <para>
8374 Specifies the flags to pass to the C compiler when building
8375 for the target.
8376 When building in the target context,
8377 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
8378 is set to the value of this variable by default.
8379 </para>
8380
8381 <para>
8382 Additionally, the SDK's environment setup script sets
8383 the
8384 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
8385 variable in the environment to the
8386 <filename>TARGET_CFLAGS</filename> value so that
8387 executables built using the SDK also have the flags
8388 applied.
8389 </para>
8390 </glossdef>
8391 </glossentry>
8392
8393 <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
8394 <glossdef>
8395 <para>
8396 Specifies the flags to pass to the C pre-processor
8397 (i.e. to both the C and the C++ compilers) when building
8398 for the target.
8399 When building in the target context,
8400 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
8401 is set to the value of this variable by default.
8402 </para>
8403
8404 <para>
8405 Additionally, the SDK's environment setup script sets
8406 the
8407 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
8408 variable in the environment to the
8409 <filename>TARGET_CPPFLAGS</filename> value so that
8410 executables built using the SDK also have the flags
8411 applied.
8412 </para>
8413 </glossdef>
8414 </glossentry>
8415
8416 <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
8417 <glossdef>
8418 <para>
8419 Specifies the flags to pass to the C++ compiler when
8420 building for the target.
8421 When building in the target context,
8422 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
8423 is set to the value of this variable by default.
8424 </para>
8425
8426 <para>
8427 Additionally, the SDK's environment setup script sets
8428 the
8429 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
8430 variable in the environment to the
8431 <filename>TARGET_CXXFLAGS</filename> value so that
8432 executables built using the SDK also have the flags
8433 applied.
8434 </para>
8435 </glossdef>
8436 </glossentry>
8437
8438 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
8439 <glossdef>
8440 <para>Specifies the method for handling FPU code.
8441 For FPU-less targets, which include most ARM CPUs, the variable must be
8442 set to "soft".
8443 If not, the kernel emulation gets used, which results in a performance penalty.</para>
8444 </glossdef>
8445 </glossentry>
8446
8447 <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
8448 <glossdef>
8449 <para>
8450 Specifies architecture-specific linker flags for the
8451 target system.
8452 <filename>TARGET_LD_ARCH</filename> is initialized from
8453 <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
8454 by default in the BitBake configuration file
8455 (<filename>meta/conf/bitbake.conf</filename>):
8456 <literallayout class='monospaced'>
8457 TARGET_LD_ARCH = "${TUNE_LDARGS}"
8458 </literallayout>
8459 </para>
8460 </glossdef>
8461 </glossentry>
8462
8463 <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
8464 <glossdef>
8465 <para>
8466 Specifies the flags to pass to the linker when building
8467 for the target.
8468 When building in the target context,
8469 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
8470 is set to the value of this variable by default.
8471 </para>
8472
8473 <para>
8474 Additionally, the SDK's environment setup script sets
8475 the
8476 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
8477 variable in the environment to the
8478 <filename>TARGET_LDFLAGS</filename> value so that
8479 executables built using the SDK also have the flags
8480 applied.
8481 </para>
8482 </glossdef>
8483 </glossentry>
8484
8485 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
8486 <glossdef>
8487 <para>Specifies the target's operating system.
8488 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
8489 to "linux-uclibc" for <filename>uclibc</filename>.
8490 For ARM/EABI targets, there are also "linux-gnueabi" and
8491 "linux-uclibc-gnueabi" values possible.</para>
8492 </glossdef>
8493 </glossentry>
8494
8495 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
8496 <glossdef>
8497 <para>
8498 Specifies the GNU standard C library (<filename>libc</filename>)
8499 variant to use during the build process.
8500 This variable replaces <filename>POKYLIBC</filename>, which is no longer
8501 supported.
8502 </para>
8503 <para>
8504 You can select "eglibc" or "uclibc".
8505 <note>
8506 This release of the Yocto Project does not support the
8507 <filename>glibc</filename> implementation of <filename>libc</filename>.
8508 </note>
8509 </para>
8510 </glossdef>
8511 </glossentry>
8512
8513 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
8514 <glossdef>
8515 <para>
8516 Specifies the toolchain selector.
8517 <filename>TCMODE</filename> controls the characteristics
8518 of the generated packages and images by telling the
8519 OpenEmbedded build system which toolchain profile to use.
8520 By default, the OpenEmbedded build system builds its own
8521 internal toolchain.
8522 The variable's default value is "default", which uses
8523 that internal toolchain.
8524 <note>
8525 If <filename>TCMODE</filename> is set to a value
8526 other than "default", then it is your responsibility
8527 to ensure that the toolchain is compatible with the
8528 default toolchain.
8529 Using older or newer versions of these components
8530 might cause build problems.
8531 See the
8532 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
8533 for the specific components with which the toolchain
8534 must be compatible.
8535 </note>
8536 </para>
8537
8538 <para>
8539 With additional layers, it is possible to use a pre-compiled
8540 external toolchain.
8541 One example is the Sourcery G++ Toolchain.
8542 The support for this toolchain resides in the separate
8543 <filename>meta-sourcery</filename> layer at
8544 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
8545 You can use <filename>meta-sourcery</filename> as a
8546 template for adding support for other external toolchains.
8547 </para>
8548
8549 <para>
8550 The <filename>TCMODE</filename> variable points the build
8551 system to a file in
8552 <filename>conf/distro/include/tcmode-${TCMODE}.inc</filename>.
8553 Thus, for <filename>meta-sourcery</filename>,
8554 which has <filename>conf/distro/include/tcmode-external-sourcery.inc</filename>,
8555 you would set the variable as follows:
8556 <literallayout class='monospaced'>
8557 TCMODE ?= "external-sourcery"
8558 </literallayout>
8559 </para>
8560
8561 <para>
8562 The variable is similar to
8563 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
8564 which controls the variant of the GNU standard C library
8565 (<filename>libc</filename>) used during the build process:
8566 <filename>eglibc</filename> or <filename>uclibc</filename>.
8567 </para>
8568 </glossdef>
8569 </glossentry>
8570
8571 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
8572 <glossdef>
8573 <para>
8574 The location the OpenEmbedded build system uses to export
8575 tests when the
8576 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
8577 variable is set to "1".
8578 </para>
8579
8580 <para>
8581 The <filename>TEST_EXPORT_DIR</filename> variable defaults
8582 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
8583 </para>
8584 </glossdef>
8585 </glossentry>
8586
8587 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
8588 <glossdef>
8589 <para>
8590 Specifies to export the tests only.
8591 Set this variable to "1" if you do not want to run the
8592 tests but you want them to be exported in a manner that
8593 you to run them outside of the build system.
8594 </para>
8595 </glossdef>
8596 </glossentry>
8597
8598 <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
8599 <glossdef>
8600 <para>
8601 Automatically runs the series of automated tests for
8602 images when an image is successfully built.
8603 </para>
8604
8605 <para>
8606 These tests are written in Python making use of the
8607 <filename>unittest</filename> module, and the majority of
8608 them run commands on the target system over
8609 <filename>ssh</filename>.
8610 You can set this variable to "1" in your
8611 <filename>local.conf</filename> file in the
8612 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
8613 to have the OpenEmbedded build system automatically run
8614 these tests after an image successfully builds:
8615 <literallayout class='monospaced'>
8616 TEST_IMAGE = "1"
8617 </literallayout>
8618 For more information on enabling, running, and writing
8619 these tests, see the
8620 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
8621 section in the Yocto Project Development Manual and the
8622 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
8623 section.
8624 </para>
8625 </glossdef>
8626 </glossentry>
8627
8628 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
8629 <glossdef>
8630 <para>
8631 Holds the SSH log and the boot log for QEMU machines.
8632 The <filename>TEST_LOG_DIR</filename> variable defaults
8633 to <filename>"${WORKDIR}/testimage"</filename>.
8634 <note>
8635 Actual test results reside in the task log
8636 (<filename>log.do_testimage</filename>), which is in
8637 the <filename>${WORKDIR}/temp/</filename> directory.
8638 </note>
8639 </para>
8640 </glossdef>
8641 </glossentry>
8642
8643 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
8644 <glossdef>
8645 <para>
8646 The time in seconds allowed for an image to boot before
8647 automated runtime tests begin to run against an
8648 image.
8649 The default timeout period to allow the boot process to
8650 reach the login prompt is 500 seconds.
8651 You can specify a different value in the
8652 <filename>local.conf</filename> file.
8653 </para>
8654
8655 <para>
8656 For more information on testing images, see the
8657 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
8658 section in the Yocto Project Development Manual.
8659 </para>
8660 </glossdef>
8661 </glossentry>
8662
8663 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
8664 <glossdef>
8665 <para>
8666 The IP address of the build machine (host machine).
8667 This IP address is usually automatically detected.
8668 However, if detection fails, this variable needs to be set
8669 to the IP address of the build machine (i.e. where
8670 the build is taking place).
8671 <note>
8672 The <filename>TEST_SERVER_IP</filename> variable
8673 is only used for a small number of tests such as
8674 the "smart" test suite, which needs to download
8675 packages from <filename>DEPLOY_DIR/rpm</filename>.
8676 </note>
8677 </para>
8678 </glossdef>
8679 </glossentry>
8680
8681 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
8682 <glossdef>
8683 <para>
8684 Specifies the target controller to use when running tests
8685 against a test image.
8686 The default controller to use is "qemu":
8687 <literallayout class='monospaced'>
8688 TEST_TARGET = "qemu"
8689 </literallayout>
8690 A target controller is a class that defines how an
8691 image gets deployed on a target and how a target is started.
8692 A layer can extend the controllers by adding a module
8693 in the layer's <filename>/lib/oeqa/controllers</filename>
8694 directory and by inheriting the
8695 <filename>BaseTarget</filename> class, which is an abstract
8696 class that cannot be used as a value of
8697 <filename>TEST_TARGET</filename>.
8698 </para>
8699
8700 <para>
8701 You can provide the following arguments with
8702 <filename>TEST_TARGET</filename>:
8703 <itemizedlist>
8704 <listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>
8705 Boots a QEMU image and runs the tests.
8706 See the
8707 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
8708 section in the Yocto Project Development Manual for
8709 more information.
8710 </para></listitem>
8711 <listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>
8712 Runs the tests on target hardware that is already
8713 up and running.
8714 The hardware can be on the network or it can be
8715 a device running an image on QEMU.
8716 You must also set
8717 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
8718 when you use "simpleremote" or "SimpleRemoteTarget".
8719 <note>
8720 This argument is defined in
8721 <filename>meta/lib/oeqa/targetcontrol.py</filename>.
8722 The small caps names are kept for compatibility
8723 reasons.
8724 </note>
8725 </para></listitem>
8726 <listitem><para><emphasis>"GummibootTarget":</emphasis>
8727 Automatically deploys and runs tests on an
8728 EFI-enabled machine that has a master image
8729 installed.
8730 <note>
8731 This argument is defined in
8732 <filename>meta/lib/oeqa/controllers/masterimage.py</filename>.
8733 </note>
8734 </para></listitem>
8735 </itemizedlist>
8736 </para>
8737
8738 <para>
8739 For information on running tests on hardware, see the
8740 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
8741 section in the Yocto Project Development Manual.
8742 </para>
8743 </glossdef>
8744 </glossentry>
8745
8746 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
8747 <glossdef>
8748 <para>
8749 The IP address of your hardware under test.
8750 The <filename>TEST_TARGET_IP</filename> variable has no
8751 effect when
8752 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
8753 is set to "qemu".
8754 </para>
8755
8756 <para>
8757 When you specify the IP address, you can also include a
8758 port.
8759 Here is an example:
8760 <literallayout class='monospaced'>
8761 TEST_TARGET_IP = "192.168.1.4:2201"
8762 </literallayout>
8763 Specifying a port is useful when SSH is started on a
8764 non-standard port or in cases when your hardware under test
8765 is behind a firewall or network that is not directly
8766 accessible from your host and you need to do port address
8767 translation.
8768 </para>
8769 </glossdef>
8770 </glossentry>
8771
8772 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
8773 <glossdef>
8774 <para>
8775 An ordered list of tests (modules) to run against
8776 an image when performing automated runtime testing.
8777 </para>
8778
8779 <para>
8780 The OpenEmbedded build system provides a core set of tests
8781 that can be used against images.
8782 <note>
8783 Currently, there is only support for running these tests
8784 under QEMU.
8785 </note>
8786 Tests include <filename>ping</filename>,
8787 <filename>ssh</filename>, <filename>df</filename> among
8788 others.
8789 You can add your own tests to the list of tests by
8790 appending <filename>TEST_SUITES</filename> as follows:
8791 <literallayout class='monospaced'>
8792 TEST_SUITES_append = " mytest"
8793 </literallayout>
8794 Alternatively, you can provide the "auto" option to
8795 have all applicable tests run against the image.
8796 <literallayout class='monospaced'>
8797 TEST_SUITES_append = " auto"
8798 </literallayout>
8799 Using this option causes the build system to automatically
8800 run tests that are applicable to the image.
8801 Tests that are not applicable are skipped.
8802 </para>
8803
8804 <para>
8805 The order in which tests are run is important.
8806 Tests that depend on another test must appear later in the
8807 list than the test on which they depend.
8808 For example, if you append the list of tests with two
8809 tests (<filename>test_A</filename> and
8810 <filename>test_B</filename>) where
8811 <filename>test_B</filename> is dependent on
8812 <filename>test_A</filename>, then you must order the tests
8813 as follows:
8814 <literallayout class='monospaced'>
8815 TEST_SUITES = " test_A test_B"
8816 </literallayout>
8817 </para>
8818
8819 <para>
8820 For more information on testing images, see the
8821 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
8822 section in the Yocto Project Development Manual.
8823 </para>
8824 </glossdef>
8825 </glossentry>
8826
8827 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
8828 <glossdef>
8829 <para>
8830 The directory in which the file BitBake is currently
8831 parsing is located.
8832 Do not manually set this variable.
8833 </para>
8834 </glossdef>
8835 </glossentry>
8836
8837 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
8838 <glossdef>
8839 <para>
8840 This variable is the base directory the OpenEmbedded
8841 build system uses for all build output and intermediate
8842 files (other than the shared state cache).
8843 By default, the <filename>TMPDIR</filename> variable points
8844 to <filename>tmp</filename> within the
8845 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
8846 </para>
8847
8848 <para>
8849 If you want to establish this directory in a location other
8850 than the default, you can uncomment and edit the following
8851 statement in the
8852 <filename>conf/local.conf</filename> file in the
8853 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
8854 <literallayout class='monospaced'>
8855 #TMPDIR = "${TOPDIR}/tmp"
8856 </literallayout>
8857 An example use for this scenario is to set
8858 <filename>TMPDIR</filename> to a local disk, which does
8859 not use NFS, while having the Build Directory use NFS.
8860 </para>
8861
8862 <para>
8863 The filesystem used by <filename>TMPDIR</filename> must
8864 have standard filesystem semantics (i.e. mixed-case files
8865 are unique, POSIX file locking, and persistent inodes).
8866 Due to various issues with NFS and bugs in some
8867 implementations, NFS does not meet this minimum
8868 requirement.
8869 Consequently, <filename>TMPDIR</filename> cannot be on
8870 NFS.
8871 </para>
8872 </glossdef>
8873 </glossentry>
8874
8875 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
8876 <glossdef>
8877 <para>
8878 This variable lists packages the OpenEmbedded build system
8879 uses when building an SDK, which contains a
8880 cross-development environment.
8881 The packages specified by this variable are part of the
8882 toolchain set that runs on the
8883 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
8884 and each package should usually have the prefix
8885 "nativesdk-".
8886 When building an SDK using
8887 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
8888 a default list of packages is set in this variable, but
8889 you can add additional packages to the list.
8890 </para>
8891
8892 <para>
8893 For background information on cross-development toolchains
8894 in the Yocto Project development environment, see the
8895 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
8896 section.
8897 For information on setting up a cross-development
8898 environment, see the
8899 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
8900 section in the Yocto Project Application Developer's Guide.
8901 </para>
8902 </glossdef>
8903 </glossentry>
8904
8905 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
8906 <glossdef>
8907 <para>
8908 This variable lists packages the OpenEmbedded build system
8909 uses when it creates the target part of an SDK
8910 (i.e. the part built for the target hardware), which
8911 includes libraries and headers.
8912 </para>
8913
8914 <para>
8915 For background information on cross-development toolchains
8916 in the Yocto Project development environment, see the
8917 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
8918 section.
8919 For information on setting up a cross-development
8920 environment, see the
8921 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
8922 section in the Yocto Project Application Developer's Guide.
8923 </para>
8924 </glossdef>
8925 </glossentry>
8926
8927 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
8928 <glossdef>
8929 <para>
8930 The top-level
8931 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
8932 BitBake automatically sets this variable when you
8933 initialize your build environment using either
8934 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
8935 or
8936 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
8937 </para>
8938 </glossdef>
8939 </glossentry>
8940
8941 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
8942 <glossdef>
8943 <para>
8944 A sanitized version of
8945 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
8946 This variable is used where the architecture is needed in
8947 a value where underscores are not allowed, for example
8948 within package filenames.
8949 In this case, dash characters replace any underscore
8950 characters used in TARGET_ARCH.
8951 </para>
8952
8953 <para>
8954 Do not edit this variable.
8955 </para>
8956 </glossdef>
8957 </glossentry>
8958
8959 <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
8960 <glossdef>
8961 <para>
8962 The GNU canonical architecture for a specific architecture
8963 (i.e. <filename>arm</filename>,
8964 <filename>armeb</filename>,
8965 <filename>mips</filename>,
8966 <filename>mips64</filename>, and so forth).
8967 BitBake uses this value to setup configuration.
8968 </para>
8969
8970 <para>
8971 <filename>TUNE_ARCH</filename> definitions are specific to
8972 a given architecture.
8973 The definitions can be a single static definition, or
8974 can be dynamically adjusted.
8975 You can see details for a given CPU family by looking at
8976 the architecture's <filename>README</filename> file.
8977 For example, the
8978 <filename>meta/conf/machine/include/mips/README</filename>
8979 file in the
8980 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
8981 provides information for <filename>TUNE_ARCH</filename>
8982 specific to the <filename>mips</filename> architecture.
8983 </para>
8984
8985 <para>
8986 <filename>TUNE_ARCH</filename> is tied closely to
8987 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
8988 which defines the target machine's architecture.
8989 The BitBake configuration file
8990 (<filename>meta/conf/bitbake.conf</filename>) sets
8991 <filename>TARGET_ARCH</filename> as follows:
8992 <literallayout class='monospaced'>
8993 TARGET_ARCH = "${TUNE_ARCH}"
8994 </literallayout>
8995 </para>
8996
8997 <para>
8998 The following list, which is by no means complete since
8999 architectures are configurable, shows supported machine
9000 architectures:
9001 <literallayout class='monospaced'>
9002 arm
9003 i586
9004 x86_64
9005 powerpc
9006 powerpc64
9007 mips
9008 mipsel
9009 </literallayout>
9010 </para>
9011 </glossdef>
9012 </glossentry>
9013
9014 <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
9015 <glossdef>
9016 <para>
9017 Specifies architecture-specific assembler flags for
9018 the target system.
9019 The set of flags is based on the selected tune features.
9020 <filename>TUNE_ASARGS</filename> is set using
9021 the tune include files, which are typically under
9022 <filename>meta/conf/machine/include/</filename> and are
9023 influenced through <filename>TUNE_FEATURES</filename>.
9024 For example, the
9025 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
9026 file defines the flags for the x86 architecture as follows:
9027 <literallayout class='monospaced'>
9028 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
9029 </literallayout>
9030 <note>
9031 Board Support Packages (BSPs) can supply their own
9032 set of flags.
9033 </note>
9034 </para>
9035 </glossdef>
9036 </glossentry>
9037
9038 <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
9039 <glossdef>
9040 <para>
9041 Specifies architecture-specific C compiler flags for
9042 the target system.
9043 The set of flags is based on the selected tune features.
9044 <filename>TUNE_CCARGS</filename> is set using
9045 the tune include files, which are typically under
9046 <filename>meta/conf/machine/include/</filename> and are
9047 influenced through <filename>TUNE_FEATURES</filename>.
9048 <note>
9049 Board Support Packages (BSPs) can supply their own
9050 set of flags.
9051 </note>
9052 </para>
9053 </glossdef>
9054 </glossentry>
9055
9056 <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
9057 <glossdef>
9058 <para>
9059 Specifies architecture-specific linker flags for
9060 the target system.
9061 The set of flags is based on the selected tune features.
9062 <filename>TUNE_LDARGS</filename> is set using
9063 the tune include files, which are typically under
9064 <filename>meta/conf/machine/include/</filename> and are
9065 influenced through <filename>TUNE_FEATURES</filename>.
9066 For example, the
9067 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
9068 file defines the flags for the x86 architecture as follows:
9069 <literallayout class='monospaced'>
9070 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
9071 </literallayout>
9072 <note>
9073 Board Support Packages (BSPs) can supply their own
9074 set of flags.
9075 </note>
9076 </para>
9077 </glossdef>
9078 </glossentry>
9079
9080 <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
9081 <glossdef>
9082 <para>
9083 Features used to "tune" a compiler for optimal use
9084 given a specific processor.
9085 The features are defined within the tune files and allow
9086 arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
9087 dynamically generated based on the features.
9088 </para>
9089
9090 <para>
9091 The OpenEmbedded build system verifies the features
9092 to be sure they are not conflicting and that they are
9093 supported.
9094 </para>
9095
9096 <para>
9097 The BitBake configuration file
9098 (<filename>meta/conf/bitbake.conf</filename>) defines
9099 <filename>TUNE_FEATURES</filename> as follows:
9100 <literallayout class='monospaced'>
9101 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
9102 </literallayout>
9103 See the
9104 <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
9105 variable for more information.
9106 </para>
9107 </glossdef>
9108 </glossentry>
9109
9110 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
9111 <glossdef>
9112 <para>
9113 The package architecture understood by the packaging
9114 system to define the architecture, ABI, and tuning of
9115 output packages.
9116 </para>
9117 </glossdef>
9118 </glossentry>
9119
9120 <glossentry id='var-TUNE_PKGARCH_tune'><glossterm>TUNE_PKGARCH_tune</glossterm>
9121 <glossdef>
9122 <para>
9123 The CPU or Application Binary Interface (ABI) specific
9124 tuning of the
9125 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
9126 </para>
9127
9128 <para>
9129 These tune-specific package architectures are defined in
9130 the machine include files.
9131 Here is an example of the "core2-32" tuning as used
9132 in the
9133 <filename>meta/conf/machine/include/tune-core2.inc</filename>
9134 file:
9135 <literallayout class='monospaced'>
9136 TUNE_PKGARCH_tune-core2-32 = "core2-32"
9137 </literallayout>
9138 </para>
9139 </glossdef>
9140 </glossentry>
9141
9142 <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
9143 <glossdef>
9144 <para>
9145 An underlying Application Binary Interface (ABI) used by
9146 a particular tuning in a given toolchain layer.
9147 Providers that use prebuilt libraries can use the
9148 <filename>TUNEABI</filename>,
9149 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
9150 and
9151 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
9152 variables to check compatibility of tunings against their
9153 selection of libraries.
9154 </para>
9155
9156 <para>
9157 If <filename>TUNEABI</filename> is undefined, then every
9158 tuning is allowed.
9159 See the
9160 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
9161 class to see how the variable is used.
9162 </para>
9163 </glossdef>
9164 </glossentry>
9165
9166 <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
9167 <glossdef>
9168 <para>
9169 If set, the OpenEmbedded system ignores the
9170 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
9171 variable.
9172 Providers that use prebuilt libraries can use the
9173 <filename>TUNEABI_OVERRIDE</filename>,
9174 <filename>TUNEABI_WHITELIST</filename>,
9175 and
9176 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
9177 variables to check compatibility of a tuning against their
9178 selection of libraries.
9179 </para>
9180
9181 <para>
9182 See the
9183 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
9184 class to see how the variable is used.
9185 </para>
9186 </glossdef>
9187 </glossentry>
9188
9189 <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
9190 <glossdef>
9191 <para>
9192 A whitelist of permissible
9193 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
9194 values.
9195 If <filename>TUNEABI_WHITELIST</filename> is not set,
9196 all tunes are allowed.
9197 Providers that use prebuilt libraries can use the
9198 <filename>TUNEABI_WHITELIST</filename>,
9199 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
9200 and <filename>TUNEABI</filename> variables to check
9201 compatibility of a tuning against their selection of
9202 libraries.
9203 </para>
9204
9205 <para>
9206 See the
9207 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
9208 class to see how the variable is used.
9209 </para>
9210 </glossdef>
9211 </glossentry>
9212
9213 <glossentry id='var-TUNECONFLICT'><glossterm>TUNECONFLICT[&lt;feature&gt;]</glossterm>
9214 <glossdef>
9215 <para>
9216 Specifies CPU or Application Binary Interface (ABI)
9217 tuning features that conflict with &gt;feature&lt;.
9218 </para>
9219
9220 <para>
9221 Known tuning conflicts are specified in the machine include
9222 files in the
9223 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
9224 Here is an example from the
9225 <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
9226 include file that lists the "o32" and "n64" features as
9227 conflicting with the "n32" feature:
9228 <literallayout class='monospaced'>
9229 TUNECONFLICTS[n32] = "o32 n64"
9230 </literallayout>
9231 </para>
9232 </glossdef>
9233 </glossentry>
9234
9235 <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[&lt;feature&gt;]</glossterm>
9236 <glossdef>
9237 <para>
9238 Specifies a valid CPU or Application Binary Interface (ABI)
9239 tuning feature.
9240 The specified feature is stored as a flag.
9241 Valid features are specified in the machine include files
9242 (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
9243 Here is an example from that file:
9244 <literallayout class='monospaced'>
9245 TUNEVALID[bigendian] = "Enable big-endian mode."
9246 </literallayout>
9247 See the machine include files in the
9248 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
9249 for these features.
9250 </para>
9251 </glossdef>
9252 </glossentry>
9253
9254 </glossdiv>
9255
9256 <glossdiv id='var-glossary-u'><title>U</title>
9257
9258 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
9259 <glossdef>
9260 <para>
9261 Configures the
9262 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
9263 and can also define
9264 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
9265 for individual cases.
9266 </para>
9267
9268 <para>
9269 Following is an example from the
9270 <filename>meta-fsl-arm</filename> layer.
9271 <literallayout class='monospaced'>
9272 UBOOT_CONFIG ??= "sd"
9273 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
9274 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
9275 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
9276 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
9277 </literallayout>
9278 In this example, "sd" is selected as the configuration
9279 of the possible four for the
9280 <filename>UBOOT_MACHINE</filename>.
9281 The "sd" configuration defines "mx6qsabreauto_config"
9282 as the value for <filename>UBOOT_MACHINE</filename>, while
9283 the "sdcard" specifies the
9284 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
9285 image.
9286 </para>
9287
9288 <para>
9289 For more information on how the
9290 <filename>UBOOT_CONFIG</filename> is handled, see the
9291 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
9292 class.
9293 </para>
9294 </glossdef>
9295 </glossentry>
9296
9297 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
9298 <glossdef>
9299 <para>
9300 Specifies the entry point for the U-Boot image.
9301 During U-Boot image creation, the
9302 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
9303 as a command-line parameter to the
9304 <filename>uboot-mkimage</filename> utility.
9305 </para>
9306 </glossdef>
9307 </glossentry>
9308
9309 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
9310 <glossdef>
9311 <para>
9312 Specifies the load address for the U-Boot image.
9313 During U-Boot image creation, the
9314 <filename>UBOOT_LOADADDRESS</filename> variable is passed
9315 as a command-line parameter to the
9316 <filename>uboot-mkimage</filename> utility.
9317 </para>
9318 </glossdef>
9319 </glossentry>
9320
9321 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
9322 <glossdef>
9323 <para>
9324 Appends a string to the name of the local version of the
9325 U-Boot image.
9326 For example, assuming the version of the U-Boot image
9327 built was "2013.10, the full version string reported by
9328 U-Boot would be "2013.10-yocto" given the following
9329 statement:
9330 <literallayout class='monospaced'>
9331 UBOOT_LOCALVERSION = "-yocto"
9332 </literallayout>
9333 </para>
9334 </glossdef>
9335 </glossentry>
9336
9337 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
9338 <glossdef>
9339 <para>
9340 Specifies the value passed on the
9341 <filename>make</filename> command line when building
9342 a U-Boot image.
9343 The value indicates the target platform configuration.
9344 You typically set this variable from the machine
9345 configuration file (i.e.
9346 <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
9347 </para>
9348
9349 <para>
9350 Please see the "Selection of Processor Architecture and
9351 Board Type" section in the U-Boot README for valid values
9352 for this variable.
9353 </para>
9354 </glossdef>
9355 </glossentry>
9356
9357 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
9358 <glossdef>
9359 <para>
9360 Specifies the target called in the
9361 <filename>Makefile</filename>.
9362 The default target is "all".
9363 </para>
9364 </glossdef>
9365 </glossentry>
9366
9367 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
9368 <glossdef>
9369 <para>
9370 Points to the generated U-Boot extension.
9371 For example, <filename>u-boot.sb</filename> has a
9372 <filename>.sb</filename> extension.
9373 </para>
9374
9375 <para>
9376 The default U-Boot extension is
9377 <filename>.bin</filename>
9378 </para>
9379 </glossdef>
9380 </glossentry>
9381
9382 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
9383 <glossdef>
9384 <para>
9385 Specifies the target used for building U-Boot.
9386 The target is passed directly as part of the "make" command
9387 (e.g. SPL and AIS).
9388 If you do not specifically set this variable, the
9389 OpenEmbedded build process passes and uses "all" for the
9390 target during the U-Boot building process.
9391 </para>
9392 </glossdef>
9393 </glossentry>
9394
9395 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
9396 <glossdef>
9397 <para>
9398 A list of classes to globally inherit.
9399 These classes are used by the OpenEmbedded build system
9400 to enable extra features (e.g.
9401 <filename>buildstats</filename>,
9402 <filename>image-mklibs</filename>, and so forth).
9403 </para>
9404
9405 <para>
9406 The default list is set in your
9407 <filename>local.conf</filename> file:
9408 <literallayout class='monospaced'>
9409 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
9410 </literallayout>
9411 For more information, see
9412 <filename>meta-yocto/conf/local.conf.sample</filename> in
9413 the
9414 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
9415 </para>
9416 </glossdef>
9417 </glossentry>
9418
9419 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
9420 <glossdef>
9421 <para>
9422 Forces the OpenEmbedded build system to produce an error
9423 if the user identification (<filename>uid</filename>) and
9424 group identification (<filename>gid</filename>) values
9425 are not defined in <filename>files/passwd</filename>
9426 and <filename>files/group</filename> files.
9427 </para>
9428
9429 <para>
9430 The default behavior for the build system is to dynamically
9431 apply <filename>uid</filename> and
9432 <filename>gid</filename> values.
9433 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
9434 variable is by default not set.
9435 If you plan on using statically assigned
9436 <filename>gid</filename> and <filename>uid</filename>
9437 values, you should set
9438 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
9439 your <filename>local.conf</filename> file as
9440 follows:
9441 <literallayout class='monospaced'>
9442 USERADD_ERROR_DYNAMIC = "1"
9443 </literallayout>
9444 Overriding the default behavior implies you are going to
9445 also take steps to set static <filename>uid</filename> and
9446 <filename>gid</filename> values through use of the
9447 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
9448 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
9449 and
9450 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
9451 variables.
9452 </para>
9453 </glossdef>
9454 </glossentry>
9455
9456 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
9457 <glossdef>
9458 <para>
9459 Specifies a password file to use for obtaining static
9460 group identification (<filename>gid</filename>) values
9461 when the OpenEmbedded build system adds a group to the
9462 system during package installation.
9463 </para>
9464
9465 <para>
9466 When applying static group identification
9467 (<filename>gid</filename>) values, the OpenEmbedded build
9468 system looks in
9469 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
9470 for a <filename>files/group</filename> file and then applies
9471 those <filename>uid</filename> values.
9472 Set the variable as follows in your
9473 <filename>local.conf</filename> file:
9474 <literallayout class='monospaced'>
9475 USERADD_GID_TABLES = "files/group"
9476 </literallayout>
9477 </para>
9478
9479 <note>
9480 Setting the
9481 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
9482 variable to "useradd-staticids" causes the build system
9483 to use static <filename>gid</filename> values.
9484 </note>
9485 </glossdef>
9486 </glossentry>
9487
9488 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
9489 <glossdef>
9490 <para>
9491 Specifies a password file to use for obtaining static
9492 user identification (<filename>uid</filename>) values
9493 when the OpenEmbedded build system adds a user to the
9494 system during package installation.
9495 </para>
9496
9497 <para>
9498 When applying static user identification
9499 (<filename>uid</filename>) values, the OpenEmbedded build
9500 system looks in
9501 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
9502 for a <filename>files/passwd</filename> file and then applies
9503 those <filename>uid</filename> values.
9504 Set the variable as follows in your
9505 <filename>local.conf</filename> file:
9506 <literallayout class='monospaced'>
9507 USERADD_UID_TABLES = "files/passwd"
9508 </literallayout>
9509 </para>
9510
9511 <note>
9512 Setting the
9513 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
9514 variable to "useradd-staticids" causes the build system
9515 to use static <filename>uid</filename> values.
9516 </note>
9517 </glossdef>
9518 </glossentry>
9519
9520 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
9521 <glossdef>
9522 <para>
9523 When a recipe inherits the
9524 <filename>useradd</filename> class, this variable
9525 specifies the individual packages within the recipe that
9526 require users and/or groups to be added.
9527 </para>
9528
9529 <para>
9530 You must set this variable if the recipe inherits the
9531 class.
9532 For example, the following enables adding a user for the
9533 main package in a recipe:
9534 <literallayout class='monospaced'>
9535 USERADD_PACKAGES = "${PN}"
9536 </literallayout>
9537 <note>
9538 If follows that if you are going to use the
9539 <filename>USERADD_PACKAGES</filename> variable,
9540 you need to set one or more of the
9541 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
9542 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
9543 or
9544 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
9545 variables.
9546 </note>
9547 </para>
9548
9549 </glossdef>
9550 </glossentry>
9551
9552 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
9553 <glossdef>
9554 <para>
9555 When a recipe inherits the
9556 <filename>useradd</filename> class, this variable
9557 specifies for a package what parameters should be passed
9558 to the <filename>useradd</filename> command
9559 if you wish to add a user to the system when the package
9560 is installed.
9561 </para>
9562
9563 <para>
9564 Here is an example from the <filename>dbus</filename>
9565 recipe:
9566 <literallayout class='monospaced'>
9567 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
9568 --no-create-home --shell /bin/false \
9569 --user-group messagebus"
9570 </literallayout>
9571 For information on the standard Linux shell command
9572 <filename>useradd</filename>, see
9573 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
9574 </para>
9575 </glossdef>
9576 </glossentry>
9577
9578 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
9579 <glossdef>
9580 <para>
9581 When set to "useradd-staticids", causes the
9582 OpenEmbedded build system to base all user and group
9583 additions on a static
9584 <filename>passwd</filename> and
9585 <filename>group</filename> files found in
9586 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
9587 </para>
9588
9589 <para>
9590 To use static user identification (<filename>uid</filename>)
9591 and group identification (<filename>gid</filename>)
9592 values, set the variable
9593 as follows in your <filename>local.conf</filename> file:
9594 <literallayout class='monospaced'>
9595 USERADDEXTENSION = "useradd-staticids"
9596 </literallayout>
9597 <note>
9598 Setting this variable to use static
9599 <filename>uid</filename> and <filename>gid</filename>
9600 values causes the OpenEmbedded build system to employ
9601 the
9602 <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link>
9603 class.
9604 </note>
9605 </para>
9606
9607 <para>
9608 If you use static <filename>uid</filename> and
9609 <filename>gid</filename> information, you must also
9610 specify the <filename>files/passwd</filename> and
9611 <filename>files/group</filename> files by setting the
9612 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
9613 and
9614 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
9615 variables.
9616 Additionally, you should also set the
9617 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
9618 variable.
9619 </para>
9620 </glossdef>
9621 </glossentry>
9622
9623 </glossdiv>
9624
9625<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
9626<!-- </glossdiv>-->
9627
9628 <glossdiv id='var-glossary-w'><title>W</title>
9629
9630 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
9631 <glossdef>
9632 <para>
9633 Specifies the quality assurance checks whose failures are
9634 reported as warnings by the OpenEmbedded build system.
9635 You set this variable in your distribution configuration
9636 file.
9637 For a list of the checks you can control with this variable,
9638 see the
9639 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
9640 section.
9641 </para>
9642 </glossdef>
9643 </glossentry>
9644
9645 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
9646 <glossdef>
9647 <para>
9648 The pathname of the work directory in which the OpenEmbedded
9649 build system builds a recipe.
9650 This directory is located within the
9651 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
9652 directory structure and is specific to the recipe being
9653 built and the system for which it is being built.
9654 </para>
9655
9656 <para>
9657 The <filename>WORKDIR</filename> directory is defined as
9658 follows:
9659 <literallayout class='monospaced'>
9660 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
9661 </literallayout>
9662 The actual directory depends on several things:
9663 <itemizedlist>
9664 <listitem><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>:
9665 The top-level build output directory</listitem>
9666 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
9667 The target system identifier</listitem>
9668 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
9669 The recipe name</listitem>
9670 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
9671 The epoch - (if
9672 <link linkend='var-PE'><filename>PE</filename></link>
9673 is not specified, which is usually the case for most
9674 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
9675 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
9676 The recipe version</listitem>
9677 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
9678 The recipe revision</listitem>
9679 </itemizedlist>
9680 </para>
9681
9682 <para>
9683 As an example, assume a Source Directory top-level folder
9684 name <filename>poky</filename>, a default Build Directory at
9685 <filename>poky/build</filename>, and a
9686 <filename>qemux86-poky-linux</filename> machine target
9687 system.
9688 Furthermore, suppose your recipe is named
9689 <filename>foo_1.3.0-r0.bb</filename>.
9690 In this case, the work directory the build system uses to
9691 build the package would be as follows:
9692 <literallayout class='monospaced'>
9693 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
9694 </literallayout>
9695 </para>
9696 </glossdef>
9697 </glossentry>
9698
9699 </glossdiv>
9700
9701<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
9702<!-- </glossdiv>-->
9703
9704<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
9705<!-- </glossdiv>-->
9706
9707<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
9708<!-- </glossdiv>-->
9709
9710</glossary>
9711</chapter>
9712<!--
9713vim: expandtab tw=80 ts=4
9714-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 15:20:08 +0000