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