blob: a5064807e50c6dacfb1017977c9a4e46cc79e236 [file] [log] [blame]
Andrew Geissler4873add2020-11-02 18:44:49 -06001<!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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<!-- Dummy chapter -->
7<chapter id='ref-variables-glos'>
8
9<title>Variables Glossary</title>
10
11<para>
12 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
13 of their function and contents.
14</para>
15
16<glossary id='ref-variables-glossary'>
17
18
19 <para>
20 <link linkend='var-ABIEXTENSION'>A</link>
21 <link linkend='var-B'>B</link>
22 <link linkend='var-CACHE'>C</link>
23 <link linkend='var-D'>D</link>
24 <link linkend='var-EFI_PROVIDER'>E</link>
25 <link linkend='var-FEATURE_PACKAGES'>F</link>
26 <link linkend='var-GCCPIE'>G</link>
27 <link linkend='var-HOMEPAGE'>H</link>
28 <link linkend='var-ICECC_DISABLED'>I</link>
29<!-- <link linkend='var-glossary-j'>J</link> -->
30 <link linkend='var-KARCH'>K</link>
31 <link linkend='var-LABELS'>L</link>
32 <link linkend='var-MACHINE'>M</link>
33 <link linkend='var-NATIVELSBSTRING'>N</link>
34 <link linkend='var-OBJCOPY'>O</link>
35 <link linkend='var-P'>P</link>
36<!-- <link linkend='var-glossary-q'>Q</link> -->
37 <link linkend='var-RANLIB'>R</link>
38 <link linkend='var-S'>S</link>
39 <link linkend='var-T'>T</link>
40 <link linkend='var-UBOOT_CONFIG'>U</link>
41 <link linkend='var-VOLATILE_LOG_DIR'>V</link>
42 <link linkend='var-WARN_QA'>W</link>
43 <link linkend='var-XSERVER'>X</link>
44<!-- <link linkend='var-glossary-y'>Y</link> -->
45<!-- <link linkend='var-glossary-z'>Z</link>-->
46 </para>
47
48 <glossdiv id='var-glossary-a'><title>A</title>
49
50 <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm>
51 <info>
52 ABIEXTENSION[doc] = "Extension to the Application Binary Interface (ABI) field of the GNU canonical architecture name (e.g. "eabi")."
53 </info>
54 <glossdef>
55 <para role="glossdeffirst">
56 Extension to the Application Binary Interface (ABI)
57 field of the GNU canonical architecture name
58 (e.g. "eabi").
59 </para>
60
61 <para>
62 ABI extensions are set in the machine include files.
63 For example, the
64 <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>
65 file sets the following extension:
66 <literallayout class='monospaced'>
67 ABIEXTENSION = "eabi"
68 </literallayout>
69 </para>
70 </glossdef>
71 </glossentry>
72
73 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
74 <info>
75 ALLOW_EMPTY[doc] = "Specifies whether to produce an output package even if it is empty."
76 </info>
77 <glossdef>
78 <para role="glossdeffirst">
79 Specifies whether to produce an output package even if it is
80 empty.
81 By default, BitBake does not produce empty packages.
82 This default behavior can cause issues when there is an
83 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
84 some other hard runtime requirement on the existence of the package.
85 </para>
86
87 <para>
88 Like all package-controlling variables, you must always use them in
89 conjunction with a package name override, as in:
90 <literallayout class='monospaced'>
91 ALLOW_EMPTY_${PN} = "1"
92 ALLOW_EMPTY_${PN}-dev = "1"
93 ALLOW_EMPTY_${PN}-staticdev = "1"
94 </literallayout>
95 </para>
96 </glossdef>
97 </glossentry>
98
99 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
100 <info>
101 ALTERNATIVE[doc] = "Lists commands in a package that need an alternative binary naming scheme."
102 </info>
103 <glossdef>
104 <para role="glossdeffirst">
105 Lists commands in a package that need an alternative
106 binary naming scheme.
107 Sometimes the same command is provided in multiple packages.
108 When this occurs, the OpenEmbedded build system needs to
109 use the alternatives system to create a different binary
110 naming scheme so the commands can co-exist.
111 </para>
112
113 <para>
114 To use the variable, list out the package's commands
115 that also exist as part of another package.
116 For example, if the <filename>busybox</filename> package
117 has four commands that also exist as part of another
118 package, you identify them as follows:
119 <literallayout class='monospaced'>
120 ALTERNATIVE_busybox = "sh sed test bracket"
121 </literallayout>
122 For more information on the alternatives system, see the
123 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
124 section.
125 </para>
126 </glossdef>
127 </glossentry>
128
129 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
130 <info>
131 ALTERNATIVE_LINK_NAME[doc] = "Used by the alternatives system to map duplicated commands to actual locations."
132 </info>
133 <glossdef>
134 <para role="glossdeffirst">
135 Used by the alternatives system to map duplicated commands
136 to actual locations.
137 For example, if the <filename>bracket</filename> command
138 provided by the <filename>busybox</filename> package is
139 duplicated through another package, you must use the
140 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
141 specify the actual location:
142 <literallayout class='monospaced'>
143 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
144 </literallayout>
145 </para>
146
147 <para>
148 In this example, the binary for the
149 <filename>bracket</filename> command (i.e.
150 <filename>[</filename>) from the
151 <filename>busybox</filename> package resides in
152 <filename>/usr/bin/</filename>.
153 <note>
154 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
155 defined, it defaults to
156 <filename>${bindir}/<replaceable>name</replaceable></filename>.
157 </note>
158 </para>
159
160 <para>
161 For more information on the alternatives system, see the
162 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
163 section.
164 </para>
165 </glossdef>
166 </glossentry>
167
168 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
169 <info>
170 ALTERNATIVE_PRIORITY[doc] = "Used by the alternatives system to create default priorities for duplicated commands."
171 </info>
172 <glossdef>
173 <para role="glossdeffirst">
174 Used by the alternatives system to create default
175 priorities for duplicated commands.
176 You can use the variable to create a single default
177 regardless of the command name or package, a default for
178 specific duplicated commands regardless of the package, or
179 a default for specific commands tied to particular packages.
180 Here are the available syntax forms:
181 <literallayout class='monospaced'>
182 ALTERNATIVE_PRIORITY = "<replaceable>priority</replaceable>"
183 ALTERNATIVE_PRIORITY[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
184 ALTERNATIVE_PRIORITY_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
185 </literallayout>
186 </para>
187
188 <para>
189 For more information on the alternatives system, see the
190 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
191 section.
192 </para>
193 </glossdef>
194 </glossentry>
195
196 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
197 <info>
198 ALTERNATIVE_TARGET[doc] = "Used by the alternatives system to create default link locations for duplicated commands."
199 </info>
200 <glossdef>
201 <para role="glossdeffirst">
202 Used by the alternatives system to create default link
203 locations for duplicated commands.
204 You can use the variable to create a single default
205 location for all duplicated commands regardless of the
206 command name or package, a default for
207 specific duplicated commands regardless of the package, or
208 a default for specific commands tied to particular packages.
209 Here are the available syntax forms:
210 <literallayout class='monospaced'>
211 ALTERNATIVE_TARGET = "<replaceable>target</replaceable>"
212 ALTERNATIVE_TARGET[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
213 ALTERNATIVE_TARGET_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
214 </literallayout>
215 <note>
216 <para>
217 If <filename>ALTERNATIVE_TARGET</filename> is not
218 defined, it inherits the value from the
219 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
220 variable.
221 </para>
222
223 <para>
224 If <filename>ALTERNATIVE_LINK_NAME</filename> and
225 <filename>ALTERNATIVE_TARGET</filename> are the
226 same, the target for
227 <filename>ALTERNATIVE_TARGET</filename>
228 has "<filename>.{BPN}</filename>" appended to it.
229 </para>
230
231 <para>
232 Finally, if the file referenced has not been
233 renamed, the alternatives system will rename it to
234 avoid the need to rename alternative files in the
235 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
236 task while
237 retaining support for the command if necessary.
238 </para>
239 </note>
240 </para>
241
242 <para>
243 For more information on the alternatives system, see the
244 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
245 section.
246 </para>
247 </glossdef>
248 </glossentry>
249
250 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
251 <info>
252 APPEND[doc] = "An override list of append strings for target specified using LABELS."
253 </info>
254 <glossdef>
255 <para role="glossdeffirst">
256 An override list of append strings for each target
257 specified with
258 <link linkend='var-LABELS'><filename>LABELS</filename></link>.
259 </para>
260
261 <para>
262 See the
263 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
264 class for more information on how this variable is used.
265 </para>
266 </glossdef>
267 </glossentry>
268
269 <glossentry id='var-AR'><glossterm>AR</glossterm>
270 <info>
271 AR[doc] = "Minimal command and arguments to run 'ar'."
272 </info>
273 <glossdef>
274 <para role="glossdeffirst">
275 The minimal command and arguments used to run
276 <filename>ar</filename>.
277 </para>
278 </glossdef>
279 </glossentry>
280
281 <glossentry id='var-ARCHIVER_MODE'><glossterm>ARCHIVER_MODE</glossterm>
282 <info>
283 ARCHIVER_MODE[doc] = "Controls archive creation used when releasing source files."
284 </info>
285 <glossdef>
286 <para role="glossdeffirst">
287 When used with the
288 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
289 class, determines the type of information used to create
290 a released archive.
291 You can use this variable to create archives of patched
292 source, original source, configured source, and so forth
293 by employing the following variable flags (varflags):
294 <literallayout class='monospaced'>
295 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source
296 # files.
297
298 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is
299 # the default.
300
301 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
302
303 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and
304 # do_patch.
305
306 ARCHIVER_MODE[diff-exclude] ?= "<replaceable>file</replaceable> <replaceable>file</replaceable> ..." # Lists files and directories to
307 # exclude from diff.
308
309 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
310
311 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
312
313 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
314 </literallayout>
315 For information on how the variable works, see the
316 <filename>meta/classes/archiver.bbclass</filename> file
317 in the
318 <link linkend='source-directory'>Source Directory</link>.
319 </para>
320 </glossdef>
321 </glossentry>
322
323 <glossentry id='var-AS'><glossterm>AS</glossterm>
324 <info>
325 AS[doc] = "Minimal command and arguments to run the assembler."
326 </info>
327 <glossdef>
328 <para role="glossdeffirst">
329 Minimal command and arguments needed to run the
330 assembler.
331 </para>
332 </glossdef>
333 </glossentry>
334
335 <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
336 <info>
337 ASSUME_PROVIDED[doc] = "Lists recipe names (PN values) BitBake does not attempt to build."
338 </info>
339 <glossdef>
340 <para role="glossdeffirst">
341 Lists recipe names
342 (<link linkend='var-PN'><filename>PN</filename></link>
343 values) BitBake does not attempt to build.
344 Instead, BitBake assumes these recipes have already been
345 built.
346 </para>
347
348 <para>
349 In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename>
350 mostly specifies native tools that should not be built.
351 An example is <filename>git-native</filename>, which when
352 specified, allows for the Git binary from the host to be
353 used rather than building <filename>git-native</filename>.
354 </para>
355 </glossdef>
356 </glossentry>
357
358 <glossentry id='var-ASSUME_SHLIBS'><glossterm>ASSUME_SHLIBS</glossterm>
359 <info>
360 ASSUME_SHLIBS[doc] = "Provides additional shlibs provider mapping information, which adds to or overwrites the information provided automatically by the system."
361 </info>
362 <glossdef>
363 <para role="glossdeffirst">
364 Provides additional <filename>shlibs</filename> provider
365 mapping information, which adds to or overwrites the
366 information provided automatically by the system.
367 Separate multiple entries using spaces.
368 </para>
369
370 <para>
371 As an example, use the following form to add an
372 <filename>shlib</filename> provider of
373 <replaceable>shlibname</replaceable> in
374 <replaceable>packagename</replaceable> with the optional
375 <replaceable>version</replaceable>:
376 <literallayout class='monospaced'>
377 <replaceable>shlibname:packagename</replaceable>[_<replaceable>version</replaceable>]
378 </literallayout>
379 </para>
380
381 <para>
382 Here is an example that adds a shared library named
383 <filename>libEGL.so.1</filename> as being provided by
384 the <filename>libegl-implementation</filename> package:
385 <literallayout class='monospaced'>
386 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
387 </literallayout>
388 </para>
389 </glossdef>
390 </glossentry>
391
392 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
393 <info>
394 AUTHOR[doc] = "Email address used to contact the original author or authors in order to send patches and forward bugs."
395 </info>
396 <glossdef>
397 <para role="glossdeffirst">
398 The email address used to contact the original author
399 or authors in order to send patches and forward bugs.
400 </para>
401 </glossdef>
402 </glossentry>
403
404 <glossentry id='var-AUTO_LIBNAME_PKGS'><glossterm>AUTO_LIBNAME_PKGS</glossterm>
405 <info>
406 AUTO_LIBNAME_PKGS[doc] = "Specifies which packages should be checked for libraries and renamed according to Debian library package naming."
407 </info>
408 <glossdef>
409 <para role="glossdeffirst">
410 When the
411 <link linkend='ref-classes-debian'><filename>debian</filename></link>
412 class is inherited, which is the default behavior,
413 <filename>AUTO_LIBNAME_PKGS</filename> specifies which
414 packages should be checked for libraries and renamed
415 according to Debian library package naming.
416 </para>
417
418 <para>
419 The default value is "${PACKAGES}", which causes the
420 debian class to act on all packages that are
421 explicitly generated by the recipe.
422 </para>
423 </glossdef>
424 </glossentry>
425
426 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
427 <info>
428 AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader."
429 </info>
430 <glossdef>
431 <para role="glossdeffirst">
432 Enables creating an automatic menu for the syslinux
433 bootloader.
434 You must set this variable in your recipe.
435 The
436 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
437 class checks this variable.
438 </para>
439 </glossdef>
440 </glossentry>
441
442 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
443 <info>
444 AUTOREV[doc] = "When SRCREV is set to the value of this variable, it specifies to use the latest source revision in the repository."
445 </info>
446 <glossdef>
447 <para role="glossdeffirst">
448 When
449 <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
450 is set to the value of this variable, it specifies to use
451 the latest source revision in the repository.
452 Here is an example:
453 <literallayout class='monospaced'>
454 SRCREV = "${AUTOREV}"
455 </literallayout>
456 </para>
457
458 <para>
459 If you use the previous statement to retrieve the latest
460 version of software, you need to be sure
461 <link linkend='var-PV'><filename>PV</filename></link>
462 contains
463 <filename>${</filename><link linkend='var-SRCPV'><filename>SRCPV</filename></link><filename>}</filename>.
464 For example, suppose you have a kernel recipe that
465 inherits the
466 <link linkend='ref-classes-kernel'>kernel</link> class
467 and you use the previous statement.
468 In this example, <filename>${SRCPV}</filename> does not
469 automatically get into <filename>PV</filename>.
470 Consequently, you need to change <filename>PV</filename>
471 in your recipe so that it does contain
472 <filename>${SRCPV}</filename>.
473 </para>
474
475 <para>
476 For more information see the
477 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
478 section in the Yocto Project Development Tasks Manual.
479 </para>
480 </glossdef>
481 </glossentry>
482
483 <glossentry id='var-AVAILABLE_LICENSES'><glossterm>AVAILABLE_LICENSES</glossterm>
484 <info>
485 AVAILABLE_LICENSES[doc] = "List of licenses found in the directories specified by COMMON_LICENSE_DIR and LICENSE_PATH."
486 </info>
487 <glossdef>
488 <para role="glossdeffirst">
489
490 List of licenses found in the directories specified
491 by <link linkend='var-COMMON_LICENSE_DIR'><filename>COMMON_LICENSE_DIR</filename></link>
492 and <link linkend='var-LICENSE_PATH'><filename>LICENSE_PATH</filename></link>.
493
494 <note>
495 It is assumed that all changes
496 to <filename>COMMON_LICENSE_DIR</filename>
497 and <filename>LICENSE_PATH</filename> have been done
498 before <filename>AVAILABLE_LICENSES</filename> is
499 defined
500 (in <link linkend='ref-classes-license'>license.bbclass</link>).
501 </note>
502 </para>
503 </glossdef>
504 </glossentry>
505
506 <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>
507 <info>
508 AVAILTUNES[doc] = "The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system."
509 </info>
510 <glossdef>
511 <para role="glossdeffirst">
512 The list of defined CPU and Application Binary Interface
513 (ABI) tunings (i.e. "tunes") available for use by the
514 OpenEmbedded build system.
515 </para>
516
517 <para>
518 The list simply presents the tunes that are available.
519 Not all tunes may be compatible with a particular
520 machine configuration, or with each other in a
521 <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>
522 configuration.
523 </para>
524
525 <para>
526 To add a tune to the list, be sure to append it with
527 spaces using the "+=" BitBake operator.
528 Do not simply replace the list by using the "=" operator.
529 See the
530 "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
531 section in the BitBake User Manual for more information.
532 </para>
533 </glossdef>
534 </glossentry>
535
536 </glossdiv>
537
538 <glossdiv id='var-glossary-b'><title>B</title>
539
540 <glossentry id='var-B'><glossterm>B</glossterm>
541 <info>
542 B[doc] = "The Build Directory. The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process."
543 </info>
544 <glossdef>
545 <para role="glossdeffirst">
546 The directory within the
547 <link linkend='build-directory'>Build Directory</link>
548 in which the OpenEmbedded build system places generated
549 objects during a recipe's build process.
550 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
551 directory, which is defined as:
552 <literallayout class='monospaced'>
553 S = "${WORKDIR}/${BP}"
554 </literallayout>
555 </para>
556
557 <para>
558 You can separate the (<filename>S</filename>) directory
559 and the directory pointed to by the <filename>B</filename>
560 variable.
561 Most Autotools-based recipes support separating these
562 directories.
563 The build system defaults to using separate directories for
564 <filename>gcc</filename> and some kernel recipes.
565 </para>
566 </glossdef>
567 </glossentry>
568
569 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
570 <info>
571 BAD_RECOMMENDATIONS[doc] = "A list of packages not to install despite being recommended by a recipe. Support for this variable exists only when using the IPK packaging backend."
572 </info>
573 <glossdef>
574 <para role="glossdeffirst">
575 Lists "recommended-only" packages to not install.
576 Recommended-only packages are packages installed only
577 through the
578 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
579 variable.
580 You can prevent any of these "recommended" packages from
581 being installed by listing them with the
582 <filename>BAD_RECOMMENDATIONS</filename> variable:
583 <literallayout class='monospaced'>
584 BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
585 </literallayout>
586 </para>
587
588 <para>
589 You can set this variable globally in your
590 <filename>local.conf</filename> file or you can attach it to
591 a specific image recipe by using the recipe name override:
592 <literallayout class='monospaced'>
593 BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
594 </literallayout>
595 </para>
596
597 <para>
598 It is important to realize that if you choose to not install
599 packages using this variable and some other packages are
600 dependent on them (i.e. listed in a recipe's
601 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
602 variable), the OpenEmbedded build system ignores your
603 request and will install the packages to avoid dependency
604 errors.
605 </para>
606
607 <para>
608 Support for this variable exists only when using the
609 IPK and RPM packaging backend.
610 Support does not exist for DEB.
611 </para>
612
613 <para>
614 See the
615 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
616 and the
617 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
618 variables for related information.
619 </para>
620 </glossdef>
621 </glossentry>
622
623 <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm>
624 <info>
625 BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune."
626 </info>
627 <glossdef>
628 <para role="glossdeffirst">
629 The library directory name for the CPU or Application
630 Binary Interface (ABI) tune.
631 The <filename>BASE_LIB</filename> applies only in the
632 Multilib context.
633 See the
634 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
635 section in the Yocto Project Development Tasks Manual for
636 information on Multilib.
637 </para>
638
639 <para>
640 The <filename>BASE_LIB</filename> variable is defined in
641 the machine include files in the
642 <link linkend='source-directory'>Source Directory</link>.
643 If Multilib is not being used, the value defaults to "lib".
644 </para>
645 </glossdef>
646 </glossentry>
647
648 <glossentry id='var-BASE_WORKDIR'><glossterm>BASE_WORKDIR</glossterm>
649 <info>
650 BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes."
651 </info>
652 <glossdef>
653 <para role="glossdeffirst">
654 Points to the base of the work directory for all recipes.
655 The default value is "${TMPDIR}/work".
656 </para>
657 </glossdef>
658 </glossentry>
659
660 <glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>
661 <info>
662 BB_ALLOWED_NETWORKS[doc] = "A list of hosts that the fetcher is allowed to use to obtain the required source code."
663 </info>
664 <glossdef>
665 <para>
666 Specifies a space-delimited list of hosts that the fetcher
667 is allowed to use to obtain the required source code.
668 Following are considerations surrounding this variable:
669 <itemizedlist>
670 <listitem><para>
671 This host list is only used if
672 <filename>BB_NO_NETWORK</filename> is either not
673 set or set to "0".
674 </para></listitem>
675 <listitem><para>
676 Limited support for wildcard matching against the
677 beginning of host names exists.
678 For example, the following setting matches
679 <filename>git.gnu.org</filename>,
680 <filename>ftp.gnu.org</filename>, and
681 <filename>foo.git.gnu.org</filename>.
682 <literallayout class='monospaced'>
683 BB_ALLOWED_NETWORKS = "*.gnu.org"
684 </literallayout>
685 <note><title>Important</title>
686 <para>The use of the "<filename>*</filename>"
687 character only works at the beginning of
688 a host name and it must be isolated from
689 the remainder of the host name.
690 You cannot use the wildcard character in any
691 other location of the name or combined with
692 the front part of the name.</para>
693
694 <para>For example,
695 <filename>*.foo.bar</filename> is supported,
696 while <filename>*aa.foo.bar</filename> is not.
697 </para>
698 </note>
699 </para></listitem>
700 <listitem><para>
701 Mirrors not in the host list are skipped and
702 logged in debug.
703 </para></listitem>
704 <listitem><para>
705 Attempts to access networks not in the host list
706 cause a failure.
707 </para></listitem>
708 </itemizedlist>
709 Using <filename>BB_ALLOWED_NETWORKS</filename> in
710 conjunction with
711 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
712 is very useful.
713 Adding the host you want to use to
714 <filename>PREMIRRORS</filename> results in the source code
715 being fetched from an allowed location and avoids raising
716 an error when a host that is not allowed is in a
717 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
718 statement.
719 This is because the fetcher does not attempt to use the
720 host listed in <filename>SRC_URI</filename> after a
721 successful fetch from the
722 <filename>PREMIRRORS</filename> occurs.
723 </para>
724 </glossdef>
725 </glossentry>
726
727 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
728 <info>
729 BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)."
730 </info>
731 <glossdef>
732 <para role="glossdeffirst">
733 Defines how BitBake handles situations where an append
734 file (<filename>.bbappend</filename>) has no
735 corresponding recipe file (<filename>.bb</filename>).
736 This condition often occurs when layers get out of sync
737 (e.g. <filename>oe-core</filename> bumps a
738 recipe version and the old recipe no longer exists and the
739 other layer has not been updated to the new version
740 of the recipe yet).
741 </para>
742
743 <para>
744 The default fatal behavior is safest because it is
745 the sane reaction given something is out of sync.
746 It is important to realize when your changes are no longer
747 being applied.
748 </para>
749
750 <para>
751 You can change the default behavior by setting this
752 variable to "1", "yes", or "true"
753 in your <filename>local.conf</filename> file, which is
754 located in the
755 <link linkend='build-directory'>Build Directory</link>:
756 Here is an example:
757 <literallayout class='monospaced'>
758 BB_DANGLINGAPPENDS_WARNONLY = "1"
759 </literallayout>
760 </para>
761 </glossdef>
762 </glossentry>
763
764 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
765 <info>
766 BB_DISKMON_DIRS[doc] = "Monitors disk space and available inodes during the build and allows you to control the build based on these parameters."
767 </info>
768 <glossdef>
769 <para role="glossdeffirst">
770 Monitors disk space and available inodes during the build
771 and allows you to control the build based on these
772 parameters.
773 </para>
774
775 <para>
776 Disk space monitoring is disabled by default.
777 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
778 variable to your <filename>conf/local.conf</filename> file found in the
779 <link linkend='build-directory'>Build Directory</link>.
780 Use the following form:
781 <literallayout class='monospaced'>
782 BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]"
783
784 where:
785
786 <replaceable>action</replaceable> is:
787 ABORT: Immediately abort the build when
788 a threshold is broken.
789 STOPTASKS: Stop the build after the currently
790 executing tasks have finished when
791 a threshold is broken.
792 WARN: Issue a warning but continue the
793 build when a threshold is broken.
794 Subsequent warnings are issued as
795 defined by the BB_DISKMON_WARNINTERVAL
796 variable, which must be defined in
797 the conf/local.conf file.
798
799 <replaceable>dir</replaceable> is:
800 Any directory you choose. You can specify one or
801 more directories to monitor by separating the
802 groupings with a space. If two directories are
803 on the same device, only the first directory
804 is monitored.
805
806 <replaceable>threshold</replaceable> is:
807 Either the minimum available disk space,
808 the minimum number of free inodes, or
809 both. You must specify at least one. To
810 omit one or the other, simply omit the value.
811 Specify the threshold using G, M, K for Gbytes,
812 Mbytes, and Kbytes, respectively. If you do
813 not specify G, M, or K, Kbytes is assumed by
814 default. Do not use GB, MB, or KB.
815 </literallayout>
816 </para>
817
818 <para>
819 Here are some examples:
820 <literallayout class='monospaced'>
821 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
822 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
823 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
824 </literallayout>
825 The first example works only if you also provide
826 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
827 in the <filename>conf/local.conf</filename>.
828 This example causes the build system to immediately
829 abort when either the disk space in <filename>${TMPDIR}</filename> drops
830 below 1 Gbyte or the available free inodes drops below
831 100 Kbytes.
832 Because two directories are provided with the variable, the
833 build system also issue a
834 warning when the disk space in the
835 <filename>${SSTATE_DIR}</filename> directory drops
836 below 1 Gbyte or the number of free inodes drops
837 below 100 Kbytes.
838 Subsequent warnings are issued during intervals as
839 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
840 variable.
841 </para>
842
843 <para>
844 The second example stops the build after all currently
845 executing tasks complete when the minimum disk space
846 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
847 directory drops below 1 Gbyte.
848 No disk monitoring occurs for the free inodes in this case.
849 </para>
850
851 <para>
852 The final example immediately aborts the build when the
853 number of free inodes in the <filename>${TMPDIR}</filename> directory
854 drops below 100 Kbytes.
855 No disk space monitoring for the directory itself occurs
856 in this case.
857 </para>
858 </glossdef>
859 </glossentry>
860
861 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
862 <info>
863 BB_DISKMON_WARNINTERVAL[doc] = "Defines the disk space and free inode warning intervals. To set these intervals, define the variable in the conf/local.conf file in the Build Directory."
864 </info>
865 <glossdef>
866 <para role="glossdeffirst">
867 Defines the disk space and free inode warning intervals.
868 To set these intervals, define the variable in your
869 <filename>conf/local.conf</filename> file in the
870 <link linkend='build-directory'>Build Directory</link>.
871 </para>
872
873 <para>
874 If you are going to use the
875 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
876 also use the
877 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
878 and define its action as "WARN".
879 During the build, subsequent warnings are issued each time
880 disk space or number of free inodes further reduces by
881 the respective interval.
882 </para>
883
884 <para>
885 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
886 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
887 the "WARN" action, the disk monitoring interval defaults to
888 the following:
889 <literallayout class='monospaced'>
890 BB_DISKMON_WARNINTERVAL = "50M,5K"
891 </literallayout>
892 </para>
893
894 <para>
895 When specifying the variable in your configuration file,
896 use the following form:
897 <literallayout class='monospaced'>
898 BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>"
899
900 where:
901
902 <replaceable>disk_space_interval</replaceable> is:
903 An interval of memory expressed in either
904 G, M, or K for Gbytes, Mbytes, or Kbytes,
905 respectively. You cannot use GB, MB, or KB.
906
907 <replaceable>disk_inode_interval</replaceable> is:
908 An interval of free inodes expressed in either
909 G, M, or K for Gbytes, Mbytes, or Kbytes,
910 respectively. You cannot use GB, MB, or KB.
911 </literallayout>
912 </para>
913
914 <para>
915 Here is an example:
916 <literallayout class='monospaced'>
917 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
918 BB_DISKMON_WARNINTERVAL = "50M,5K"
919 </literallayout>
920 These variables cause the OpenEmbedded build system to
921 issue subsequent warnings each time the available
922 disk space further reduces by 50 Mbytes or the number
923 of free inodes further reduces by 5 Kbytes in the
924 <filename>${SSTATE_DIR}</filename> directory.
925 Subsequent warnings based on the interval occur each time
926 a respective interval is reached beyond the initial warning
927 (i.e. 1 Gbytes and 100 Kbytes).
928 </para>
929 </glossdef>
930 </glossentry>
931
932 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
933 <info>
934 BB_GENERATE_MIRROR_TARBALLS[doc] = "Causes tarballs of the source control repositories to be placed in the DL_DIR directory."
935 </info>
936 <glossdef>
937 <para role="glossdeffirst">
938 Causes tarballs of the source control repositories
939 (e.g. Git repositories), including metadata, to be placed
940 in the
941 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
942 directory.
943 </para>
944
945 <para>
946 For performance reasons, creating and placing tarballs of
947 these repositories is not the default action by the
948 OpenEmbedded build system.
949 <literallayout class='monospaced'>
950 BB_GENERATE_MIRROR_TARBALLS = "1"
951 </literallayout>
952 Set this variable in your <filename>local.conf</filename>
953 file in the
954 <link linkend='build-directory'>Build Directory</link>.
955 </para>
956
957 <para>
958 Once you have the tarballs containing your source files,
959 you can clean up your <filename>DL_DIR</filename>
960 directory by deleting any Git or other source control
961 work directories.
962 </para>
963 </glossdef>
964 </glossentry>
965
966 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
967 <info>
968 BB_NUMBER_THREADS[doc] = "The maximum number of tasks BitBake should run in parallel at any one time. This variable is automatically configured to be equal to the number of build system cores."
969 </info>
970 <glossdef>
971 <para role="glossdeffirst">
972 The maximum number of tasks BitBake should run in parallel
973 at any one time.
974 The OpenEmbedded build system automatically configures
975 this variable to be equal to the number of cores on the
976 build system.
977 For example, a system with a dual core processor that
978 also uses hyper-threading causes the
979 <filename>BB_NUMBER_THREADS</filename> variable to default
980 to "4".
981 </para>
982
983 <para>
984 For single socket systems (i.e. one CPU), you should not
985 have to override this variable to gain optimal parallelism
986 during builds.
987 However, if you have very large systems that employ
988 multiple physical CPUs, you might want to make sure the
989 <filename>BB_NUMBER_THREADS</filename> variable is not
990 set higher than "20".
991 </para>
992
993 <para>
994 For more information on speeding up builds, see the
995 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
996 section in the Yocto Project Development Tasks Manual.
997 </para>
998 </glossdef>
999 </glossentry>
1000
1001 <glossentry id='var-BB_SERVER_TIMEOUT'><glossterm>BB_SERVER_TIMEOUT</glossterm>
1002 <info>
1003 BB_SERVER_TIMEOUT [doc] = "Specifies the time (in seconds) after which to unload the BitBake server due to inactivity."
1004 </info>
1005 <glossdef>
1006 <para role="glossdeffirst">
1007 Specifies the time (in seconds) after which to unload the
1008 BitBake server due to inactivity.
1009 Set <filename>BB_SERVER_TIMEOUT</filename> to determine how
1010 long the BitBake server stays resident between invocations.
1011 </para>
1012
1013 <para>
1014 For example, the following statement in your
1015 <filename>local.conf</filename> file instructs the server
1016 to be unloaded after 20 seconds of inactivity:
1017 <literallayout class='monospaced'>
1018 BB_SERVER_TIMEOUT = "20"
1019 </literallayout>
1020 If you want the server to never be unloaded, set
1021 <filename>BB_SERVER_TIMEOUT</filename> to "-1".
1022 </para>
1023 </glossdef>
1024 </glossentry>
1025
1026 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
1027 <info>
1028 BBCLASSEXTEND[doc] = "Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes are 'native', 'cross', 'nativesdk', and multilibs."
1029 </info>
1030 <glossdef>
1031 <para role="glossdeffirst">
1032 Allows you to extend a recipe so that it builds variants of the software.
1033 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
1034 which is a copy of Quilt built to run on the build system;
1035 "crosses" such as <filename>gcc-cross</filename>,
1036 which is a compiler built to run on the build machine but produces binaries
1037 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
1038 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
1039 and "mulitlibs" in the form "<filename>multilib:</filename><replaceable>multilib_name</replaceable>".
1040 </para>
1041
1042 <para>
1043 To build a different variant of the recipe with a minimal amount of code, it usually
1044 is as simple as adding the following to your recipe:
1045 <literallayout class='monospaced'>
1046 BBCLASSEXTEND =+ "native nativesdk"
1047 BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
1048 </literallayout>
1049 <note>
1050 <para>
1051 Internally, the <filename>BBCLASSEXTEND</filename>
1052 mechanism generates recipe variants by rewriting
1053 variable values and applying overrides such as
1054 <filename>_class-native</filename>.
1055 For example, to generate a native version of a recipe,
1056 a
1057 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1058 on "foo" is rewritten to a <filename>DEPENDS</filename>
1059 on "foo-native".
1060 </para>
1061
1062 <para>
1063 Even when using <filename>BBCLASSEXTEND</filename>, the
1064 recipe is only parsed once.
1065 Parsing once adds some limitations.
1066 For example, it is not possible to
1067 include a different file depending on the variant,
1068 since <filename>include</filename> statements are
1069 processed when the recipe is parsed.
1070 </para>
1071 </note>
1072 </para>
1073 </glossdef>
1074 </glossentry>
1075
1076 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
1077 <info>
1078 BBFILE_COLLECTIONS[doc] = "Lists the names of configured layers. These names are used to find the other BBFILE_* variables."
1079 </info>
1080 <glossdef>
1081 <para role="glossdeffirst">
1082 Lists the names of configured layers.
1083 These names are used to find the other <filename>BBFILE_*</filename>
1084 variables.
1085 Typically, each layer will append its name to this variable in its
1086 <filename>conf/layer.conf</filename> file.
1087 </para>
1088 </glossdef>
1089 </glossentry>
1090
1091 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
1092 <info>
1093 BBFILE_PATTERN[doc] = "Variable that expands to match files from BBFILES in a particular layer. This variable is used in the layer.conf file and must be suffixed with the name of a layer."
1094 </info>
1095 <glossdef>
1096 <para role="glossdeffirst">
1097 Variable that expands to match files from
1098 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
1099 in a particular layer.
1100 This variable is used in the <filename>conf/layer.conf</filename> file and must
1101 be suffixed with the name of the specific layer (e.g.
1102 <filename>BBFILE_PATTERN_emenlow</filename>).
1103 </para>
1104 </glossdef>
1105 </glossentry>
1106
1107 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
1108 <info>
1109 BBFILE_PRIORITY[doc] = "Assigns the priority for recipe files in each layer. Setting this variable allows you to prioritize a layer against other layers that contain the same recipe."
1110 </info>
1111 <glossdef>
1112 <para role="glossdeffirst">
1113 Assigns the priority for recipe files in each layer.
1114 </para>
1115
1116 <para>
1117 This variable is useful in situations where the same recipe appears in
1118 more than one layer.
1119 Setting this variable allows you to prioritize a
1120 layer against other layers that contain the same recipe - effectively
1121 letting you control the precedence for the multiple layers.
1122 The precedence established through this variable stands regardless of a
1123 recipe's version
1124 (<link linkend='var-PV'><filename>PV</filename></link> variable).
1125 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
1126 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
1127 lower precedence.
1128 </para>
1129
1130 <para>
1131 A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
1132 precedence.
1133 For example, the value 6 has a higher precedence than the value 5.
1134 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
1135 dependencies (see the
1136 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
1137 more information.
1138 The default priority, if unspecified
1139 for a layer with no dependencies, is the lowest defined priority + 1
1140 (or 1 if no priorities are defined).
1141 </para>
1142 <tip>
1143 You can use the command <filename>bitbake-layers show-layers</filename> to list
1144 all configured layers along with their priorities.
1145 </tip>
1146 </glossdef>
1147 </glossentry>
1148
1149 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
1150 <info>
1151 BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software."
1152 </info>
1153 <glossdef>
1154 <para role="glossdeffirst">
1155 A space-separated list of recipe files BitBake uses to
1156 build software.
1157 </para>
1158
1159 <para>
1160 When specifying recipe files, you can pattern match using
1161 Python's
1162 <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink>
1163 syntax.
1164 For details on the syntax, see the documentation by
1165 following the previous link.
1166 </para>
1167 </glossdef>
1168 </glossentry>
1169
1170 <glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm>
1171 <info>
1172 BBFILES_DYNAMIC[doc] = "Activates content when identified layers are present."
1173 </info>
1174 <glossdef>
1175 <para role="glossdeffirst">
1176 Activates content when identified layers are present.
1177 You identify the layers by the collections that the layers
1178 define.
1179 </para>
1180
1181 <para>
1182 Use the <filename>BBFILES_DYNAMIC</filename> variable to
1183 avoid <filename>.bbappend</filename> files whose
1184 corresponding <filename>.bb</filename> file is in a layer
1185 that attempts to modify other layers through
1186 <filename>.bbappend</filename> but does not want to
1187 introduce a hard dependency on those other layers.
1188 </para>
1189
1190 <para>
1191 Use the following form for
1192 <filename>BBFILES_DYNAMIC</filename>:
1193 <literallayout class='monospaced'>
1194 <replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable>
1195 </literallayout>
1196 The following example identifies two collection names and
1197 two filename patterns:
1198 <literallayout class='monospaced'>
1199 BBFILES_DYNAMIC += " \
1200 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
1201 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
1202 "
1203 </literallayout>
1204 This next example shows an error message that occurs
1205 because invalid entries are found, which cause parsing to
1206 abort:
1207 <literallayout class='monospaced'>
1208 ERROR: BBFILES_DYNAMIC entries must be of the form &lt;collection name&gt;:&lt;filename pattern&gt;, not:
1209 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
1210 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
1211 </literallayout>
1212 </para>
1213 </glossdef>
1214 </glossentry>
1215
1216 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
1217 <info>
1218 BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure."
1219 </info>
1220 <glossdef>
1221 <para role="glossdeffirst">
1222 Variable that controls how BitBake displays logs on build failure.
1223 </para>
1224 </glossdef>
1225 </glossentry>
1226
1227 <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
1228 <info>
1229 BBINCLUDELOGS_LINES[doc] = "Amount of log lines printed on failure."
1230 </info>
1231 <glossdef>
1232 <para role="glossdeffirst">
1233 If
1234 <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
1235 is set, specifies the maximum number of lines from the
1236 task log file to print when reporting a failed task.
1237 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
1238 the entire log is printed.
1239 </para>
1240 </glossdef>
1241 </glossentry>
1242
1243 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
1244 <info>
1245 BBLAYERS[doc] = "Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file."
1246 </info>
1247 <glossdef>
1248 <para role="glossdeffirst">
1249 Lists the layers to enable during the build.
1250 This variable is defined in the <filename>bblayers.conf</filename> configuration
1251 file in the
1252 <link linkend='build-directory'>Build Directory</link>.
1253 Here is an example:
1254 <literallayout class='monospaced'>
1255 BBLAYERS = " \
1256 /home/scottrif/poky/meta \
1257 /home/scottrif/poky/meta-poky \
1258 /home/scottrif/poky/meta-yocto-bsp \
1259 /home/scottrif/poky/meta-mykernel \
1260 "
1261 </literallayout>
1262 </para>
1263
1264 <para>
1265 This example enables four layers, one of which is a custom, user-defined layer
1266 named <filename>meta-mykernel</filename>.
1267 </para>
1268 </glossdef>
1269 </glossentry>
1270
1271 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
1272 <info>
1273 BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files."
1274 </info>
1275 <glossdef>
1276 <para role="glossdeffirst">
1277 Prevents BitBake from processing recipes and recipe
1278 append files.
1279 </para>
1280
1281 <para>
1282 You can use the <filename>BBMASK</filename> variable
1283 to "hide" these <filename>.bb</filename> and
1284 <filename>.bbappend</filename> files.
1285 BitBake ignores any recipe or recipe append files that
1286 match any of the expressions.
1287 It is as if BitBake does not see them at all.
1288 Consequently, matching files are not parsed or otherwise
1289 used by BitBake.
1290 </para>
1291
1292 <para>
1293 The values you provide are passed to Python's regular
1294 expression compiler.
1295 Consequently, the syntax follows Python's Regular
1296 Expression (re) syntax.
1297 The expressions are compared against the full paths to
1298 the files.
1299 For complete syntax information, see Python's
1300 documentation at
1301 <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>.
1302 </para>
1303
1304 <para>
1305 The following example uses a complete regular expression
1306 to tell BitBake to ignore all recipe and recipe append
1307 files in the <filename>meta-ti/recipes-misc/</filename>
1308 directory:
1309 <literallayout class='monospaced'>
1310 BBMASK = "meta-ti/recipes-misc/"
1311 </literallayout>
1312 If you want to mask out multiple directories or recipes,
1313 you can specify multiple regular expression fragments.
1314 This next example masks out multiple directories and
1315 individual recipes:
1316 <literallayout class='monospaced'>
1317 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
1318 BBMASK += "/meta-oe/recipes-support/"
1319 BBMASK += "/meta-foo/.*/openldap"
1320 BBMASK += "opencv.*\.bbappend"
1321 BBMASK += "lzma"
1322 </literallayout>
1323 <note>
1324 When specifying a directory name, use the trailing
1325 slash character to ensure you match just that directory
1326 name.
1327 </note>
1328 </para>
1329 </glossdef>
1330 </glossentry>
1331
1332 <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>
1333 <info>
1334 BBMULTICONFIG[doc] = "Specifies each additional separate configuration when you are building targets with multiple configurations."
1335 </info>
1336 <glossdef>
1337 <para role="glossdeffirst">
1338 Specifies each additional separate configuration when you
1339 are building targets with multiple configurations.
1340 Use this variable in your
1341 <filename>conf/local.conf</filename> configuration file.
1342 Specify a <replaceable>multiconfigname</replaceable> for
1343 each configuration file you are using.
1344 For example, the following line specifies three
1345 configuration files:
1346 <literallayout class='monospaced'>
1347 BBMULTICONFIG = "configA configB configC"
1348 </literallayout>
1349 Each configuration file you use must reside in the
1350 <link linkend='build-directory'>Build Directory</link>
1351 <filename>conf/multiconfig</filename> directory
1352 (e.g.
1353 <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).
1354 </para>
1355
1356 <para>
1357 For information on how to use
1358 <filename>BBMULTICONFIG</filename> in an environment that
1359 supports building targets with multiple configurations,
1360 see the
1361 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-images-for-multiple-targets-using-multiple-configurations'>Building Images for Multiple Targets Using Multiple Configurations</ulink>"
1362 section in the Yocto Project Development Tasks Manual.
1363 </para>
1364 </glossdef>
1365 </glossentry>
1366
1367 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
1368 <info>
1369 BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable."
1370 </info>
1371 <glossdef>
1372 <para role="glossdeffirst">
1373 Used by BitBake to locate
1374 <filename>.bbclass</filename> and configuration files.
1375 This variable is analogous to the
1376 <filename>PATH</filename> variable.
1377 <note>
1378 If you run BitBake from a directory outside of the
1379 <link linkend='build-directory'>Build Directory</link>,
1380 you must be sure to set
1381 <filename>BBPATH</filename> to point to the
1382 Build Directory.
1383 Set the variable as you would any environment variable
1384 and then run BitBake:
1385 <literallayout class='monospaced'>
1386 $ BBPATH = "<replaceable>build_directory</replaceable>"
1387 $ export BBPATH
1388 $ bitbake <replaceable>target</replaceable>
1389 </literallayout>
1390 </note>
1391 </para>
1392 </glossdef>
1393 </glossentry>
1394
1395 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
1396 <info>
1397 BBSERVER[doc] = "Points to the BitBake remote server."
1398 </info>
1399 <glossdef>
1400 <para role="glossdeffirst">
1401 If defined in the BitBake environment,
1402 <filename>BBSERVER</filename> points to the BitBake
1403 remote server.
1404 </para>
1405
1406 <para>
1407 Use the following format to export the variable to the
1408 BitBake environment:
1409 <literallayout class='monospaced'>
1410 export BBSERVER=localhost:$port
1411 </literallayout>
1412 </para>
1413
1414 <para>
1415 By default, <filename>BBSERVER</filename> also appears in
1416 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>.
1417 Consequently, <filename>BBSERVER</filename> is excluded
1418 from checksum and dependency data.
1419 </para>
1420 </glossdef>
1421 </glossentry>
1422
1423 <glossentry id='var-BINCONFIG'><glossterm>BINCONFIG</glossterm>
1424 <info>
1425 BINCONFIG[doc] = "When inheriting the binconfig-disabled class, this variable specifies binary configuration scripts to disable in favor of using pkg-config to query the information."
1426 </info>
1427 <glossdef>
1428 <para role="glossdeffirst">
1429 When inheriting the
1430 <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link>
1431 class, this variable specifies binary configuration
1432 scripts to disable in favor of using
1433 <filename>pkg-config</filename> to query the information.
1434 The <filename>binconfig-disabled</filename> class will
1435 modify the specified scripts to return an error so that
1436 calls to them can be easily found and replaced.
1437 </para>
1438
1439 <para>
1440 To add multiple scripts, separate them by spaces.
1441 Here is an example from the <filename>libpng</filename>
1442 recipe:
1443 <literallayout class='monospaced'>
1444 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
1445 </literallayout>
1446 </para>
1447 </glossdef>
1448 </glossentry>
1449
1450 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
1451 <info>
1452 BINCONFIG_GLOB[doc] = "When inheriting binconfig.bbclass from a recipe, this variable specifies a wildcard for configuration scripts that need editing."
1453 </info>
1454 <glossdef>
1455 <para role="glossdeffirst">
1456 When inheriting the
1457 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
1458 class, this variable specifies a wildcard for
1459 configuration scripts that need editing.
1460 The scripts are edited to correct any paths that have been
1461 set up during compilation so that they are correct for
1462 use when installed into the sysroot and called by the
1463 build processes of other recipes.
1464 <note>
1465 The <filename>BINCONFIG_GLOB</filename> variable
1466 uses
1467 <ulink url='http://tldp.org/LDP/abs/html/globbingref.html'>shell globbing</ulink>,
1468 which is recognition and expansion of wildcards during
1469 pattern matching.
1470 Shell globbing is very similar to
1471 <ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
1472 and
1473 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>.
1474 </note>
1475 </para>
1476
1477 <para>
1478 For more information on how this variable works, see
1479 <filename>meta/classes/binconfig.bbclass</filename> in the
1480 <link linkend='source-directory'>Source Directory</link>.
1481 You can also find general information on the class in the
1482 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
1483 section.
1484 </para>
1485 </glossdef>
1486 </glossentry>
1487
1488 <glossentry id='var-BP'><glossterm>BP</glossterm>
1489 <info>
1490 BP[doc] = "The base recipe name and version but without any special recipe name suffix (i.e. -native, lib64-, and so forth). BP is comprised of ${BPN}-${PV}"
1491 </info>
1492 <glossdef>
1493 <para role="glossdeffirst">
1494 The base recipe name and version but without any special
1495 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
1496 and so forth).
1497 <filename>BP</filename> is comprised of the following:
1498 <literallayout class="monospaced">
1499 ${BPN}-${PV}
1500 </literallayout>
1501 </para>
1502 </glossdef>
1503 </glossentry>
1504
1505 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
1506 <info>
1507 BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes."
1508 </info>
1509 <glossdef>
1510 <para role="glossdeffirst">
1511 This variable is a version of the
1512 <link linkend='var-PN'><filename>PN</filename></link>
1513 variable with common prefixes and suffixes
1514 removed, such as <filename>nativesdk-</filename>,
1515 <filename>-cross</filename>,
1516 <filename>-native</filename>, and multilib's
1517 <filename>lib64-</filename> and
1518 <filename>lib32-</filename>.
1519 The exact lists of prefixes and suffixes removed are
1520 specified by the
1521 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link>
1522 and
1523 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link>
1524 variables, respectively.
1525 </para>
1526 </glossdef>
1527 </glossentry>
1528
1529 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
1530 <info>
1531 BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe."
1532 </info>
1533 <glossdef>
1534 <para role="glossdeffirst">
1535 Specifies a URL for an upstream bug tracking website for
1536 a recipe.
1537 The OpenEmbedded build system does not use this variable.
1538 Rather, the variable is a useful pointer in case a bug
1539 in the software being built needs to be manually reported.
1540 </para>
1541 </glossdef>
1542 </glossentry>
1543
1544 <glossentry id='var-BUILD_ARCH'><glossterm>BUILD_ARCH</glossterm>
1545 <info>
1546 BUILD_ARCH[doc] = "The name of the building architecture (e.g. i686)."
1547 </info>
1548 <glossdef>
1549 <para role="glossdeffirst">
1550 Specifies the architecture of the build host
1551 (e.g. <filename>i686</filename>).
1552 The OpenEmbedded build system sets the value of
1553 <filename>BUILD_ARCH</filename> from the machine name
1554 reported by the <filename>uname</filename> command.
1555 </para>
1556 </glossdef>
1557 </glossentry>
1558
1559 <glossentry id='var-BUILD_AS_ARCH'><glossterm>BUILD_AS_ARCH</glossterm>
1560 <info>
1561 BUILD_AS_ARCH[doc] = "Specifies the architecture-specific assembler flags for the build host."
1562 </info>
1563 <glossdef>
1564 <para role="glossdeffirst">
1565 Specifies the architecture-specific assembler flags for
1566 the build host. By default, the value of
1567 <filename>BUILD_AS_ARCH</filename> is empty.
1568 </para>
1569 </glossdef>
1570 </glossentry>
1571
1572 <glossentry id='var-BUILD_CC_ARCH'><glossterm>BUILD_CC_ARCH</glossterm>
1573 <info>
1574 BUILD_CC_ARCH[doc] = "Specifies the architecture-specific C compiler flags for the build host."
1575 </info>
1576 <glossdef>
1577 <para role="glossdeffirst">
1578 Specifies the architecture-specific C compiler flags for
1579 the build host. By default, the value of
1580 <filename>BUILD_CC_ARCH</filename> is empty.
1581 </para>
1582 </glossdef>
1583 </glossentry>
1584
1585 <glossentry id='var-BUILD_CCLD'><glossterm>BUILD_CCLD</glossterm>
1586 <info>
1587 BUILD_CCLD[doc] = "Specifies the linker command to be used for the build host when the C compiler is being used as the linker."
1588 </info>
1589 <glossdef>
1590 <para role="glossdeffirst">
1591 Specifies the linker command to be used for the build host
1592 when the C compiler is being used as the linker. By default,
1593 <filename>BUILD_CCLD</filename> points to GCC and passes as
1594 arguments the value of
1595 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1596 assuming <filename>BUILD_CC_ARCH</filename> is set.
1597 </para>
1598 </glossdef>
1599 </glossentry>
1600
1601 <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>
1602 <info>
1603 BUILD_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the build host."
1604 </info>
1605 <glossdef>
1606 <para role="glossdeffirst">
1607 Specifies the flags to pass to the C compiler when building
1608 for the build host.
1609 When building in the <filename>-native</filename> context,
1610 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1611 is set to the value of this variable by default.
1612 </para>
1613 </glossdef>
1614 </glossentry>
1615
1616 <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
1617 <info>
1618 BUILD_CPPFLAGS[doc] = "Specifies the flags to pass to the C preprocessor (i.e. to both the C and the C++ compilers) when building for the build host."
1619 </info>
1620 <glossdef>
1621 <para role="glossdeffirst">
1622 Specifies the flags to pass to the C preprocessor
1623 (i.e. to both the C and the C++ compilers) when building
1624 for the build host.
1625 When building in the <filename>-native</filename> context,
1626 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
1627 is set to the value of this variable by default.
1628 </para>
1629 </glossdef>
1630 </glossentry>
1631
1632 <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>
1633 <info>
1634 BUILD_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the build host."
1635 </info>
1636 <glossdef>
1637 <para role="glossdeffirst">
1638 Specifies the flags to pass to the C++ compiler when
1639 building for the build host.
1640 When building in the <filename>-native</filename> context,
1641 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
1642 is set to the value of this variable by default.
1643 </para>
1644 </glossdef>
1645 </glossentry>
1646
1647 <glossentry id='var-BUILD_FC'><glossterm>BUILD_FC</glossterm>
1648 <info>
1649 BUILD_FC[doc] = "Specifies the Fortran compiler command for the build host."
1650 </info>
1651 <glossdef>
1652 <para role="glossdeffirst">
1653 Specifies the Fortran compiler command for the build host.
1654 By default, <filename>BUILD_FC</filename> points to
1655 Gfortran and passes as arguments the value of
1656 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1657 assuming <filename>BUILD_CC_ARCH</filename> is set.
1658 </para>
1659 </glossdef>
1660 </glossentry>
1661
1662 <glossentry id='var-BUILD_LD'><glossterm>BUILD_LD</glossterm>
1663 <info>
1664 BUILD_LD[doc] = "Specifies the linker command for the build host."
1665 </info>
1666 <glossdef>
1667 <para role="glossdeffirst">
1668 Specifies the linker command for the build host. By default,
1669 <filename>BUILD_LD</filename> points to the GNU linker (ld)
1670 and passes as arguments the value of
1671 <link linkend='var-BUILD_LD_ARCH'><filename>BUILD_LD_ARCH</filename></link>,
1672 assuming <filename>BUILD_LD_ARCH</filename> is set.
1673 </para>
1674 </glossdef>
1675 </glossentry>
1676
1677 <glossentry id='var-BUILD_LD_ARCH'><glossterm>BUILD_LD_ARCH</glossterm>
1678 <info>
1679 BUILD_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the build."
1680 </info>
1681 <glossdef>
1682 <para role="glossdeffirst">
1683 Specifies architecture-specific linker flags for the build
1684 host. By default, the value of
1685 <filename>BUILD_LD_ARCH</filename> is empty.
1686 </para>
1687 </glossdef>
1688 </glossentry>
1689
1690 <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>
1691 <info>
1692 BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host."
1693 </info>
1694 <glossdef>
1695 <para role="glossdeffirst">
1696 Specifies the flags to pass to the linker when building
1697 for the build host.
1698 When building in the <filename>-native</filename> context,
1699 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1700 is set to the value of this variable by default.
1701 </para>
1702 </glossdef>
1703 </glossentry>
1704
1705 <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>
1706 <info>
1707 BUILD_OPTIMIZATION[doc] = "Specifies the optimization flags passed to the C compiler when building for the build host or the SDK."
1708 </info>
1709 <glossdef>
1710 <para role="glossdeffirst">
1711 Specifies the optimization flags passed to the C compiler
1712 when building for the build host or the SDK.
1713 The flags are passed through the
1714 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1715 and
1716 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1717 default values.
1718 </para>
1719
1720 <para>
1721 The default value of the
1722 <filename>BUILD_OPTIMIZATION</filename> variable is
1723 "-O2 -pipe".
1724 </para>
1725 </glossdef>
1726 </glossentry>
1727
1728 <glossentry id='var-BUILD_OS'><glossterm>BUILD_OS</glossterm>
1729 <info>
1730 BUILD_OS[doc] = "The operating system (in lower case) of the building architecture (e.g. Linux)."
1731 </info>
1732 <glossdef>
1733 <para role="glossdeffirst">
1734 Specifies the operating system in use on the build
1735 host (e.g. "linux").
1736 The OpenEmbedded build system sets the value of
1737 <filename>BUILD_OS</filename> from the OS reported by
1738 the <filename>uname</filename> command - the first word,
1739 converted to lower-case characters.
1740 </para>
1741 </glossdef>
1742 </glossentry>
1743
1744 <glossentry id='var-BUILD_PREFIX'><glossterm>BUILD_PREFIX</glossterm>
1745 <info>
1746 BUILD_PREFIX[doc] = "The toolchain binary prefix used for native recipes."
1747 </info>
1748 <glossdef>
1749 <para role="glossdeffirst">
1750 The toolchain binary prefix used for native recipes.
1751 The OpenEmbedded build system uses the
1752 <filename>BUILD_PREFIX</filename> value to set the
1753 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
1754 when building for <filename>native</filename> recipes.
1755 </para>
1756 </glossdef>
1757 </glossentry>
1758
1759 <glossentry id='var-BUILD_STRIP'><glossterm>BUILD_STRIP</glossterm>
1760 <info>
1761 BUILD_STRIP[doc] = "Specifies the command to be used to strip debugging symbols from binaries produced for the build host."
1762 </info>
1763 <glossdef>
1764 <para role="glossdeffirst">
1765 Specifies the command to be used to strip debugging symbols
1766 from binaries produced for the build host. By default,
1767 <filename>BUILD_STRIP</filename> points to
1768 <filename>${</filename><link linkend='var-BUILD_PREFIX'><filename>BUILD_PREFIX</filename></link><filename>}strip</filename>.
1769 </para>
1770 </glossdef>
1771 </glossentry>
1772
1773 <glossentry id='var-BUILD_SYS'><glossterm>BUILD_SYS</glossterm>
1774 <info>
1775 BUILD_SYS[doc] = "The toolchain binary prefix used for native recipes."
1776 </info>
1777 <glossdef>
1778 <para role="glossdeffirst">
1779 Specifies the system, including the architecture and
1780 the operating system, to use when building for the build
1781 host (i.e. when building <filename>native</filename>
1782 recipes).
1783 </para>
1784
1785 <para>
1786 The OpenEmbedded build system automatically sets this
1787 variable based on
1788 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>,
1789 <link linkend='var-BUILD_VENDOR'><filename>BUILD_VENDOR</filename></link>,
1790 and
1791 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
1792 You do not need to set the <filename>BUILD_SYS</filename>
1793 variable yourself.
1794 </para>
1795 </glossdef>
1796 </glossentry>
1797
1798 <glossentry id='var-BUILD_VENDOR'><glossterm>BUILD_VENDOR</glossterm>
1799 <info>
1800 BUILD_VENDOR[doc] = "The vendor name to use when building for the build host."
1801 </info>
1802 <glossdef>
1803 <para role="glossdeffirst">
1804 Specifies the vendor name to use when building for the
1805 build host.
1806 The default value is an empty string ("").
1807 </para>
1808 </glossdef>
1809 </glossentry>
1810
1811 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
1812 <info>
1813 BUILDDIR[doc] = "Points to the location of the Build Directory."
1814 </info>
1815 <glossdef>
1816 <para role="glossdeffirst">
1817 Points to the location of the
1818 <link linkend='build-directory'>Build Directory</link>.
1819 You can define this directory indirectly through the
1820 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
1821 script by passing in a Build Directory path when you run
1822 the script.
1823 If you run the script and do not provide a Build Directory
1824 path, the <filename>BUILDDIR</filename> defaults to
1825 <filename>build</filename> in the current directory.
1826 </para>
1827 </glossdef>
1828 </glossentry>
1829
1830 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
1831 <info>
1832 BUILDHISTORY_COMMIT[doc] = "When inheriting the buildhistory class, this variable specifies whether or not to commit the build history output in a local Git repository."
1833 </info>
1834 <glossdef>
1835 <para role="glossdeffirst">
1836 When inheriting the
1837 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1838 class, this variable specifies whether or not to commit the
1839 build history output in a local Git repository.
1840 If set to "1", this local repository will be maintained
1841 automatically by the
1842 <filename>buildhistory</filename>
1843 class and a commit will be created on every
1844 build for changes to each top-level subdirectory of the
1845 build history output (images, packages, and sdk).
1846 If you want to track changes to build history over
1847 time, you should set this value to "1".
1848 </para>
1849
1850 <para>
1851 By default, the <filename>buildhistory</filename> class
1852 does not commit the build history output in a local
1853 Git repository:
1854 <literallayout class='monospaced'>
1855 BUILDHISTORY_COMMIT ?= "0"
1856 </literallayout>
1857 </para>
1858 </glossdef>
1859 </glossentry>
1860
1861 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
1862 <info>
1863 BUILDHISTORY_COMMIT_AUTHOR[doc] = "When inheriting the buildhistory class, this variable specifies the author to use for each Git commit."
1864 </info>
1865 <glossdef>
1866 <para role="glossdeffirst">
1867 When inheriting the
1868 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1869 class, this variable specifies the author to use for each
1870 Git commit.
1871 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
1872 variable to work, the
1873 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1874 variable must be set to "1".
1875 </para>
1876
1877 <para>
1878 Git requires that the value you provide for the
1879 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
1880 takes the form of "name <replaceable>email@host</replaceable>".
1881 Providing an email address or host that is not valid does
1882 not produce an error.
1883 </para>
1884
1885 <para>
1886 By default, the <filename>buildhistory</filename> class
1887 sets the variable as follows:
1888 <literallayout class='monospaced'>
1889 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
1890 </literallayout>
1891 </para>
1892 </glossdef>
1893 </glossentry>
1894
1895 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
1896 <info>
1897 BUILDHISTORY_DIR[doc] = "When inheriting the buildhistory class, this variable specifies the directory in which build history information is kept."
1898 </info>
1899 <glossdef>
1900 <para role="glossdeffirst">
1901 When inheriting the
1902 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1903 class, this variable specifies the directory in which
1904 build history information is kept.
1905 For more information on how the variable works, see the
1906 <filename>buildhistory.class</filename>.
1907 </para>
1908
1909 <para>
1910 By default, the <filename>buildhistory</filename> class
1911 sets the directory as follows:
1912 <literallayout class='monospaced'>
1913 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1914 </literallayout>
1915 </para>
1916 </glossdef>
1917 </glossentry>
1918
1919 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
1920 <info>
1921 BUILDHISTORY_FEATURES[doc] = "When inheriting the buildhistory class, this variable specifies the build history features to be enabled."
1922 </info>
1923 <glossdef>
1924 <para role="glossdeffirst">
1925 When inheriting the
1926 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1927 class, this variable specifies the build history features
1928 to be enabled.
1929 For more information on how build history works, see the
1930 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1931 section in the Yocto Project Development Tasks Manual.
1932 </para>
1933
1934 <para>
1935 You can specify these features in the form of a
1936 space-separated list:
1937 <itemizedlist>
1938 <listitem><para><emphasis>image:</emphasis>
1939 Analysis of the contents of images, which
1940 includes the list of installed packages among other
1941 things.
1942 </para></listitem>
1943 <listitem><para><emphasis>package:</emphasis>
1944 Analysis of the contents of individual packages.
1945 </para></listitem>
1946 <listitem><para><emphasis>sdk:</emphasis>
1947 Analysis of the contents of the software
1948 development kit (SDK).
1949 </para></listitem>
1950 <listitem><para><emphasis>task:</emphasis>
1951 Save output file signatures for
1952 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
1953 (sstate) tasks.
1954 This saves one file per task and lists the SHA-256
1955 checksums for each file staged (i.e. the output of
1956 the task).
1957 </para></listitem>
1958 </itemizedlist>
1959 </para>
1960
1961 <para>
1962 By default, the <filename>buildhistory</filename> class
1963 enables the following features:
1964 <literallayout class='monospaced'>
1965 BUILDHISTORY_FEATURES ?= "image package sdk"
1966 </literallayout>
1967 </para>
1968 </glossdef>
1969 </glossentry>
1970
1971 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
1972 <info>
1973 BUILDHISTORY_IMAGE_FILES[doc] = "When inheriting the buildhistory class, this variable specifies a list of paths to files copied from the image contents into the build history directory under an "image-files" directory in the directory for the image, so that you can track the contents of each file."
1974 </info>
1975 <glossdef>
1976 <para role="glossdeffirst">
1977 When inheriting the
1978 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1979 class, this variable specifies a list of paths to files
1980 copied from the
1981 image contents into the build history directory under
1982 an "image-files" directory in the directory for
1983 the image, so that you can track the contents of each file.
1984 The default is to copy <filename>/etc/passwd</filename>
1985 and <filename>/etc/group</filename>, which allows you to
1986 monitor for changes in user and group entries.
1987 You can modify the list to include any file.
1988 Specifying an invalid path does not produce an error.
1989 Consequently, you can include files that might
1990 not always be present.
1991 </para>
1992
1993 <para>
1994 By default, the <filename>buildhistory</filename> class
1995 provides paths to the following files:
1996 <literallayout class='monospaced'>
1997 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1998 </literallayout>
1999 </para>
2000 </glossdef>
2001 </glossentry>
2002
2003 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
2004 <info>
2005 BUILDHISTORY_PUSH_REPO[doc] = "When inheriting the buildhistory class, this variable optionally specifies a remote repository to which build history pushes Git changes."
2006 </info>
2007 <glossdef>
2008 <para role="glossdeffirst">
2009 When inheriting the
2010 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
2011 class, this variable optionally specifies a remote
2012 repository to which build history pushes Git changes.
2013 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
2014 to work,
2015 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
2016 must be set to "1".
2017 </para>
2018
2019 <para>
2020 The repository should correspond to a remote
2021 address that specifies a repository as understood by
2022 Git, or alternatively to a remote name that you have
2023 set up manually using <filename>git remote</filename>
2024 within the local repository.
2025 </para>
2026
2027 <para>
2028 By default, the <filename>buildhistory</filename> class
2029 sets the variable as follows:
2030 <literallayout class='monospaced'>
2031 BUILDHISTORY_PUSH_REPO ?= ""
2032 </literallayout>
2033 </para>
2034 </glossdef>
2035 </glossentry>
2036
2037 <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>
2038 <info>
2039 BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK."
2040 </info>
2041 <glossdef>
2042 <para role="glossdeffirst">
2043 Specifies the flags to pass to the C compiler when building
2044 for the SDK.
2045 When building in the <filename>nativesdk-</filename>
2046 context,
2047 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
2048 is set to the value of this variable by default.
2049 </para>
2050 </glossdef>
2051 </glossentry>
2052
2053 <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>
2054 <info>
2055 BUILDSDK_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the SDK."
2056 </info>
2057 <glossdef>
2058 <para role="glossdeffirst">
2059 Specifies the flags to pass to the C pre-processor
2060 (i.e. to both the C and the C++ compilers) when building
2061 for the SDK.
2062 When building in the <filename>nativesdk-</filename>
2063 context,
2064 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
2065 is set to the value of this variable by default.
2066 </para>
2067 </glossdef>
2068 </glossentry>
2069
2070 <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>
2071 <info>
2072 BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK."
2073 </info>
2074 <glossdef>
2075 <para role="glossdeffirst">
2076 Specifies the flags to pass to the C++ compiler when
2077 building for the SDK.
2078 When building in the <filename>nativesdk-</filename>
2079 context,
2080 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
2081 is set to the value of this variable by default.
2082 </para>
2083 </glossdef>
2084 </glossentry>
2085
2086 <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>
2087 <info>
2088 BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK."
2089 </info>
2090 <glossdef>
2091 <para role="glossdeffirst">
2092 Specifies the flags to pass to the linker when building
2093 for the SDK.
2094 When building in the <filename>nativesdk-</filename>
2095 context,
2096 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
2097 is set to the value of this variable by default.
2098 </para>
2099 </glossdef>
2100 </glossentry>
2101
2102 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
2103 <info>
2104 BUILDSTATS_BASE[doc] = "Points to the location of the directory that holds build statistics when you use and enable the buildstats class."
2105 </info>
2106 <glossdef>
2107 <para role="glossdeffirst">
2108 Points to the location of the directory that holds build
2109 statistics when you use and enable the
2110 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
2111 class.
2112 The <filename>BUILDSTATS_BASE</filename> directory defaults
2113 to
2114 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
2115 </para>
2116 </glossdef>
2117 </glossentry>
2118
2119 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
2120 <info>
2121 BUSYBOX_SPLIT_SUID[doc] = "For the BusyBox recipe, specifies whether to split the output executable file into two parts: one for features that require setuid root, and one for the remaining features."
2122 </info>
2123 <glossdef>
2124 <para role="glossdeffirst">
2125 For the BusyBox recipe, specifies whether to split the
2126 output executable file into two parts: one for features
2127 that require <filename>setuid root</filename>, and one for
2128 the remaining features (i.e. those that do not require
2129 <filename>setuid root</filename>).
2130 </para>
2131
2132 <para>
2133 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
2134 defaults to "1", which results in splitting the output
2135 executable file.
2136 Set the variable to "0" to get a single output executable
2137 file.
2138 </para>
2139 </glossdef>
2140 </glossentry>
2141
2142 </glossdiv>
2143
2144 <glossdiv id='var-glossary-c'><title>C</title>
2145
2146 <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
2147 <info>
2148 CACHE[doc] = "The directory BitBake uses to store a cache of the metadata."
2149 </info>
2150 <glossdef>
2151 <para role="glossdeffirst">
2152 Specifies the directory BitBake uses to store a cache
2153 of the
2154 <link linkend='metadata'>Metadata</link>
2155 so it does not need to be parsed every time BitBake is
2156 started.
2157 </para>
2158 </glossdef>
2159 </glossentry>
2160
2161 <glossentry id='var-CC'><glossterm>CC</glossterm>
2162 <info>
2163 CC[doc] = "Minimum command and arguments to run the C compiler."
2164 </info>
2165 <glossdef>
2166 <para role="glossdeffirst">
2167 The minimal command and arguments used to run the C
2168 compiler.
2169 </para>
2170 </glossdef>
2171 </glossentry>
2172
2173 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
2174 <info>
2175 CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as TARGET_CFLAGS."
2176 </info>
2177 <glossdef>
2178 <para role="glossdeffirst">
2179 Specifies the flags to pass to the C compiler.
2180 This variable is exported to an environment
2181 variable and thus made visible to the software being
2182 built during the compilation step.
2183 </para>
2184
2185 <para>
2186 Default initialization for <filename>CFLAGS</filename>
2187 varies depending on what is being built:
2188 <itemizedlist>
2189 <listitem><para>
2190 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
2191 when building for the target
2192 </para></listitem>
2193 <listitem><para>
2194 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
2195 when building for the build host (i.e.
2196 <filename>-native</filename>)
2197 </para></listitem>
2198 <listitem><para>
2199 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
2200 when building for an SDK (i.e.
2201 <filename>nativesdk-</filename>)
2202 </para></listitem>
2203 </itemizedlist>
2204 </para>
2205 </glossdef>
2206 </glossentry>
2207
2208 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
2209 <info>
2210 CLASSOVERRIDE[doc] = "An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth)."
2211 </info>
2212 <glossdef>
2213 <para role="glossdeffirst">
2214 An internal variable specifying the special class override
2215 that should currently apply (e.g. "class-target",
2216 "class-native", and so forth).
2217 The classes that use this variable (e.g.
2218 <link linkend='ref-classes-native'><filename>native</filename></link>,
2219 <link linkend='ref-classes-nativesdk'><filename>nativesdk</filename></link>,
2220 and so forth) set the variable to appropriate values.
2221 <note>
2222 <filename>CLASSOVERRIDE</filename> gets its default
2223 "class-target" value from the
2224 <filename>bitbake.conf</filename> file.
2225 </note>
2226 </para>
2227
2228 <para>
2229 As an example, the following override allows you to install
2230 extra files, but only when building for the target:
2231 <literallayout class='monospaced'>
2232 do_install_append_class-target() {
2233 install my-extra-file ${D}${sysconfdir}
2234 }
2235 </literallayout>
2236 Here is an example where <filename>FOO</filename>
2237 is set to "native" when building for the build host, and
2238 to "other" when not building for the build host:
2239 <literallayout class='monospaced'>
2240 FOO_class-native = "native"
2241 FOO = "other"
2242 </literallayout>
2243 The underlying mechanism behind
2244 <filename>CLASSOVERRIDE</filename> is simply that it is
2245 included in the default value of
2246 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
2247 </para>
2248 </glossdef>
2249 </glossentry>
2250
2251 <glossentry id='var-CLEANBROKEN'><glossterm>CLEANBROKEN</glossterm>
2252 <info>
2253 CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task."
2254 </info>
2255 <glossdef>
2256 <para role="glossdeffirst">
2257 If set to "1" within a recipe,
2258 <filename>CLEANBROKEN</filename> specifies that
2259 the <filename>make clean</filename> command does
2260 not work for the software being built.
2261 Consequently, the OpenEmbedded build system will not try
2262 to run <filename>make clean</filename> during the
2263 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2264 task, which is the default behavior.
2265 </para>
2266 </glossdef>
2267 </glossentry>
2268
2269 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
2270 <info>
2271 COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES."
2272 </info>
2273 <glossdef>
2274 <para role="glossdeffirst">
2275 Provides a list of hardware features that are enabled in
2276 both
2277 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
2278 and
2279 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2280 This select list of features contains features that make
2281 sense to be controlled both at the machine and distribution
2282 configuration level.
2283 For example, the "bluetooth" feature requires hardware
2284 support but should also be optional at the distribution
2285 level, in case the hardware supports Bluetooth but you
2286 do not ever intend to use it.
2287 </para>
2288 </glossdef>
2289 </glossentry>
2290
2291 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
2292 <info>
2293 COMMON_LICENSE_DIR[doc] = "Points to meta/files/common-licenses in the Source Directory, which is where generic license files reside."
2294 </info>
2295 <glossdef>
2296 <para role="glossdeffirst">
2297 Points to <filename>meta/files/common-licenses</filename>
2298 in the
2299 <link linkend='source-directory'>Source Directory</link>,
2300 which is where generic license files reside.
2301 </para>
2302 </glossdef>
2303 </glossentry>
2304
2305 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
2306 <info>
2307 COMPATIBLE_HOST[doc] = "A regular expression that resolves to one or more hosts (when the recipe is native) or one or more targets (when the recipe is non-native) with which a recipe is compatible."
2308 </info>
2309 <glossdef>
2310 <para role="glossdeffirst">
2311 A regular expression that resolves to one or more hosts
2312 (when the recipe is native) or one or more targets (when
2313 the recipe is non-native) with which a recipe is compatible.
2314 The regular expression is matched against
2315 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
2316 You can use the variable to stop recipes from being built
2317 for classes of systems with which the recipes are not
2318 compatible.
2319 Stopping these builds is particularly useful with kernels.
2320 The variable also helps to increase parsing speed
2321 since the build system skips parsing recipes not
2322 compatible with the current system.
2323 </para>
2324 </glossdef>
2325 </glossentry>
2326
2327 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
2328 <info>
2329 COMPATIBLE_MACHINE[doc] = "A regular expression that resolves to one or more target machines with which a recipe is compatible."
2330 </info>
2331 <glossdef>
2332 <para role="glossdeffirst">
2333 A regular expression that resolves to one or more
2334 target machines with which a recipe is compatible.
2335 The regular expression is matched against
2336 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
2337 You can use the variable to stop recipes from being built
2338 for machines with which the recipes are not compatible.
2339 Stopping these builds is particularly useful with kernels.
2340 The variable also helps to increase parsing speed
2341 since the build system skips parsing recipes not
2342 compatible with the current machine.
2343 </para>
2344 </glossdef>
2345 </glossentry>
2346
2347 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
2348 <info>
2349 COMPLEMENTARY_GLOB[doc] = "Defines wildcards to match when installing a list of complementary packages for all the packages installed in an image."
2350 </info>
2351 <glossdef>
2352 <para role="glossdeffirst">
2353 Defines wildcards to match when installing a list of
2354 complementary packages for all the packages explicitly
2355 (or implicitly) installed in an image.
2356 <note>
2357 The <filename>COMPLEMENTARY_GLOB</filename> variable
2358 uses Unix filename pattern matching
2359 (<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>),
2360 which is similar to the Unix style pathname pattern
2361 expansion
2362 (<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>).
2363 </note>
2364 The resulting list of complementary packages is associated
2365 with an item that can be added to
2366 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2367 An example usage of this is the "dev-pkgs" item that when
2368 added to <filename>IMAGE_FEATURES</filename> will
2369 install -dev packages (containing headers and other
2370 development files) for every package in the image.
2371 </para>
2372
2373 <para>
2374 To add a new feature item pointing to a wildcard, use a
2375 variable flag to specify the feature item name and
2376 use the value to specify the wildcard.
2377 Here is an example:
2378 <literallayout class='monospaced'>
2379 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
2380 </literallayout>
2381 </para>
2382 </glossdef>
2383 </glossentry>
2384
2385 <glossentry id='var-COMPONENTS_DIR'><glossterm>COMPONENTS_DIR</glossterm>
2386 <info>
2387 COMPONENTS_DIR[doc] = "Stores sysroot components for each recipe."
2388 </info>
2389 <glossdef>
2390 <para role="glossdeffirst">
2391 Stores sysroot components for each recipe.
2392 The OpenEmbedded build system uses
2393 <filename>COMPONENTS_DIR</filename> when constructing
2394 recipe-specific sysroots for other recipes.
2395 </para>
2396
2397 <para>
2398 The default is
2399 "<filename>${</filename><link linkend='var-STAGING_DIR'><filename>STAGING_DIR</filename></link><filename>}-components</filename>."
2400 (i.e. "<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots-components</filename>").
2401 </para>
2402 </glossdef>
2403 </glossentry>
2404
2405 <glossentry id='var-CONF_VERSION'><glossterm>CONF_VERSION</glossterm>
2406 <info>
2407 CONF_VERSION[doc] = "Tracks the version of local.conf. Increased each time build/conf/ changes incompatibly."
2408 </info>
2409 <glossdef>
2410 <para role="glossdeffirst">
2411 Tracks the version of the local configuration file
2412 (i.e. <filename>local.conf</filename>).
2413 The value for <filename>CONF_VERSION</filename>
2414 increments each time <filename>build/conf/</filename>
2415 compatibility changes.
2416 </para>
2417 </glossdef>
2418 </glossentry>
2419
2420 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
2421 <info>
2422 CONFFILES[doc] = "Identifies editable or configurable files that are part of a package."
2423 </info>
2424 <glossdef>
2425 <para role="glossdeffirst">
2426 Identifies editable or configurable files that are part of a package.
2427 If the Package Management System (PMS) is being used to update
2428 packages on the target system, it is possible that
2429 configuration files you have changed after the original installation
2430 and that you now want to remain unchanged are overwritten.
2431 In other words, editable files might exist in the package that you do not
2432 want reset as part of the package update process.
2433 You can use the <filename>CONFFILES</filename> variable to list the files in the
2434 package that you wish to prevent the PMS from overwriting during this update process.
2435 </para>
2436
2437 <para>
2438 To use the <filename>CONFFILES</filename> variable, provide a package name
2439 override that identifies the resulting package.
2440 Then, provide a space-separated list of files.
2441 Here is an example:
2442 <literallayout class='monospaced'>
2443 CONFFILES_${PN} += "${sysconfdir}/file1 \
2444 ${sysconfdir}/file2 ${sysconfdir}/file3"
2445 </literallayout>
2446 </para>
2447
2448 <para>
2449 A relationship exists between the <filename>CONFFILES</filename> and
2450 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
2451 The files listed within <filename>CONFFILES</filename> must be a subset of
2452 the files listed within <filename>FILES</filename>.
2453 Because the configuration files you provide with <filename>CONFFILES</filename>
2454 are simply being identified so that the PMS will not overwrite them,
2455 it makes sense that
2456 the files must already be included as part of the package through the
2457 <filename>FILES</filename> variable.
2458 </para>
2459
2460 <note>
2461 When specifying paths as part of the <filename>CONFFILES</filename> variable,
2462 it is good practice to use appropriate path variables.
2463 For example, <filename>${sysconfdir}</filename> rather than
2464 <filename>/etc</filename> or <filename>${bindir}</filename> rather
2465 than <filename>/usr/bin</filename>.
2466 You can find a list of these variables at the top of the
2467 <filename>meta/conf/bitbake.conf</filename> file in the
2468 <link linkend='source-directory'>Source Directory</link>.
2469 </note>
2470 </glossdef>
2471 </glossentry>
2472
2473 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
2474 <info>
2475 CONFIG_INITRAMFS_SOURCE[doc] = "Identifies the initial RAM filesystem (initramfs) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable."
2476 </info>
2477 <glossdef>
2478 <para role="glossdeffirst">
2479 Identifies the initial RAM filesystem (initramfs) source
2480 files.
2481 The OpenEmbedded build system receives and uses
2482 this kernel Kconfig variable as an environment variable.
2483 By default, the variable is set to null ("").
2484 </para>
2485
2486 <para>
2487 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
2488 either a single cpio archive with a
2489 <filename>.cpio</filename> suffix or a
2490 space-separated list of directories and files for building
2491 the initramfs image.
2492 A cpio archive should contain a filesystem archive
2493 to be used as an initramfs image.
2494 Directories should contain a filesystem layout to be
2495 included in the initramfs image.
2496 Files should contain entries according to the format
2497 described by the
2498 <filename>usr/gen_init_cpio</filename> program in the
2499 kernel tree.
2500 </para>
2501
2502 <para>
2503 If you specify multiple directories and files, the
2504 initramfs image will be the aggregate of all of them.
2505 </para>
2506
2507 <para>
2508 For information on creating an initramfs, see the
2509 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
2510 section in the Yocto Project Development Tasks Manual.
2511 </para>
2512 </glossdef>
2513 </glossentry>
2514
2515 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
2516 <info>
2517 CONFIG_SITE[doc] = "A list of files that contains autoconf test results relevant to the current build. This variable is used by the Autotools utilities when running configure."
2518 </info>
2519 <glossdef>
2520 <para role="glossdeffirst">
2521 A list of files that contains <filename>autoconf</filename> test results relevant
2522 to the current build.
2523 This variable is used by the Autotools utilities when running
2524 <filename>configure</filename>.
2525 </para>
2526 </glossdef>
2527 </glossentry>
2528
2529 <glossentry id='var-CONFIGURE_FLAGS'><glossterm>CONFIGURE_FLAGS</glossterm>
2530 <info>
2531 CONFIGURE_FLAGS[doc] = "The minimal arguments for GNU configure."
2532 </info>
2533 <glossdef>
2534 <para role="glossdeffirst">
2535 The minimal arguments for GNU configure.
2536 </para>
2537 </glossdef>
2538 </glossentry>
2539
2540 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
2541 <info>
2542 CONFLICT_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that would be in conflict should the recipe be built."
2543 </info>
2544 <glossdef>
2545 <para role="glossdeffirst">
2546 When inheriting the
2547 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
2548 class, this
2549 variable identifies distribution features that would
2550 be in conflict should the recipe
2551 be built.
2552 In other words, if the
2553 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
2554 lists a feature that also appears in
2555 <filename>DISTRO_FEATURES</filename> within the
2556 current configuration, an error occurs and the
2557 build stops.
2558 </para>
2559 </glossdef>
2560 </glossentry>
2561
2562 <glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm>
2563 <info>
2564 COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class."
2565 </info>
2566 <glossdef>
2567 <para role="glossdeffirst">
2568 A space-separated list of licenses to exclude from the
2569 source archived by the
2570 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2571 class.
2572 In other words, if a license in a recipe's
2573 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2574 value is in the value of
2575 <filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its
2576 source is not archived by the class.
2577 <note>
2578 The <filename>COPYLEFT_LICENSE_EXCLUDE</filename>
2579 variable takes precedence over the
2580 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2581 variable.
2582 </note>
2583 The default value, which is "CLOSED Proprietary", for
2584 <filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set
2585 by the
2586 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2587 class, which is inherited by the
2588 <filename>archiver</filename> class.
2589 </para>
2590 </glossdef>
2591 </glossentry>
2592
2593 <glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm>
2594 <info>
2595 COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class."
2596 </info>
2597 <glossdef>
2598 <para role="glossdeffirst">
2599 A space-separated list of licenses to include in the
2600 source archived by the
2601 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2602 class.
2603 In other words, if a license in a recipe's
2604 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2605 value is in the value of
2606 <filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its
2607 source is archived by the class.
2608 </para>
2609
2610 <para>
2611 The default value is set by the
2612 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2613 class, which is inherited by the
2614 <filename>archiver</filename> class.
2615 The default value includes "GPL*", "LGPL*", and "AGPL*".
2616 </para>
2617 </glossdef>
2618 </glossentry>
2619
2620 <glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm>
2621 <info>
2622 COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class."
2623 </info>
2624 <glossdef>
2625 <para role="glossdeffirst">
2626 A list of recipes to exclude in the source archived
2627 by the
2628 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2629 class.
2630 The <filename>COPYLEFT_PN_EXCLUDE</filename> variable
2631 overrides the license inclusion and exclusion caused
2632 through the
2633 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2634 and
2635 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2636 variables, respectively.
2637 </para>
2638
2639 <para>
2640 The default value, which is "" indicating to not explicitly
2641 exclude any recipes by name, for
2642 <filename>COPYLEFT_PN_EXCLUDE</filename> is set
2643 by the
2644 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2645 class, which is inherited by the
2646 <filename>archiver</filename> class.
2647 </para>
2648 </glossdef>
2649 </glossentry>
2650
2651 <glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm>
2652 <info>
2653 COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class."
2654 </info>
2655 <glossdef>
2656 <para role="glossdeffirst">
2657 A list of recipes to include in the source archived
2658 by the
2659 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2660 class.
2661 The <filename>COPYLEFT_PN_INCLUDE</filename> variable
2662 overrides the license inclusion and exclusion caused
2663 through the
2664 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2665 and
2666 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2667 variables, respectively.
2668 </para>
2669
2670 <para>
2671 The default value, which is "" indicating to not explicitly
2672 include any recipes by name, for
2673 <filename>COPYLEFT_PN_INCLUDE</filename> is set
2674 by the
2675 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2676 class, which is inherited by the
2677 <filename>archiver</filename> class.
2678 </para>
2679 </glossdef>
2680 </glossentry>
2681
2682 <glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm>
2683 <info>
2684 COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class."
2685 </info>
2686 <glossdef>
2687 <para role="glossdeffirst">
2688 A space-separated list of recipe types to include
2689 in the source archived by the
2690 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2691 class.
2692 Recipe types are <filename>target</filename>,
2693 <filename>native</filename>,
2694 <filename>nativesdk</filename>,
2695 <filename>cross</filename>,
2696 <filename>crosssdk</filename>, and
2697 <filename>cross-canadian</filename>.
2698 </para>
2699
2700 <para>
2701 The default value, which is "target*", for
2702 <filename>COPYLEFT_RECIPE_TYPES</filename> is set
2703 by the
2704 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2705 class, which is inherited by the
2706 <filename>archiver</filename> class.
2707 </para>
2708 </glossdef>
2709 </glossentry>
2710
2711 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
2712 <info>
2713 COPY_LIC_DIRS[doc] = "If set to "1" along with the COPY_LIC_MANIFEST variable, the OpenEmbedded build system copies into the image the license files, which are located in /usr/share/common-licenses, for each package."
2714 </info>
2715 <glossdef>
2716 <para role="glossdeffirst">
2717 If set to "1" along with the
2718 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
2719 variable, the OpenEmbedded build system copies
2720 into the image the license files, which are located in
2721 <filename>/usr/share/common-licenses</filename>,
2722 for each package.
2723 The license files are placed
2724 in directories within the image itself during build time.
2725 <note>
2726 The <filename>COPY_LIC_DIRS</filename> does not
2727 offer a path for adding licenses for newly installed
2728 packages to an image, which might be most suitable
2729 for read-only filesystems that cannot be upgraded.
2730 See the
2731 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2732 variable for additional information.
2733 You can also reference the
2734 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
2735 section in the Yocto Project Development Tasks Manual
2736 for information on providing license text.
2737 </note>
2738 </para>
2739 </glossdef>
2740 </glossentry>
2741
2742 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
2743 <info>
2744 COPY_LIC_MANIFEST[doc] = "If set to "1", the OpenEmbedded build system copies the license manifest for the image to /usr/share/common-licenses/license.manifest within the image itself."
2745 </info>
2746 <glossdef>
2747 <para role="glossdeffirst">
2748 If set to "1", the OpenEmbedded build system copies
2749 the license manifest for the image to
2750 <filename>/usr/share/common-licenses/license.manifest</filename>
2751 within the image itself during build time.
2752 <note>
2753 The <filename>COPY_LIC_MANIFEST</filename> does not
2754 offer a path for adding licenses for newly installed
2755 packages to an image, which might be most suitable
2756 for read-only filesystems that cannot be upgraded.
2757 See the
2758 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2759 variable for additional information.
2760 You can also reference the
2761 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
2762 section in the Yocto Project Development Tasks Manual
2763 for information on providing license text.
2764 </note>
2765 </para>
2766 </glossdef>
2767 </glossentry>
2768
2769 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
2770 <info>
2771 CORE_IMAGE_EXTRA_INSTALL[doc] = "Specifies the list of packages to be added to the image. You should only set this variable in the conf/local.conf file in the Build Directory."
2772 </info>
2773 <glossdef>
2774 <para role="glossdeffirst">
2775 Specifies the list of packages to be added to the image.
2776 You should only set this variable in the
2777 <filename>local.conf</filename> configuration file found
2778 in the
2779 <link linkend='build-directory'>Build Directory</link>.
2780 </para>
2781
2782 <para>
2783 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
2784 </para>
2785 </glossdef>
2786 </glossentry>
2787
2788 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
2789 <info>
2790 COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. meta)."
2791 </info>
2792 <glossdef>
2793 <para role="glossdeffirst">
2794 Specifies the parent directory of the OpenEmbedded-Core
2795 Metadata layer (i.e. <filename>meta</filename>).
2796 </para>
2797
2798 <para>
2799 It is an important distinction that
2800 <filename>COREBASE</filename> points to the parent of this
2801 layer and not the layer itself.
2802 Consider an example where you have cloned the Poky Git
2803 repository and retained the <filename>poky</filename>
2804 name for your local copy of the repository.
2805 In this case, <filename>COREBASE</filename> points to
2806 the <filename>poky</filename> folder because it is the
2807 parent directory of the <filename>poky/meta</filename>
2808 layer.
2809 </para>
2810 </glossdef>
2811 </glossentry>
2812
2813 <glossentry id='var-COREBASE_FILES'><glossterm>COREBASE_FILES</glossterm>
2814 <info>
2815 COREBASE_FILES[doc] = "Lists files from the COREBASE directory that should be copied other than the layers listed in the bblayers.conf file."
2816 </info>
2817 <glossdef>
2818 <para role="glossdeffirst">
2819 Lists files from the
2820 <link linkend='var-COREBASE'><filename>COREBASE</filename></link>
2821 directory that should be copied other than the layers
2822 listed in the <filename>bblayers.conf</filename> file.
2823 The <filename>COREBASE_FILES</filename> variable exists
2824 for the purpose of copying metadata from the
2825 OpenEmbedded build system into the extensible
2826 SDK.
2827 </para>
2828
2829 <para>
2830 Explicitly listing files in <filename>COREBASE</filename>
2831 is needed because it typically contains build
2832 directories and other files that should not normally
2833 be copied into the extensible SDK.
2834 Consequently, the value of
2835 <filename>COREBASE_FILES</filename> is used in order to
2836 only copy the files that are actually needed.
2837 </para>
2838 </glossdef>
2839 </glossentry>
2840
2841 <glossentry id='var-CPP'><glossterm>CPP</glossterm>
2842 <info>
2843 CPP[doc] = "Minimum command and arguments to run the C preprocessor."
2844 </info>
2845 <glossdef>
2846 <para role="glossdeffirst">
2847 The minimal command and arguments used to run the C
2848 preprocessor.
2849 </para>
2850 </glossdef>
2851 </glossentry>
2852
2853 <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>
2854 <info>
2855 CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers)."
2856 </info>
2857 <glossdef>
2858 <para role="glossdeffirst">
2859 Specifies the flags to pass to the C pre-processor
2860 (i.e. to both the C and the C++ compilers).
2861 This variable is exported to an environment
2862 variable and thus made visible to the software being
2863 built during the compilation step.
2864 </para>
2865
2866 <para>
2867 Default initialization for <filename>CPPFLAGS</filename>
2868 varies depending on what is being built:
2869 <itemizedlist>
2870 <listitem><para>
2871 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>
2872 when building for the target
2873 </para></listitem>
2874 <listitem><para>
2875 <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link>
2876 when building for the build host (i.e.
2877 <filename>-native</filename>)
2878 </para></listitem>
2879 <listitem><para>
2880 <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link>
2881 when building for an SDK (i.e.
2882 <filename>nativesdk-</filename>)
2883 </para></listitem>
2884 </itemizedlist>
2885 </para>
2886 </glossdef>
2887 </glossentry>
2888
2889 <glossentry id='var-CROSS_COMPILE'><glossterm>CROSS_COMPILE</glossterm>
2890 <info>
2891 CROSS_COMPILE[doc] = "The toolchain binary prefix for the target tools."
2892 </info>
2893 <glossdef>
2894 <para role="glossdeffirst">
2895 The toolchain binary prefix for the target tools.
2896 The <filename>CROSS_COMPILE</filename> variable is the
2897 same as the
2898 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
2899 variable.
2900 <note>
2901 The OpenEmbedded build system sets the
2902 <filename>CROSS_COMPILE</filename> variable only in
2903 certain contexts (e.g. when building for kernel
2904 and kernel module recipes).
2905 </note>
2906 </para>
2907 </glossdef>
2908 </glossentry>
2909
2910 <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>
2911 <info>
2912 CVSDIR[doc] = "The directory where cvs checkouts will be stored in."
2913 </info>
2914 <glossdef>
2915 <para role="glossdeffirst">
2916 The directory in which files checked out under the
2917 CVS system are stored.
2918 </para>
2919 </glossdef>
2920 </glossentry>
2921
2922 <glossentry id='var-CXX'><glossterm>CXX</glossterm>
2923 <info>
2924 CXX[doc] = "Minimum command and arguments to run the C++ compiler."
2925 </info>
2926 <glossdef>
2927 <para role="glossdeffirst">
2928 The minimal command and arguments used to run the C++
2929 compiler.
2930 </para>
2931 </glossdef>
2932 </glossentry>
2933
2934 <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>
2935 <info>
2936 CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler."
2937 </info>
2938 <glossdef>
2939 <para role="glossdeffirst">
2940 Specifies the flags to pass to the C++ compiler.
2941 This variable is exported to an environment
2942 variable and thus made visible to the software being
2943 built during the compilation step.
2944 </para>
2945
2946 <para>
2947 Default initialization for <filename>CXXFLAGS</filename>
2948 varies depending on what is being built:
2949 <itemizedlist>
2950 <listitem><para>
2951 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>
2952 when building for the target
2953 </para></listitem>
2954 <listitem><para>
2955 <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link>
2956 when building for the build host (i.e.
2957 <filename>-native</filename>)
2958 </para></listitem>
2959 <listitem><para>
2960 <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
2961 when building for an SDK (i.e.
2962 <filename>nativesdk-</filename>)
2963 </para></listitem>
2964 </itemizedlist>
2965 </para>
2966 </glossdef>
2967 </glossentry>
2968
2969 </glossdiv>
2970
2971 <glossdiv id='var-glossary-d'><title>D</title>
2972
2973 <glossentry id='var-D'><glossterm>D</glossterm>
2974 <info>
2975 D[doc] = "The destination directory."
2976 </info>
2977 <glossdef>
2978 <para role="glossdeffirst">
2979 The destination directory.
2980 The location in the
2981 <link linkend='build-directory'>Build Directory</link>
2982 where components are installed by the
2983 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2984 task.
2985 This location defaults to:
2986 <literallayout class='monospaced'>
2987 ${WORKDIR}/image
2988 </literallayout>
2989 <note><title>Caution</title>
2990 Tasks that read from or write to this directory should
2991 run under
2992 <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
2993 </note>
2994 </para>
2995 </glossdef>
2996 </glossentry>
2997
2998 <glossentry id='var-DATE'><glossterm>DATE</glossterm>
2999 <info>
3000 DATE[doc] = "The date the build was started using YMD format."
3001 </info>
3002 <glossdef>
3003 <para role="glossdeffirst">
3004 The date the build was started.
3005 Dates appear using the year, month, and day (YMD) format
3006 (e.g. "20150209" for February 9th, 2015).
3007 </para>
3008 </glossdef>
3009 </glossentry>
3010
3011 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
3012 <info>
3013 DATETIME[doc] = "The date and time the build was started."
3014 </info>
3015 <glossdef>
3016 <para role="glossdeffirst">
3017 The date and time on which the current build started.
3018 The format is suitable for timestamps.
3019 </para>
3020 </glossdef>
3021 </glossentry>
3022
3023 <glossentry id='var-DEBIAN_NOAUTONAME'><glossterm>DEBIAN_NOAUTONAME</glossterm>
3024 <info>
3025 DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming."
3026 </info>
3027 <glossdef>
3028 <para role="glossdeffirst">
3029 When the
3030 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3031 class is inherited, which is the default behavior,
3032 <filename>DEBIAN_NOAUTONAME</filename> specifies a
3033 particular package should not be renamed according to
3034 Debian library package naming.
3035 You must use the package name as an override when you
3036 set this variable.
3037 Here is an example from the <filename>fontconfig</filename>
3038 recipe:
3039 <literallayout class='monospaced'>
3040 DEBIAN_NOAUTONAME_fontconfig-utils = "1"
3041 </literallayout>
3042 </para>
3043 </glossdef>
3044 </glossentry>
3045
3046 <glossentry id='var-DEBIANNAME'><glossterm>DEBIANNAME</glossterm>
3047 <info>
3048 DEBIANNAME[doc] = "Allows you to override the library name for an individual package for Debian library package renaming."
3049 </info>
3050 <glossdef>
3051 <para role="glossdeffirst">
3052 When the
3053 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3054 class is inherited, which is the default behavior,
3055 <filename>DEBIANNAME</filename> allows you to override the
3056 library name for an individual package.
3057 Overriding the library name in these cases is rare.
3058 You must use the package name as an override when you
3059 set this variable.
3060 Here is an example from the <filename>dbus</filename>
3061 recipe:
3062 <literallayout class='monospaced'>
3063 DEBIANNAME_${PN} = "dbus-1"
3064 </literallayout>
3065 </para>
3066 </glossdef>
3067 </glossentry>
3068
3069 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
3070 <info>
3071 DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable."
3072 </info>
3073 <glossdef>
3074 <para role="glossdeffirst">
3075 Specifies to build packages with debugging information.
3076 This influences the value of the
3077 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
3078 variable.
3079 </para>
3080 </glossdef>
3081 </glossentry>
3082
3083 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
3084 <info>
3085 DEBUG_OPTIMIZATION[doc] = "The options to pass in TARGET_CFLAGS and CFLAGS when compiling a system for debugging. This variable defaults to '-O -fno-omit-frame-pointer -g'."
3086 </info>
3087 <glossdef>
3088 <para role="glossdeffirst">
3089 The options to pass in
3090 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
3091 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
3092 a system for debugging.
3093 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
3094 </para>
3095 </glossdef>
3096 </glossentry>
3097
3098 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
3099 <info>
3100 DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority."
3101 </info>
3102 <glossdef>
3103 <para role="glossdeffirst">
3104 Specifies a weak bias for recipe selection priority.
3105 </para>
3106
3107 <para>
3108 The most common usage of this is variable is to set
3109 it to "-1" within a recipe for a development version of a
3110 piece of software.
3111 Using the variable in this way causes the stable version
3112 of the recipe to build by default in the absence of
3113 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
3114 being used to build the development version.
3115 </para>
3116
3117 <note>
3118 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
3119 is weak and is overridden by
3120 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
3121 if that variable is different between two layers
3122 that contain different versions of the same recipe.
3123 </note>
3124 </glossdef>
3125 </glossentry>
3126
3127 <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>
3128 <info>
3129 DEFAULTTUNE[doc] = "The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system."
3130 </info>
3131 <glossdef>
3132 <para role="glossdeffirst">
3133 The default CPU and Application Binary Interface (ABI)
3134 tunings (i.e. the "tune") used by the OpenEmbedded build
3135 system.
3136 The <filename>DEFAULTTUNE</filename> helps define
3137 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
3138 </para>
3139
3140 <para>
3141 The default tune is either implicitly or explicitly set
3142 by the machine
3143 (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).
3144 However, you can override the setting using available tunes
3145 as defined with
3146 <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>.
3147 </para>
3148 </glossdef>
3149 </glossentry>
3150
3151 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
3152 <info>
3153 DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)."
3154 </info>
3155 <glossdef>
3156 <para role="glossdeffirst">
3157 Lists a recipe's build-time dependencies.
3158 These are dependencies on other recipes whose
3159 contents (e.g. headers and shared libraries) are needed
3160 by the recipe at build time.
3161 </para>
3162
3163 <para>
3164 As an example, consider a recipe <filename>foo</filename>
3165 that contains the following assignment:
3166 <literallayout class='monospaced'>
3167 DEPENDS = "bar"
3168 </literallayout>
3169 The practical effect of the previous assignment is that
3170 all files installed by bar will be available in the
3171 appropriate staging sysroot, given by the
3172 <link linkend='var-STAGING_DIR'><filename>STAGING_DIR*</filename></link>
3173 variables, by the time the
3174 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3175 task for <filename>foo</filename> runs.
3176 This mechanism is implemented by having
3177 <filename>do_configure</filename> depend on the
3178 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
3179 task of each recipe listed in <filename>DEPENDS</filename>,
3180 through a
3181 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
3182 declaration in the
3183 <link linkend='ref-classes-base'><filename>base</filename></link>
3184 class.
3185 <note>
3186 It seldom is necessary to reference, for example,
3187 <filename>STAGING_DIR_HOST</filename> explicitly.
3188 The standard classes and build-related variables are
3189 configured to automatically use the appropriate staging
3190 sysroots.
3191 </note>
3192 As another example, <filename>DEPENDS</filename> can also
3193 be used to add utilities that run on the build machine
3194 during the build.
3195 For example, a recipe that makes use of a code generator
3196 built by the recipe <filename>codegen</filename> might have
3197 the following:
3198 <literallayout class='monospaced'>
3199 DEPENDS = "codegen-native"
3200 </literallayout>
3201 For more information, see the
3202 <link linkend='ref-classes-native'><filename>native</filename></link>
3203 class and the
3204 <link linkend='var-EXTRANATIVEPATH'><filename>EXTRANATIVEPATH</filename></link>
3205 variable.
3206 <note>
3207 <title>Notes</title>
3208 <itemizedlist>
3209 <listitem><para>
3210 <filename>DEPENDS</filename> is a list of
3211 recipe names.
3212 Or, to be more precise, it is a list of
3213 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
3214 names, which usually match recipe names.
3215 Putting a package name such as "foo-dev" in
3216 <filename>DEPENDS</filename> does not make
3217 sense.
3218 Use "foo" instead, as this will put files
3219 from all the packages that make up
3220 <filename>foo</filename>, which includes
3221 those from <filename>foo-dev</filename>, into
3222 the sysroot.
3223 </para></listitem>
3224 <listitem><para>
3225 One recipe having another recipe in
3226 <filename>DEPENDS</filename> does not by itself
3227 add any runtime dependencies between the
3228 packages produced by the two recipes.
3229 However, as explained in the
3230 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
3231 section in the Yocto Project Overview and
3232 Concepts Manual, runtime dependencies will
3233 often be added automatically, meaning
3234 <filename>DEPENDS</filename> alone is
3235 sufficient for most recipes.
3236 </para></listitem>
3237 <listitem><para>
3238 Counterintuitively,
3239 <filename>DEPENDS</filename> is often necessary
3240 even for recipes that install precompiled
3241 components.
3242 For example, if <filename>libfoo</filename>
3243 is a precompiled library that links against
3244 <filename>libbar</filename>, then
3245 linking against <filename>libfoo</filename>
3246 requires both <filename>libfoo</filename>
3247 and <filename>libbar</filename> to be available
3248 in the sysroot.
3249 Without a <filename>DEPENDS</filename> from the
3250 recipe that installs <filename>libfoo</filename>
3251 to the recipe that installs
3252 <filename>libbar</filename>, other recipes might
3253 fail to link against
3254 <filename>libfoo</filename>.
3255 </para></listitem>
3256 </itemizedlist>
3257 </note>
3258 </para>
3259
3260 <para>
3261 For information on runtime dependencies, see the
3262 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3263 variable.
3264 You can also see the
3265 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
3266 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
3267 sections in the BitBake User Manual for additional
3268 information on tasks and dependencies.
3269 </para>
3270 </glossdef>
3271 </glossentry>
3272
3273 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
3274 <info>
3275 DEPLOY_DIR[doc] = "Points to the general area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3276 </info>
3277 <glossdef>
3278 <para role="glossdeffirst">
3279 Points to the general area that the OpenEmbedded build
3280 system uses to place images, packages, SDKs, and other output
3281 files that are ready to be used outside of the build system.
3282 By default, this directory resides within the
3283 <link linkend='build-directory'>Build Directory</link>
3284 as <filename>${TMPDIR}/deploy</filename>.
3285 </para>
3286
3287 <para>
3288 For more information on the structure of the Build
3289 Directory, see
3290 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3291 section.
3292 For more detail on the contents of the
3293 <filename>deploy</filename> directory, see the
3294 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>",
3295 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",
3296 and
3297 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3298 sections all in the Yocto Project Overview and Concepts
3299 Manual.
3300 </para>
3301 </glossdef>
3302 </glossentry>
3303
3304 <glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>
3305 <info>
3306 DEPLOY_DIR_DEB[doc] = "Points to a Debian-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3307 </info>
3308 <glossdef>
3309 <para role="glossdeffirst">
3310 Points to the area that the OpenEmbedded build system uses
3311 to place Debian packages that are ready to be used outside
3312 of the build system.
3313 This variable applies only when
3314 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3315 contains "package_deb".
3316 </para>
3317
3318 <para>
3319 The BitBake configuration file initially defines the
3320 <filename>DEPLOY_DIR_DEB</filename> variable as a
3321 sub-folder of
3322 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3323 <literallayout class='monospaced'>
3324 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
3325 </literallayout>
3326 </para>
3327
3328 <para>
3329 The
3330 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>
3331 class uses the
3332 <filename>DEPLOY_DIR_DEB</filename> variable to make sure
3333 the
3334 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
3335 task writes Debian packages into the appropriate folder.
3336 For more information on how packaging works, see the
3337 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3338 section in the Yocto Project Overview and Concepts Manual.
3339 </para>
3340 </glossdef>
3341 </glossentry>
3342
3343 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
3344 <info>
3345 DEPLOY_DIR_IMAGE[doc] = "Points to the area that the OpenEmbedded build system uses to place images and other associated output files that are ready to be deployed onto the target machine."
3346 </info>
3347 <glossdef>
3348 <para role="glossdeffirst">
3349 Points to the area that the OpenEmbedded build system uses
3350 to place images and other associated output files that are
3351 ready to be deployed onto the target machine.
3352 The directory is machine-specific as it contains the
3353 <filename>${MACHINE}</filename> name.
3354 By default, this directory resides within the
3355 <link linkend='build-directory'>Build Directory</link>
3356 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
3357 </para>
3358
3359 <para>
3360 For more information on the structure of the Build
3361 Directory, see
3362 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3363 section.
3364 For more detail on the contents of the
3365 <filename>deploy</filename> directory, see the
3366 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
3367 and
3368 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3369 sections both in the Yocto Project Overview and Concepts
3370 Manual.
3371 </para>
3372 </glossdef>
3373 </glossentry>
3374
3375 <glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>
3376 <info>
3377 DEPLOY_DIR_IPK[doc] = "Points to a IPK-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3378 </info>
3379 <glossdef>
3380 <para role="glossdeffirst">
3381 Points to the area that the OpenEmbedded build system uses
3382 to place IPK packages that are ready to be used outside of
3383 the build system.
3384 This variable applies only when
3385 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3386 contains "package_ipk".
3387 </para>
3388
3389 <para>
3390 The BitBake configuration file initially defines this
3391 variable as a sub-folder of
3392 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3393 <literallayout class='monospaced'>
3394 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
3395 </literallayout>
3396 </para>
3397
3398 <para>
3399 The
3400 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>
3401 class uses the
3402 <filename>DEPLOY_DIR_IPK</filename> variable to make sure
3403 the
3404 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
3405 task writes IPK packages into the appropriate folder.
3406 For more information on how packaging works, see the
3407 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3408 section in the Yocto Project Overview and Concepts Manual.
3409 </para>
3410 </glossdef>
3411 </glossentry>
3412
3413 <glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>
3414 <info>
3415 DEPLOY_DIR_RPM[doc] = "Points to a RPM-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3416 </info>
3417 <glossdef>
3418 <para role="glossdeffirst">
3419 Points to the area that the OpenEmbedded build system uses
3420 to place RPM packages that are ready to be used outside
3421 of the build system.
3422 This variable applies only when
3423 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3424 contains "package_rpm".
3425 </para>
3426
3427 <para>
3428 The BitBake configuration file initially defines this
3429 variable as a sub-folder of
3430 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3431 <literallayout class='monospaced'>
3432 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
3433 </literallayout>
3434 </para>
3435
3436 <para>
3437 The
3438 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>
3439 class uses the
3440 <filename>DEPLOY_DIR_RPM</filename> variable to make sure
3441 the
3442 <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
3443 task writes RPM packages into the appropriate folder.
3444 For more information on how packaging works, see the
3445 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3446 section in the Yocto Project Overview and Concepts Manual.
3447 </para>
3448 </glossdef>
3449 </glossentry>
3450
3451 <glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>
3452 <info>
3453 DEPLOY_DIR_TAR[doc] = "Points to a tarball area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3454 </info>
3455 <glossdef>
3456 <para role="glossdeffirst">
3457 Points to the area that the OpenEmbedded build system uses
3458 to place tarballs that are ready to be used outside of
3459 the build system.
3460 This variable applies only when
3461 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3462 contains "package_tar".
3463 </para>
3464
3465 <para>
3466 The BitBake configuration file initially defines this
3467 variable as a sub-folder of
3468 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3469 <literallayout class='monospaced'>
3470 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
3471 </literallayout>
3472 </para>
3473
3474 <para>
3475 The
3476 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3477 class uses the
3478 <filename>DEPLOY_DIR_TAR</filename> variable to make sure
3479 the
3480 <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
3481 task writes TAR packages into the appropriate folder.
3482 For more information on how packaging works, see the
3483 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3484 section in the Yocto Project Overview and Concepts Manual.
3485 </para>
3486 </glossdef>
3487 </glossentry>
3488
3489 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
3490 <info>
3491 DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files."
3492 </info>
3493 <glossdef>
3494 <para role="glossdeffirst">
3495 When inheriting the
3496 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
3497 class, the <filename>DEPLOYDIR</filename> points to a
3498 temporary work area for deployed files that is set in the
3499 <filename>deploy</filename> class as follows:
3500 <literallayout class='monospaced'>
3501 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
3502 </literallayout>
3503 </para>
3504
3505 <para>
3506 Recipes inheriting the <filename>deploy</filename> class
3507 should copy files to be deployed into
3508 <filename>DEPLOYDIR</filename>, and the class will take
3509 care of copying them into
3510 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3511 afterwards.
3512 </para>
3513 </glossdef>
3514 </glossentry>
3515
3516 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
3517 <info>
3518 DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable."
3519 </info>
3520 <glossdef>
3521 <para role="glossdeffirst">
3522 The package description used by package managers.
3523 If not set, <filename>DESCRIPTION</filename> takes
3524 the value of the
3525 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
3526 variable.
3527 </para>
3528 </glossdef>
3529 </glossentry>
3530
3531 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
3532 <info>
3533 DISTRO[doc] = "The short name of the distribution. If the variable is blank, meta/conf/distro/defaultsetup.conf will be used."
3534 </info>
3535 <glossdef>
3536 <para role="glossdeffirst">
3537 The short name of the distribution.
3538 For information on the long name of the distribution, see
3539 the
3540 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
3541 variable.
3542 </para>
3543
3544 <para>
3545 The <filename>DISTRO</filename> variable corresponds to a
3546 distribution configuration file whose root name is the
3547 same as the variable's argument and whose filename
3548 extension is <filename>.conf</filename>.
3549 For example, the distribution configuration file for the
3550 Poky distribution is named <filename>poky.conf</filename>
3551 and resides in the
3552 <filename>meta-poky/conf/distro</filename> directory of
3553 the
3554 <link linkend='source-directory'>Source Directory</link>.
3555 </para>
3556
3557 <para>
3558 Within that <filename>poky.conf</filename> file, the
3559 <filename>DISTRO</filename> variable is set as follows:
3560 <literallayout class='monospaced'>
3561 DISTRO = "poky"
3562 </literallayout>
3563 </para>
3564
3565 <para>
3566 Distribution configuration files are located in a
3567 <filename>conf/distro</filename> directory within the
3568 <link linkend='metadata'>Metadata</link>
3569 that contains the distribution configuration.
3570 The value for <filename>DISTRO</filename> must not contain
3571 spaces, and is typically all lower-case.
3572 <note>
3573 If the <filename>DISTRO</filename> variable is blank,
3574 a set of default configurations are used, which are
3575 specified within
3576 <filename>meta/conf/distro/defaultsetup.conf</filename>
3577 also in the Source Directory.
3578 </note>
3579 </para>
3580 </glossdef>
3581 </glossentry>
3582
3583 <glossentry id='var-DISTRO_CODENAME'><glossterm>DISTRO_CODENAME</glossterm>
3584 <info>
3585 DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built."
3586 </info>
3587 <glossdef>
3588 <para role="glossdeffirst">
3589 Specifies a codename for the distribution being built.
3590 </para>
3591 </glossdef>
3592 </glossentry>
3593
3594 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
3595 <info>
3596 DISTRO_EXTRA_RDEPENDS[doc] = "Specifies a list of distro-specific packages to add to all images. The variable only applies to the images that include packagegroup-base."
3597 </info>
3598 <glossdef>
3599 <para role="glossdeffirst">
3600 Specifies a list of distro-specific packages to add to all images.
3601 This variable takes affect through
3602 <filename>packagegroup-base</filename> so the
3603 variable only really applies to the more full-featured
3604 images that include <filename>packagegroup-base</filename>.
3605 You can use this variable to keep distro policy out of
3606 generic images.
3607 As with all other distro variables, you set this variable
3608 in the distro <filename>.conf</filename> file.
3609 </para>
3610 </glossdef>
3611 </glossentry>
3612
3613 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
3614 <info>
3615 DISTRO_EXTRA_RRECOMMENDS[doc] = "Specifies a list of distro-specific packages to add to all images if the packages exist. The list of packages are automatically installed but you can remove them."
3616 </info>
3617 <glossdef>
3618 <para role="glossdeffirst">
3619 Specifies a list of distro-specific packages to add to all images
3620 if the packages exist.
3621 The packages might not exist or be empty (e.g. kernel modules).
3622 The list of packages are automatically installed but you can
3623 remove them.
3624 </para>
3625 </glossdef>
3626 </glossentry>
3627
3628 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
3629 <info>
3630 DISTRO_FEATURES[doc] = "The features enabled for the distribution."
3631 </info>
3632 <glossdef>
3633 <para role="glossdeffirst">
3634 The software support you want in your distribution for
3635 various features.
3636 You define your distribution features in the distribution
3637 configuration file.
3638 </para>
3639
3640 <para>
3641 In most cases, the presence or absence of a feature in
3642 <filename>DISTRO_FEATURES</filename> is translated to the
3643 appropriate option supplied to the configure script
3644 during the
3645 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3646 task for recipes that optionally support the feature.
3647 For example, specifying "x11" in
3648 <filename>DISTRO_FEATURES</filename>, causes
3649 every piece of software built for the target that can
3650 optionally support X11 to have its X11 support enabled.
3651 </para>
3652
3653 <para>
3654 Two more examples are Bluetooth and NFS support.
3655 For a more complete list of features that ships with the
3656 Yocto Project and that you can provide with this variable,
3657 see the
3658 "<link linkend='ref-features-distro'>Distro Features</link>"
3659 section.
3660 </para>
3661 </glossdef>
3662 </glossentry>
3663
3664 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
3665 <info>
3666 DISTRO_FEATURES_BACKFILL[doc] = "Features to be added to DISTRO_FEATURES if not also present in DISTRO_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and it is not intended to be user-configurable."
3667 </info>
3668 <glossdef>
3669 <para role="glossdeffirst">
3670 Features to be added to
3671 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
3672 if not also present in
3673 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
3674 </para>
3675
3676 <para>
3677 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
3678 It is not intended to be user-configurable.
3679 It is best to just reference the variable to see which distro features are
3680 being backfilled for all distro configurations.
3681 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
3682 more information.
3683 </para>
3684 </glossdef>
3685 </glossentry>
3686
3687 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
3688 <info>
3689 DISTRO_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from DISTRO_FEATURES_BACKFILL that should not be backfilled (i.e. added to DISTRO_FEATURES) during the build."
3690 </info>
3691 <glossdef>
3692 <para role="glossdeffirst">
3693 Features from
3694 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
3695 that should not be backfilled (i.e. added to
3696 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
3697 during the build.
3698 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
3699 more information.
3700 </para>
3701 </glossdef>
3702 </glossentry>
3703
3704 <glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm>DISTRO_FEATURES_DEFAULT</glossterm>
3705 <info>
3706 DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features."
3707 </info>
3708 <glossdef>
3709 <para role="glossdeffirst">
3710 A convenience variable that gives you the default
3711 list of distro features with the exception of any
3712 features specific to the C library
3713 (<filename>libc</filename>).
3714 </para>
3715
3716 <para>
3717 When creating a custom distribution, you might find it
3718 useful to be able to reuse the default
3719 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3720 options without the need to write out the full set.
3721 Here is an example that uses
3722 <filename>DISTRO_FEATURES_DEFAULT</filename> from a
3723 custom distro configuration file:
3724 <literallayout class='monospaced'>
3725 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
3726 </literallayout>
3727 </para>
3728 </glossdef>
3729 </glossentry>
3730
3731 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm>
3732 <info>
3733 DISTRO_FEATURES_FILTER_NATIVE[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building native recipes."
3734 </info>
3735 <glossdef>
3736 <para role="glossdeffirst">
3737 Specifies a list of features that if present in
3738 the target
3739 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3740 value should be included in
3741 <filename>DISTRO_FEATURES</filename> when building native
3742 recipes.
3743 This variable is used in addition to the features
3744 filtered using the
3745 <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
3746 variable.
3747 </para>
3748 </glossdef>
3749 </glossentry>
3750
3751 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm>
3752 <info>
3753 DISTRO_FEATURES_FILTER_NATIVESDK[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building nativesdk recipes."
3754 </info>
3755 <glossdef>
3756 <para role="glossdeffirst">
3757 Specifies a list of features that if present in the target
3758 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3759 value should be included in
3760 <filename>DISTRO_FEATURES</filename> when building
3761 nativesdk recipes.
3762 This variable is used in addition to the features
3763 filtered using the
3764 <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
3765 variable.
3766 </para>
3767 </glossdef>
3768 </glossentry>
3769
3770<!--
3771 <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm>
3772 <info>
3773 DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)."
3774 </info>
3775 <glossdef>
3776 <para role="glossdeffirst">
3777 A convenience variable that specifies the list of distro
3778 features that are specific to the C library
3779 (<filename>libc</filename>).
3780 Typically, these features are prefixed with "libc-" and
3781 control which features are enabled at during the build
3782 within the C library itself.
3783 </para>
3784 </glossdef>
3785 </glossentry>
3786-->
3787
3788 <glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm>
3789 <info>
3790 DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes."
3791 </info>
3792 <glossdef>
3793 <para role="glossdeffirst">
3794 Specifies a list of features that should be included in
3795 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3796 when building native recipes.
3797 This variable is used in addition to the features
3798 filtered using the
3799 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>
3800 variable.
3801 </para>
3802 </glossdef>
3803 </glossentry>
3804
3805 <glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm>
3806 <info>
3807 DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes."
3808 </info>
3809 <glossdef>
3810 <para role="glossdeffirst">
3811 Specifies a list of features that should be included in
3812 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3813 when building nativesdk recipes.
3814 This variable is used in addition to the features
3815 filtered using the
3816 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>
3817 variable.
3818 </para>
3819 </glossdef>
3820 </glossentry>
3821
3822 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
3823 <info>
3824 DISTRO_NAME[doc] = "The long name of the distribution."
3825 </info>
3826 <glossdef>
3827 <para role="glossdeffirst">
3828 The long name of the distribution.
3829 For information on the short name of the distribution, see
3830 the
3831 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
3832 variable.
3833 </para>
3834
3835 <para>
3836 The <filename>DISTRO_NAME</filename> variable corresponds
3837 to a distribution configuration file whose root name is the
3838 same as the variable's argument and whose filename
3839 extension is <filename>.conf</filename>.
3840 For example, the distribution configuration file for the
3841 Poky distribution is named <filename>poky.conf</filename>
3842 and resides in the
3843 <filename>meta-poky/conf/distro</filename> directory of
3844 the
3845 <link linkend='source-directory'>Source Directory</link>.
3846 </para>
3847
3848 <para>
3849 Within that <filename>poky.conf</filename> file, the
3850 <filename>DISTRO_NAME</filename> variable is set as
3851 follows:
3852 <literallayout class='monospaced'>
3853 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
3854 </literallayout>
3855 </para>
3856
3857 <para>
3858 Distribution configuration files are located in a
3859 <filename>conf/distro</filename> directory within the
3860 <link linkend='metadata'>Metadata</link>
3861 that contains the distribution configuration.
3862 <note>
3863 If the <filename>DISTRO_NAME</filename> variable is
3864 blank, a set of default configurations are used, which
3865 are specified within
3866 <filename>meta/conf/distro/defaultsetup.conf</filename>
3867 also in the Source Directory.
3868 </note>
3869 </para>
3870 </glossdef>
3871 </glossentry>
3872
3873 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
3874 <info>
3875 DISTRO_VERSION[doc] = "The version of the distribution."
3876 </info>
3877 <glossdef>
3878 <para role="glossdeffirst">
3879 The version of the distribution.
3880 </para>
3881 </glossdef>
3882 </glossentry>
3883
3884 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
3885 <info>
3886 DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution."
3887 </info>
3888 <glossdef>
3889 <para role="glossdeffirst">
3890 A colon-separated list of overrides specific to the
3891 current distribution.
3892 By default, this list includes the value of
3893 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>.
3894 </para>
3895
3896 <para>
3897 You can extend <filename>DISTROOVERRIDES</filename>
3898 to add extra overrides that should apply to
3899 the distribution.
3900 </para>
3901
3902 <para>
3903 The underlying mechanism behind
3904 <filename>DISTROOVERRIDES</filename> is simply that it
3905 is included in the default value of
3906 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
3907 </para>
3908 </glossdef>
3909 </glossentry>
3910
3911 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
3912 <info>
3913 DL_DIR[doc] = "The central download directory used by the build process to store downloads. By default, the directory is 'downloads' in the Build Directory."
3914 </info>
3915 <glossdef>
3916 <para role="glossdeffirst">
3917 The central download directory used by the build process to
3918 store downloads.
3919 By default, <filename>DL_DIR</filename> gets files
3920 suitable for mirroring for everything except Git
3921 repositories.
3922 If you want tarballs of Git repositories, use the
3923 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
3924 variable.
3925 </para>
3926
3927 <para>
3928 You can set this directory by defining the
3929 <filename>DL_DIR</filename> variable in the
3930 <filename>conf/local.conf</filename> file.
3931 This directory is self-maintaining and you should not have
3932 to touch it.
3933 By default, the directory is <filename>downloads</filename>
3934 in the
3935 <link linkend='build-directory'>Build Directory</link>.
3936 <literallayout class='monospaced'>
3937 #DL_DIR ?= "${TOPDIR}/downloads"
3938 </literallayout>
3939 To specify a different download directory, simply remove
3940 the comment from the line and provide your directory.
3941 </para>
3942
3943 <para>
3944 During a first build, the system downloads many different
3945 source code tarballs from various upstream projects.
3946 Downloading can take a while, particularly if your network
3947 connection is slow.
3948 Tarballs are all stored in the directory defined by
3949 <filename>DL_DIR</filename> and the build system looks there
3950 first to find source tarballs.
3951 <note>
3952 When wiping and rebuilding, you can preserve this
3953 directory to speed up this part of subsequent
3954 builds.
3955 </note>
3956 </para>
3957
3958 <para>
3959 You can safely share this directory between multiple builds
3960 on the same development machine.
3961 For additional information on how the build process gets
3962 source files when working behind a firewall or proxy server,
3963 see this specific question in the
3964 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
3965 chapter.
3966 You can also refer to the
3967 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
3968 Wiki page.
3969 </para>
3970 </glossdef>
3971 </glossentry>
3972
3973 <glossentry id='var-DOC_COMPRESS'><glossterm>DOC_COMPRESS</glossterm>
3974 <info>
3975 DOC_COMPRESS[doc] = "When inheriting the compress_doc class, this variable sets the compression policy used when the OpenEmbedded build system compresses man pages and info pages."
3976 </info>
3977 <glossdef>
3978 <para role="glossdeffirst">
3979 When inheriting the
3980 <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link>
3981 class, this variable sets the compression policy used when
3982 the OpenEmbedded build system compresses man pages and info
3983 pages.
3984 By default, the compression method used is gz (gzip).
3985 Other policies available are xz and bz2.
3986 </para>
3987
3988 <para>
3989 For information on policies and on how to use this
3990 variable, see the comments in the
3991 <filename>meta/classes/compress_doc.bbclass</filename> file.
3992 </para>
3993 </glossdef>
3994 </glossentry>
3995
3996 </glossdiv>
3997
3998 <glossdiv id='var-glossary-e'><title>E</title>
3999
4000 <glossentry id='var-EFI_PROVIDER'><glossterm>EFI_PROVIDER</glossterm>
4001 <info>
4002 EFI_PROVIDER[doc] = "When building bootable images (i.e. where hddimg, iso, or wic.vmdk is in IMAGE_FSTYPES), the EFI_PROVIDER variable specifies the EFI bootloader to use."
4003 </info>
4004 <glossdef>
4005 <para role="glossdeffirst">
4006 When building bootable images (i.e. where
4007 <filename>hddimg</filename>, <filename>iso</filename>,
4008 or <filename>wic.vmdk</filename> is in
4009 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>),
4010 the <filename>EFI_PROVIDER</filename> variable specifies
4011 the EFI bootloader to use.
4012 The default is "grub-efi", but "systemd-boot" can be used
4013 instead.
4014 </para>
4015
4016 <para>
4017 See the
4018 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
4019 and
4020 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
4021 classes for more information.
4022 </para>
4023 </glossdef>
4024 </glossentry>
4025
4026 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
4027 <info>
4028 ENABLE_BINARY_LOCALE_GENERATION[doc] = "Controls which locales for glibc are generated during the build. The variable is useful if the target device has 64Mbytes of RAM or less."
4029 </info>
4030 <glossdef>
4031 <para role="glossdeffirst">
4032 Variable that controls which locales for
4033 <filename>glibc</filename> are generated during the
4034 build (useful if the target device has 64Mbytes
4035 of RAM or less).
4036 </para>
4037 </glossdef>
4038 </glossentry>
4039
4040 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
4041 <info>
4042 ERR_REPORT_DIR[doc] = "When used with the report-error class, specifies the path used for storing the debug files created by the error reporting tool, which allows you to submit build errors you encounter to a central database."
4043 </info>
4044 <glossdef>
4045 <para role="glossdeffirst">
4046 When used with the
4047 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
4048 class, specifies the path used for storing the debug files
4049 created by the
4050 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
4051 which allows you to submit build errors you encounter to a
4052 central database.
4053 By default, the value of this variable is
4054 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
4055 </para>
4056
4057 <para>
4058 You can set <filename>ERR_REPORT_DIR</filename> to the path
4059 you want the error reporting tool to store the debug files
4060 as follows in your <filename>local.conf</filename> file:
4061 <literallayout class='monospaced'>
4062 ERR_REPORT_DIR = "<replaceable>path</replaceable>"
4063 </literallayout>
4064 </para>
4065 </glossdef>
4066 </glossentry>
4067
4068 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
4069 <info>
4070 ERROR_QA[doc] = "Specifies the quality assurance checks whose failures are reported as errors by the OpenEmbedded build system."
4071 </info>
4072 <glossdef>
4073 <para role="glossdeffirst">
4074 Specifies the quality assurance checks whose failures are
4075 reported as errors by the OpenEmbedded build system.
4076 You set this variable in your distribution configuration
4077 file.
4078 For a list of the checks you can control with this variable,
4079 see the
4080 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
4081 section.
4082 </para>
4083 </glossdef>
4084 </glossentry>
4085
4086 <glossentry id='var-EXCLUDE_FROM_SHLIBS'><glossterm>EXCLUDE_FROM_SHLIBS</glossterm>
4087 <info>
4088 EXCLUDE_FROM_SHLIBS[doc] = "Causes the OpenEmbedded build system's shared libraries resolver to exclude an entire package when scanning for shared libraries."
4089 </info>
4090 <glossdef>
4091 <para role="glossdeffirst">
4092 Triggers the OpenEmbedded build system's shared libraries
4093 resolver to exclude an entire package when scanning for
4094 shared libraries.
4095 <note>
4096 The shared libraries resolver's functionality results
4097 in part from the internal function
4098 <filename>package_do_shlibs</filename>, which is part of
4099 the
4100 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
4101 task.
4102 You should be aware that the shared libraries resolver
4103 might implicitly define some dependencies between
4104 packages.
4105 </note>
4106 The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is
4107 similar to the
4108 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
4109 variable, which excludes a package's particular libraries
4110 only and not the whole package.
4111 </para>
4112
4113 <para>
4114 Use the
4115 <filename>EXCLUDE_FROM_SHLIBS</filename> variable by
4116 setting it to "1" for a particular package:
4117 <literallayout class='monospaced'>
4118 EXCLUDE_FROM_SHLIBS = "1"
4119 </literallayout>
4120 </para>
4121 </glossdef>
4122 </glossentry>
4123
4124 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
4125 <info>
4126 EXCLUDE_FROM_WORLD[doc] = "Directs BitBake to exclude a recipe from world builds (i.e. bitbake world)."
4127 </info>
4128 <glossdef>
4129 <para role="glossdeffirst">
4130 Directs BitBake to exclude a recipe from world builds (i.e.
4131 <filename>bitbake world</filename>).
4132 During world builds, BitBake locates, parses and builds all
4133 recipes found in every layer exposed in the
4134 <filename>bblayers.conf</filename> configuration file.
4135 </para>
4136
4137 <para>
4138 To exclude a recipe from a world build using this variable,
4139 set the variable to "1" in the recipe.
4140 </para>
4141
4142 <note>
4143 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
4144 may still be built during a world build in order to satisfy
4145 dependencies of other recipes.
4146 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
4147 only ensures that the recipe is not explicitly added
4148 to the list of build targets in a world build.
4149 </note>
4150 </glossdef>
4151 </glossentry>
4152
4153 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
4154 <info>
4155 EXTENDPE[doc] = "Used with file and pathnames to create a prefix for a recipe's version based on the recipe's PE value. If PE is set and greater than zero for a recipe, EXTENDPE becomes that value."
4156 </info>
4157 <glossdef>
4158 <para role="glossdeffirst">
4159 Used with file and pathnames to create a prefix for a recipe's
4160 version based on the recipe's
4161 <link linkend='var-PE'><filename>PE</filename></link> value.
4162 If <filename>PE</filename> is set and greater than zero for a recipe,
4163 <filename>EXTENDPE</filename> becomes that value (e.g if
4164 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
4165 becomes "1_").
4166 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
4167 zero, <filename>EXTENDPE</filename> becomes "".</para>
4168 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
4169 variable for an example.
4170 </para>
4171 </glossdef>
4172 </glossentry>
4173
4174 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
4175 <info>
4176 EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe."
4177 </info>
4178 <glossdef>
4179 <para role="glossdeffirst">
4180 The full package version specification as it appears on the
4181 final packages produced by a recipe.
4182 The variable's value is normally used to fix a runtime
4183 dependency to the exact same version of another package
4184 in the same recipe:
4185 <literallayout class='monospaced'>
4186 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
4187 </literallayout>
4188 </para>
4189
4190 <para>
4191 The dependency relationships are intended to force the
4192 package manager to upgrade these types of packages in
4193 lock-step.
4194 </para>
4195 </glossdef>
4196 </glossentry>
4197
4198 <glossentry id='var-EXTERNAL_KERNEL_TOOLS'><glossterm>EXTERNAL_KERNEL_TOOLS</glossterm>
4199 <info>
4200 EXTERNAL_KERNEL_TOOLS[doc] = "Indicates kernel tools are external to the source tree."
4201 </info>
4202 <glossdef>
4203 <para role="glossdeffirst">
4204 When set, the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4205 variable indicates that these tools are not in the
4206 source tree.
4207 </para>
4208
4209 <para>
4210 When kernel tools are available in the tree, they are
4211 preferred over any externally installed tools.
4212 Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4213 variable tells the OpenEmbedded build system to prefer
4214 the installed external tools.
4215 See the
4216 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
4217 class in <filename>meta/classes</filename> to see how
4218 the variable is used.
4219 </para>
4220 </glossdef>
4221 </glossentry>
4222
4223 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
4224 <info>
4225 EXTERNALSRC[doc] = "If externalsrc.bbclass is inherited, this variable points to the source tree, which is outside of the OpenEmbedded build system."
4226 </info>
4227 <glossdef>
4228 <para role="glossdeffirst">
4229 When inheriting the
4230 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4231 class, this variable points to the source tree, which is
4232 outside of the OpenEmbedded build system.
4233 When set, this variable sets the
4234 <link linkend='var-S'><filename>S</filename></link>
4235 variable, which is what the OpenEmbedded build system uses
4236 to locate unpacked recipe source code.
4237 </para>
4238
4239 <para>
4240 For more information on
4241 <filename>externalsrc.bbclass</filename>, see the
4242 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4243 section.
4244 You can also find information on how to use this variable
4245 in the
4246 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
4247 section in the Yocto Project Development Tasks Manual.
4248 </para>
4249 </glossdef>
4250 </glossentry>
4251
4252 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
4253 <info>
4254 EXTERNALSRC_BUILD[doc] = "If externalsrc.bbclass is inherited, this variable points to the directory in which the recipe's source code is built, which is outside of the OpenEmbedded build system."
4255 </info>
4256 <glossdef>
4257 <para role="glossdeffirst">
4258 When inheriting the
4259 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4260 class, this variable points to the directory in which the
4261 recipe's source code is built, which is outside of the
4262 OpenEmbedded build system.
4263 When set, this variable sets the
4264 <link linkend='var-B'><filename>B</filename></link>
4265 variable, which is what the OpenEmbedded build system uses
4266 to locate the Build Directory.
4267 </para>
4268
4269 <para>
4270 For more information on
4271 <filename>externalsrc.bbclass</filename>, see the
4272 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4273 section.
4274 You can also find information on how to use this variable
4275 in the
4276 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
4277 section in the Yocto Project Development Tasks Manual.
4278 </para>
4279 </glossdef>
4280 </glossentry>
4281
4282 <glossentry id='var-EXTRA_AUTORECONF'><glossterm>EXTRA_AUTORECONF</glossterm>
4283 <info>
4284 EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure."
4285 </info>
4286 <glossdef>
4287 <para role="glossdeffirst">
4288 For recipes inheriting the
4289 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
4290 class, you can use <filename>EXTRA_AUTORECONF</filename> to
4291 specify extra options to pass to the
4292 <filename>autoreconf</filename> command that is
4293 executed during the
4294 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
4295 task.
4296 </para>
4297
4298 <para>
4299 The default value is "--exclude=autopoint".
4300 </para>
4301 </glossdef>
4302 </glossentry>
4303
4304 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
4305 <info>
4306 EXTRA_IMAGE_FEATURES[doc] = "The list of additional features to include in an image. Configure this variable in the conf/local.conf file in the Build Directory."
4307 </info>
4308 <glossdef>
4309 <para role="glossdeffirst">
4310 A list of additional features to include in an image.
4311 When listing more than one feature, separate them with
4312 a space.
4313 </para>
4314
4315 <para>
4316 Typically, you configure this variable in your
4317 <filename>local.conf</filename> file, which is found in the
4318 <link linkend='build-directory'>Build Directory</link>.
4319 Although you can use this variable from within a recipe,
4320 best practices dictate that you do not.
4321 <note>
4322 To enable primary features from within the image
4323 recipe, use the
4324 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
4325 variable.
4326 </note>
4327 </para>
4328
4329 <para>
4330 Here are some examples of features you can add:
4331 <literallayout class='monospaced'>
4332"dbg-pkgs" - Adds -dbg packages for all installed packages
4333 including symbol information for debugging and
4334 profiling.
4335
4336"debug-tweaks" - Makes an image suitable for debugging.
4337 For example, allows root logins without
4338 passwords and enables post-installation
4339 logging. See the 'allow-empty-password'
4340 and 'post-install-logging' features in
4341 the "<link linkend='ref-features-image'>Image Features</link>" section for
4342 more information.
4343
4344"dev-pkgs" - Adds -dev packages for all installed packages.
4345 This is useful if you want to develop against
4346 the libraries in the image.
4347
4348"read-only-rootfs" - Creates an image whose root
4349 filesystem is read-only. See the
4350 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
4351 section in the Yocto Project
4352 Development Tasks Manual for
4353 more information
4354
4355"tools-debug" - Adds debugging tools such as gdb and
4356 strace.
4357
4358"tools-sdk" - Adds development tools such as gcc, make,
4359 pkgconfig and so forth.
4360
4361"tools-testapps" - Adds useful testing tools such as
4362 ts_print, aplay, arecord and so
4363 forth.
4364
4365 </literallayout>
4366 </para>
4367
4368 <para>
4369 For a complete list of image features that ships with the
4370 Yocto Project, see the
4371 "<link linkend="ref-features-image">Image Features</link>"
4372 section.
4373 </para>
4374
4375 <para>
4376 For an example that shows how to customize your image by
4377 using this variable, see the
4378 "<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>"
4379 section in the Yocto Project Development Tasks Manual.
4380 </para>
4381 </glossdef>
4382 </glossentry>
4383
4384 <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
4385 <info>
4386 EXTRA_IMAGECMD[doc] = "Specifies additional options for the image creation command that has been specified in IMAGE_CMD. When setting this variable, you should use an override for the associated image type."
4387 </info>
4388 <glossdef>
4389 <para role="glossdeffirst">
4390 Specifies additional options for the image
4391 creation command that has been specified in
4392 <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
4393 When setting this variable, use an override for the
4394 associated image type.
4395 Here is an example:
4396 <literallayout class='monospaced'>
4397 EXTRA_IMAGECMD_ext3 ?= "-i 4096"
4398 </literallayout>
4399 </para>
4400 </glossdef>
4401 </glossentry>
4402
4403 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
4404 <info>
4405 EXTRA_IMAGEDEPENDS[doc] = "A list of recipes to build that do not provide packages for installing into the root filesystem. Use this variable to list recipes that are required to build the final image, but not needed in the root filesystem."
4406 </info>
4407 <glossdef>
4408 <para role="glossdeffirst">
4409 A list of recipes to build that do not provide packages
4410 for installing into the root filesystem.
4411 </para>
4412
4413 <para>
4414 Sometimes a recipe is required to build the final image but is not
4415 needed in the root filesystem.
4416 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
4417 list these recipes and thus specify the dependencies.
4418 A typical example is a required bootloader in a machine configuration.
4419 </para>
4420
4421 <note>
4422 To add packages to the root filesystem, see the various
4423 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
4424 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
4425 variables.
4426 </note>
4427 </glossdef>
4428 </glossentry>
4429
4430 <glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm>
4431 <info>
4432 EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH."
4433 </info>
4434 <glossdef>
4435 <para role="glossdeffirst">
4436 A list of subdirectories of
4437 <filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename>
4438 added to the beginning of the environment variable
4439 <filename>PATH</filename>.
4440 As an example, the following prepends
4441 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:"
4442 to <filename>PATH</filename>:
4443 <literallayout class='monospaced'>
4444 EXTRANATIVEPATH = "foo bar"
4445 </literallayout>
4446 </para>
4447 </glossdef>
4448 </glossentry>
4449
4450 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
4451 <info>
4452 EXTRA_OECMAKE[doc] = "Additional cmake options."
4453 </info>
4454 <glossdef>
4455 <para role="glossdeffirst">
4456 Additional
4457 <ulink url='https://cmake.org/overview/'>CMake</ulink>
4458 options.
4459 See the
4460 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
4461 class for additional information.
4462 </para>
4463 </glossdef>
4464 </glossentry>
4465
4466 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
4467 <info>
4468 EXTRA_OECONF[doc] = "Additional configure script options."
4469 </info>
4470 <glossdef>
4471 <para role="glossdeffirst">
4472 Additional <filename>configure</filename> script options.
4473 See
4474 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
4475 for additional information on passing configure script
4476 options.
4477 </para>
4478 </glossdef>
4479 </glossentry>
4480
4481 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
4482 <info>
4483 EXTRA_OEMAKE[doc] = "Additional GNU make options."
4484 </info>
4485 <glossdef>
4486 <para role="glossdeffirst">
4487 Additional GNU <filename>make</filename> options.
4488 </para>
4489
4490 <para>
4491 Because the <filename>EXTRA_OEMAKE</filename> defaults to
4492 "", you need to set the variable to specify any required
4493 GNU options.
4494 </para>
4495
4496 <para>
4497 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
4498 and
4499 <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></link>
4500 also make use of
4501 <filename>EXTRA_OEMAKE</filename> to pass the required
4502 flags.
4503 </para>
4504 </glossdef>
4505 </glossentry>
4506
4507 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
4508 <info>
4509 EXTRA_OESCONS[doc] = "When a recipe inherits the scons class, this variable specifies additional configuration options you want to pass to the scons command line."
4510 </info>
4511 <glossdef>
4512 <para role="glossdeffirst">
4513 When inheriting the
4514 <link linkend='ref-classes-scons'><filename>scons</filename></link>
4515 class, this variable specifies additional configuration
4516 options you want to pass to the
4517 <filename>scons</filename> command line.
4518 </para>
4519 </glossdef>
4520 </glossentry>
4521
4522 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
4523 <info>
4524 EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations."
4525 </info>
4526 <glossdef>
4527 <para role="glossdeffirst">
4528 When inheriting the
4529 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
4530 class, this variable provides image level user and group
4531 operations.
4532 This is a more global method of providing user and group
4533 configuration as compared to using the
4534 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
4535 class, which ties user and group configurations to a
4536 specific recipe.
4537 </para>
4538
4539 <para>
4540 The set list of commands you can configure using the
4541 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
4542 <filename>extrausers</filename> class.
4543 These commands map to the normal Unix commands of the same
4544 names:
4545 <literallayout class='monospaced'>
4546 # EXTRA_USERS_PARAMS = "\
4547 # useradd -p '' tester; \
4548 # groupadd developers; \
4549 # userdel nobody; \
4550 # groupdel -g video; \
4551 # groupmod -g 1020 developers; \
4552 # usermod -s /bin/sh tester; \
4553 # "
4554 </literallayout>
4555 </para>
4556 </glossdef>
4557 </glossentry>
4558
4559 </glossdiv>
4560
4561 <glossdiv id='var-glossary-f'><title>F</title>
4562
4563 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
4564 <info>
4565 FEATURE_PACKAGES[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES. When setting the value, FEATURE_PACKAGES should have the name of the feature item as an override."
4566 </info>
4567 <glossdef>
4568 <para role="glossdeffirst">
4569 Defines one or more packages to include in an image when
4570 a specific item is included in
4571 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
4572 When setting the value, <filename>FEATURE_PACKAGES</filename>
4573 should have the name of the feature item as an override.
4574 Here is an example:
4575 <literallayout class='monospaced'>
4576 FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>"
4577 </literallayout>
4578 </para>
4579
4580 <para>
4581 In this example, if "widget" were added to
4582 <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and
4583 <replaceable>package2</replaceable> would be included in the image.
4584 <note>
4585 Packages installed by features defined through
4586 <filename>FEATURE_PACKAGES</filename> are often package
4587 groups.
4588 While similarly named, you should not confuse the
4589 <filename>FEATURE_PACKAGES</filename> variable with
4590 package groups, which are discussed elsewhere in the
4591 documentation.
4592 </note>
4593 </para>
4594 </glossdef>
4595 </glossentry>
4596
4597 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
4598 <info>
4599 FEED_DEPLOYDIR_BASE_URI[doc] = "Allow to serve ipk deploy directory as an ad hoc feed (bogofeed). Set to base URL of the directory as exported by HTTP. Set of ad hoc feed configs will be generated in the image."
4600 </info>
4601 <glossdef>
4602 <para role="glossdeffirst">
4603 Points to the base URL of the server and location within
4604 the document-root that provides the metadata and
4605 packages required by OPKG to support runtime package
4606 management of IPK packages.
4607 You set this variable in your
4608 <filename>local.conf</filename> file.
4609 </para>
4610
4611 <para>
4612 Consider the following example:
4613 <literallayout class='monospaced'>
4614 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
4615 </literallayout>
4616 This example assumes you are serving your packages over
4617 HTTP and your databases are located in a directory
4618 named <filename>BOARD-dir</filename>, which is underneath
4619 your HTTP server's document-root.
4620 In this case, the OpenEmbedded build system generates a set
4621 of configuration files for you in your target that work
4622 with the feed.
4623 </para>
4624 </glossdef>
4625 </glossentry>
4626
4627 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
4628 <info>
4629 FILES[doc] = "The list of directories or files that are placed in a package."
4630 </info>
4631 <glossdef>
4632 <para role="glossdeffirst">
4633 The list of files and directories that are placed in a
4634 package.
4635 The
4636 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
4637 variable lists the packages generated by a recipe.
4638 </para>
4639
4640 <para>
4641 To use the <filename>FILES</filename> variable, provide a
4642 package name override that identifies the resulting package.
4643 Then, provide a space-separated list of files or paths
4644 that identify the files you want included as part of the
4645 resulting package.
4646 Here is an example:
4647 <literallayout class='monospaced'>
4648 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
4649 </literallayout>
4650 <note><title>Notes</title>
4651 <itemizedlist>
4652 <listitem><para>
4653 When specifying files or paths, you can pattern
4654 match using Python's
4655 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
4656 syntax.
4657 For details on the syntax, see the
4658 documentation by following the previous link.
4659 </para></listitem>
4660 <listitem><para>
4661 When specifying paths as part of the
4662 <filename>FILES</filename> variable, it is
4663 good practice to use appropriate path
4664 variables.
4665 For example, use <filename>${sysconfdir}</filename>
4666 rather than <filename>/etc</filename>, or
4667 <filename>${bindir}</filename> rather than
4668 <filename>/usr/bin</filename>.
4669 You can find a list of these variables at the
4670 top of the
4671 <filename>meta/conf/bitbake.conf</filename>
4672 file in the
4673 <link linkend='source-directory'>Source Directory</link>.
4674 You will also find the default values of the
4675 various <filename>FILES_*</filename> variables
4676 in this file.
4677 </para></listitem>
4678 </itemizedlist>
4679 </note>
4680 </para>
4681
4682 <para>
4683 If some of the files you provide with the
4684 <filename>FILES</filename> variable are editable and you
4685 know they should not be overwritten during the package
4686 update process by the Package Management System (PMS), you
4687 can identify these files so that the PMS will not
4688 overwrite them.
4689 See the
4690 <link linkend='var-CONFFILES'><filename>CONFFILES</filename></link>
4691 variable for information on how to identify these files to
4692 the PMS.
4693 </para>
4694 </glossdef>
4695 </glossentry>
4696
4697 <glossentry id='var-FILES_SOLIBSDEV'><glossterm>FILES_SOLIBSDEV</glossterm>
4698 <info>
4699 FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."
4700 </info>
4701 <glossdef>
4702 <para role="glossdeffirst">
4703 Defines the file specification to match
4704 <link linkend='var-SOLIBSDEV'><filename>SOLIBSDEV</filename></link>.
4705 In other words, <filename>FILES_SOLIBSDEV</filename>
4706 defines the full path name of the development symbolic link
4707 (symlink) for shared libraries on the target platform.
4708 </para>
4709
4710 <para>
4711 The following statement from the
4712 <filename>bitbake.conf</filename> shows how it is set:
4713 <literallayout class='monospaced'>
4714 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
4715 </literallayout>
4716 </para>
4717 </glossdef>
4718 </glossentry>
4719
4720 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
4721 <info>
4722 FILESEXTRAPATHS[doc] = "Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files."
4723 </info>
4724 <glossdef>
4725 <para role="glossdeffirst">
4726 Extends the search path the OpenEmbedded build system uses
4727 when looking for files and patches as it processes recipes
4728 and append files.
4729 The default directories BitBake uses when it processes
4730 recipes are initially defined by the
4731 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4732 variable.
4733 You can extend <filename>FILESPATH</filename> variable
4734 by using <filename>FILESEXTRAPATHS</filename>.
4735 </para>
4736
4737 <para>
4738 Best practices dictate that you accomplish this by using
4739 <filename>FILESEXTRAPATHS</filename> from within a
4740 <filename>.bbappend</filename> file and that you prepend
4741 paths as follows:
4742 <literallayout class='monospaced'>
4743 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
4744 </literallayout>
4745 In the above example, the build system first looks for files
4746 in a directory that has the same name as the corresponding
4747 append file.
4748 <note>
4749 <para>When extending
4750 <filename>FILESEXTRAPATHS</filename>,
4751 be sure to use the immediate expansion
4752 (<filename>:=</filename>) operator.
4753 Immediate expansion makes sure that BitBake evaluates
4754 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
4755 at the time the directive is encountered rather than at
4756 some later time when expansion might result in a
4757 directory that does not contain the files you need.
4758 </para>
4759
4760 <para>Also, include the trailing separating colon
4761 character if you are prepending.
4762 The trailing colon character is necessary because you
4763 are directing BitBake to extend the path by prepending
4764 directories to the search path.</para>
4765 </note>
4766 Here is another common use:
4767 <literallayout class='monospaced'>
4768 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
4769 </literallayout>
4770 In this example, the build system extends the
4771 <filename>FILESPATH</filename> variable to include a
4772 directory named <filename>files</filename> that is in the
4773 same directory as the corresponding append file.
4774 </para>
4775
4776 <para>
4777 This next example specifically adds three paths:
4778 <literallayout class='monospaced'>
4779 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
4780 </literallayout>
4781 </para>
4782
4783 <para>
4784 A final example shows how you can extend the search path
4785 and include a
4786 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>-specific
4787 override, which is useful in a BSP layer:
4788 <literallayout class='monospaced'>
4789 FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"
4790 </literallayout>
4791 The previous statement appears in the
4792 <filename>linux-yocto-dev.bbappend</filename> file, which
4793 is found in the Yocto Project
4794 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
4795 in
4796 <filename>meta-intel/common/recipes-kernel/linux</filename>.
4797 Here, the machine override is a special
4798 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
4799 definition for multiple <filename>meta-intel</filename>
4800 machines.
4801 <note>
4802 For a layer that supports a single BSP, the override
4803 could just be the value of <filename>MACHINE</filename>.
4804 </note>
4805 </para>
4806
4807 <para>
4808 By prepending paths in <filename>.bbappend</filename>
4809 files, you allow multiple append files that reside in
4810 different layers but are used for the same recipe to
4811 correctly extend the path.
4812 </para>
4813 </glossdef>
4814 </glossentry>
4815
4816 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
4817 <info>
4818 FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."
4819 </info>
4820 <glossdef>
4821 <para role="glossdeffirst">
4822 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
4823 used by the OpenEmbedded build system for creating
4824 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
4825 The <filename>FILESOVERRIDES</filename> variable uses
4826 overrides to automatically extend the
4827 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4828 variable.
4829 For an example of how that works, see the
4830 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4831 variable description.
4832 Additionally, you find more information on how overrides
4833 are handled in the
4834 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
4835 section of the BitBake User Manual.
4836 </para>
4837
4838 <para>
4839 By default, the <filename>FILESOVERRIDES</filename>
4840 variable is defined as:
4841 <literallayout class='monospaced'>
4842 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
4843 </literallayout>
4844
4845 <note>
4846 Do not hand-edit the <filename>FILESOVERRIDES</filename>
4847 variable.
4848 The values match up with expected overrides and are
4849 used in an expected manner by the build system.
4850 </note>
4851 </para>
4852 </glossdef>
4853 </glossentry>
4854
4855 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
4856 <info>
4857 FILESPATH[doc] = "The default set of directories the OpenEmbedded build system uses when searching for patches and files. It is defined in the base.bbclass class found in meta/classes in the Source Directory. Do not hand-edit the FILESPATH variable."
4858 </info>
4859 <glossdef>
4860 <para role="glossdeffirst">
4861 The default set of directories the OpenEmbedded build
4862 system uses when searching for patches and files.
4863 </para>
4864
4865 <para>
4866 During the build process, BitBake searches each directory
4867 in <filename>FILESPATH</filename> in the specified order
4868 when looking for files and patches specified by each
4869 <filename>file://</filename> URI in a recipe's
4870 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
4871 statements.
4872 </para>
4873
4874 <para>
4875 The default value for the <filename>FILESPATH</filename>
4876 variable is defined in the <filename>base.bbclass</filename>
4877 class found in <filename>meta/classes</filename> in the
4878 <link linkend='source-directory'>Source Directory</link>:
4879 <literallayout class='monospaced'>
4880 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
4881 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
4882 </literallayout>
4883 The <filename>FILESPATH</filename> variable is automatically
4884 extended using the overrides from the
4885 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
4886 variable.
4887 <note><title>Notes</title>
4888 <itemizedlist>
4889 <listitem><para>
4890 Do not hand-edit the
4891 <filename>FILESPATH</filename> variable.
4892 If you want the build system to look in
4893 directories other than the defaults, extend the
4894 <filename>FILESPATH</filename> variable by
4895 using the
4896 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
4897 variable.
4898 </para></listitem>
4899 <listitem><para>
4900 Be aware that the default
4901 <filename>FILESPATH</filename> directories do
4902 not map to directories in custom layers
4903 where append files
4904 (<filename>.bbappend</filename>) are used.
4905 If you want the build system to find patches
4906 or files that reside with your append files,
4907 you need to extend the
4908 <filename>FILESPATH</filename> variable by
4909 using the <filename>FILESEXTRAPATHS</filename>
4910 variable.
4911 </para></listitem>
4912 </itemizedlist>
4913 </note>
4914 </para>
4915
4916 <para>
4917 You can take advantage of this searching behavior in
4918 useful ways.
4919 For example, consider a case where the following
4920 directory structure exists for general and machine-specific
4921 configurations:
4922 <literallayout class='monospaced'>
4923 files/defconfig
4924 files/MACHINEA/defconfig
4925 files/MACHINEB/defconfig
4926 </literallayout>
4927 Also in the example, the <filename>SRC_URI</filename>
4928 statement contains "file://defconfig".
4929 Given this scenario, you can set
4930 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
4931 to "MACHINEA" and cause the build system to use files
4932 from <filename>files/MACHINEA</filename>.
4933 Set <filename>MACHINE</filename> to "MACHINEB" and the
4934 build system uses files from
4935 <filename>files/MACHINEB</filename>.
4936 Finally, for any machine other than "MACHINEA" and
4937 "MACHINEB", the build system uses files from
4938 <filename>files/defconfig</filename>.
4939 </para>
4940
4941 <para>
4942 You can find out more about the patching process in the
4943 "<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
4944 section in the Yocto Project Overview and Concepts Manual
4945 and the
4946 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
4947 section in the Yocto Project Development Tasks Manual.
4948 See the
4949 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
4950 task as well.
4951 </para>
4952 </glossdef>
4953 </glossentry>
4954
4955 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
4956 <info>
4957 FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."
4958 </info>
4959 <glossdef>
4960 <para role="glossdeffirst">
4961 Allows you to define your own file permissions settings table as part of
4962 your configuration for the packaging process.
4963 For example, suppose you need a consistent set of custom permissions for
4964 a set of groups and users across an entire work project.
4965 It is best to do this in the packages themselves but this is not always
4966 possible.
4967 </para>
4968
4969 <para>
4970 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
4971 is located in the <filename>meta/files</filename> folder in the
4972 <link linkend='source-directory'>Source Directory</link>.
4973 If you create your own file permissions setting table, you should place it in your
4974 layer or the distro's layer.
4975 </para>
4976
4977 <para>
4978 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
4979 <filename>conf/local.conf</filename> file, which is found in the
4980 <link linkend='build-directory'>Build Directory</link>, to
4981 point to your custom <filename>fs-perms.txt</filename>.
4982 You can specify more than a single file permissions setting table.
4983 The paths you specify to these files must be defined within the
4984 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
4985 </para>
4986
4987 <para>
4988 For guidance on how to create your own file permissions settings table file,
4989 examine the existing <filename>fs-perms.txt</filename>.
4990 </para>
4991 </glossdef>
4992 </glossentry>
4993
4994 <glossentry id='var-FIT_HASH_ALG'><glossterm>FIT_HASH_ALG</glossterm>
4995 <info>
4996 FIT_HASH_ALG[doc] = "Specifies the hash algorithm used in creating the FIT Image."
4997 </info>
4998 <glossdef>
4999 <para role="glossdeffirst">
5000 Specifies the hash algorithm used in creating the FIT Image.
5001 For e.g. sha256.
5002 </para>
5003 </glossdef>
5004 </glossentry>
5005
5006 <glossentry id='var-FIT_SIGN_ALG'><glossterm>FIT_SIGN_ALG</glossterm>
5007 <info>
5008 FIT_SIGN_ALG[doc] = "Specifies the signature algorithm used in creating the FIT Image."
5009 </info>
5010 <glossdef>
5011 <para role="glossdeffirst">
5012 Specifies the signature algorithm used in creating the FIT Image.
5013 For e.g. rsa2048.
5014 </para>
5015 </glossdef>
5016 </glossentry>
5017
5018 <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm>
5019 <info>
5020 FONT_EXTRA_RDEPENDS[doc] = "When a recipe inherits the fontcache class, this variable specifies runtime dependencies for font packages. This variable defaults to 'fontconfig-utils'."
5021 </info>
5022 <glossdef>
5023 <para role="glossdeffirst">
5024 When inheriting the
5025 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5026 class, this variable specifies the runtime dependencies
5027 for font packages.
5028 By default, the <filename>FONT_EXTRA_RDEPENDS</filename>
5029 is set to "fontconfig-utils".
5030 </para>
5031 </glossdef>
5032 </glossentry>
5033
5034 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
5035 <info>
5036 FONT_PACKAGES[doc] = "When a recipe inherits the fontcache class, this variable identifies packages containing font files that need to be cached by Fontconfig."
5037 </info>
5038 <glossdef>
5039 <para role="glossdeffirst">
5040 When inheriting the
5041 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5042 class, this variable identifies packages containing font
5043 files that need to be cached by Fontconfig.
5044 By default, the <filename>fontcache</filename> class assumes
5045 that fonts are in the recipe's main package
5046 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5047 Use this variable if fonts you need are in a package
5048 other than that main package.
5049 </para>
5050 </glossdef>
5051 </glossentry>
5052
5053 <glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm>
5054 <info>
5055 FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."
5056 </info>
5057 <glossdef>
5058 <para role="glossdeffirst">
5059 Forces the removal of the packages listed in
5060 <filename>ROOTFS_RO_UNNEEDED</filename> during the
5061 generation of the root filesystem.
5062 </para>
5063
5064 <para>
5065 Set the variable to "1" to force the removal of these
5066 packages.
5067 </para>
5068 </glossdef>
5069 </glossentry>
5070
5071 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
5072 <info>
5073 FULL_OPTIMIZATION[doc]= "The options to pass in TARGET_CFLAGS and CFLAGS when compiling an optimized system. This variable defaults to '-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2'."
5074 </info>
5075 <glossdef>
5076 <para role="glossdeffirst">
5077 The options to pass in
5078 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
5079 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
5080 when compiling an optimized system.
5081 This variable defaults to
5082 "-O2 -pipe ${DEBUG_FLAGS}".
5083 </para>
5084 </glossdef>
5085 </glossentry>
5086 </glossdiv>
5087
5088 <glossdiv id='var-glossary-g'><title>G</title>
5089
5090 <glossentry id='var-GCCPIE'><glossterm>GCCPIE</glossterm>
5091 <info>
5092 GCCPIE[doc] = "Enables Position Independent Executables (PIE) within the GNU C Compiler (GCC)."
5093 </info>
5094 <glossdef>
5095 <para role="glossdeffirst">
5096 Enables Position Independent Executables (PIE) within the
5097 GNU C Compiler (GCC).
5098 Enabling PIE in the GCC makes Return Oriented Programming
5099 (ROP) attacks much more difficult to
5100 execute.
5101 </para>
5102
5103 <para>
5104 By default the <filename>security_flags.inc</filename>
5105 file enables PIE by setting the variable as follows:
5106 <literallayout class='monospaced'>
5107 GCCPIE ?= "--enable-default-pie"
5108 </literallayout>
5109 </para>
5110 </glossdef>
5111 </glossentry>
5112
5113 <glossentry id='var-GCCVERSION'><glossterm>GCCVERSION</glossterm>
5114 <info>
5115 GCCVERSION[doc] = "Specifies the default version of the GNU C Compiler (GCC) to use."
5116 </info>
5117 <glossdef>
5118 <para role="glossdeffirst">
5119 Specifies the default version of the GNU C Compiler (GCC)
5120 used for compilation.
5121 By default, <filename>GCCVERSION</filename> is set to
5122 "8.x" in the
5123 <filename>meta/conf/distro/include/tcmode-default.inc</filename>
5124 include file:
5125 <literallayout class='monospaced'>
5126 GCCVERSION ?= "8.%"
5127 </literallayout>
5128 You can override this value by setting it in a configuration
5129 file such as the <filename>local.conf</filename>.
5130 </para>
5131 </glossdef>
5132 </glossentry>
5133
5134 <glossentry id='var-GDB'><glossterm>GDB</glossterm>
5135 <info>
5136 GDB[doc] = "The minimal command and arguments to run the GNU Debugger."
5137 </info>
5138 <glossdef>
5139 <para role="glossdeffirst">
5140 The minimal command and arguments to run the GNU Debugger.
5141 </para>
5142 </glossdef>
5143 </glossentry>
5144
5145 <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>
5146 <info>
5147 GITDIR[doc] = "The directory where Git clones will be stored."
5148 </info>
5149 <glossdef>
5150 <para role="glossdeffirst">
5151 The directory in which a local copy of a Git repository
5152 is stored when it is cloned.
5153 </para>
5154 </glossdef>
5155 </glossentry>
5156
5157 <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm>
5158 <info>
5159 GLIBC_GENERATE_LOCALES[doc]= "Specifies the list of GLIBC locales to generate should you not wish to generate all LIBC locals, which can be time consuming."
5160 </info>
5161 <glossdef>
5162 <para role="glossdeffirst">
5163 Specifies the list of GLIBC locales to generate should you
5164 not wish to generate all LIBC locals, which can be time
5165 consuming.
5166 <note>
5167 If you specifically remove the locale
5168 <filename>en_US.UTF-8</filename>, you must set
5169 <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>
5170 appropriately.
5171 </note>
5172 </para>
5173
5174 <para>
5175 You can set <filename>GLIBC_GENERATE_LOCALES</filename>
5176 in your <filename>local.conf</filename> file.
5177 By default, all locales are generated.
5178 <literallayout class='monospaced'>
5179 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
5180 </literallayout>
5181 </para>
5182 </glossdef>
5183 </glossentry>
5184
5185 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
5186 <info>
5187 GROUPADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupadd command if you wish to add a group to the system when the package is installed."
5188 </info>
5189 <glossdef>
5190 <para role="glossdeffirst">
5191 When inheriting the
5192 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5193 class, this variable
5194 specifies for a package what parameters should be passed
5195 to the <filename>groupadd</filename> command
5196 if you wish to add a group to the system when the package
5197 is installed.
5198 </para>
5199
5200 <para>
5201 Here is an example from the <filename>dbus</filename>
5202 recipe:
5203 <literallayout class='monospaced'>
5204 GROUPADD_PARAM_${PN} = "-r netdev"
5205 </literallayout>
5206 For information on the standard Linux shell command
5207 <filename>groupadd</filename>, see
5208 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
5209 </para>
5210 </glossdef>
5211 </glossentry>
5212
5213 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
5214 <info>
5215 GROUPMEMS_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupmems command if you wish to modify the members of a group when the package is installed."
5216 </info>
5217 <glossdef>
5218 <para role="glossdeffirst">
5219 When inheriting the
5220 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5221 class, this variable
5222 specifies for a package what parameters should be passed
5223 to the <filename>groupmems</filename> command
5224 if you wish to modify the members of a group when the
5225 package is installed.
5226 </para>
5227
5228 <para>
5229 For information on the standard Linux shell command
5230 <filename>groupmems</filename>, see
5231 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
5232 </para>
5233 </glossdef>
5234 </glossentry>
5235
5236 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
5237 <info>
5238 GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."
5239 </info>
5240 <glossdef>
5241 <para role="glossdeffirst">
5242 Configures the GNU GRand Unified Bootloader (GRUB) to have
5243 graphics and serial in the boot menu.
5244 Set this variable to "1" in your
5245 <filename>local.conf</filename> or distribution
5246 configuration file to enable graphics and serial
5247 in the menu.
5248 </para>
5249
5250 <para>
5251 See the
5252 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5253 class for more information on how this variable is used.
5254 </para>
5255 </glossdef>
5256 </glossentry>
5257
5258 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
5259 <info>
5260 GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration."
5261 </info>
5262 <glossdef>
5263 <para role="glossdeffirst">
5264 Additional options to add to the GNU GRand Unified
5265 Bootloader (GRUB) configuration.
5266 Use a semi-colon character (<filename>;</filename>) to
5267 separate multiple options.
5268 </para>
5269
5270 <para>
5271 The <filename>GRUB_OPTS</filename> variable is optional.
5272 See the
5273 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5274 class for more information on how this variable is used.
5275 </para>
5276 </glossdef>
5277 </glossentry>
5278
5279 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
5280 <info>
5281 GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."
5282 </info>
5283 <glossdef>
5284 <para role="glossdeffirst">
5285 Specifies the timeout before executing the default
5286 <filename>LABEL</filename> in the GNU GRand Unified
5287 Bootloader (GRUB).
5288 </para>
5289
5290 <para>
5291 The <filename>GRUB_TIMEOUT</filename> variable is optional.
5292 See the
5293 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5294 class for more information on how this variable is used.
5295 </para>
5296 </glossdef>
5297 </glossentry>
5298
5299 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
5300 <info>
5301 GTKIMMODULES_PACKAGES[doc] = "For recipes that inherit the gtk-immodules-cache class, this variable specifies the packages that contain the GTK+ input method modules being installed when the modules are in packages other than the main package."
5302 </info>
5303 <glossdef>
5304 <para role="glossdeffirst">
5305 When inheriting the
5306 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
5307 class, this variable specifies the packages that contain the
5308 GTK+ input method modules being installed when the modules
5309 are in packages other than the main package.
5310 </para>
5311 </glossdef>
5312 </glossentry>
5313
5314 </glossdiv>
5315
5316 <glossdiv id='var-glossary-h'><title>H</title>
5317
5318 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
5319 <info>
5320 HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."
5321 </info>
5322 <glossdef>
5323 <para role="glossdeffirst">
5324 Website where more information about the software the recipe is building
5325 can be found.
5326 </para>
5327 </glossdef>
5328 </glossentry>
5329
5330 <glossentry id='var-HOST_ARCH'><glossterm>HOST_ARCH</glossterm>
5331 <info>
5332 HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH."
5333
5334 </info>
5335 <glossdef>
5336 <para role="glossdeffirst">
5337 The name of the target architecture, which is normally
5338 the same as
5339 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
5340 The OpenEmbedded build system supports many
5341 architectures.
5342 Here is an example list of architectures supported.
5343 This list is by no means complete as the architecture
5344 is configurable:
5345 <literallayout class='monospaced'>
5346 arm
5347 i586
5348 x86_64
5349 powerpc
5350 powerpc64
5351 mips
5352 mipsel
5353 </literallayout>
5354 </para>
5355 </glossdef>
5356 </glossentry>
5357
5358 <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm>
5359 <info>
5360 HOST_CC_ARCH[doc] = "The name of the host architecture. Normally same as the TARGET_CC_ARCH."
5361 </info>
5362 <glossdef>
5363 <para role="glossdeffirst">
5364 Specifies architecture-specific compiler flags that are
5365 passed to the C compiler.
5366 </para>
5367
5368 <para>
5369 Default initialization for <filename>HOST_CC_ARCH</filename>
5370 varies depending on what is being built:
5371 <itemizedlist>
5372 <listitem><para>
5373 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
5374 when building for the target
5375 </para></listitem>
5376 <listitem><para>
5377 <filename>BUILD_CC_ARCH</filename>
5378 when building for the build host (i.e.
5379 <filename>-native</filename>)
5380 </para></listitem>
5381 <listitem><para>
5382 <filename>BUILDSDK_CC_ARCH</filename>
5383 when building for an SDK (i.e.
5384 <filename>nativesdk-</filename>)
5385 </para></listitem>
5386 </itemizedlist>
5387 </para>
5388 </glossdef>
5389 </glossentry>
5390
5391 <glossentry id='var-HOST_OS'><glossterm>HOST_OS</glossterm>
5392 <info>
5393 HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS."
5394 </info>
5395 <glossdef>
5396 <para role="glossdeffirst">
5397 Specifies the name of the target operating system, which
5398 is normally the same as the
5399 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>.
5400 The variable can be set to "linux" for <filename>glibc</filename>-based systems and
5401 to "linux-musl" for <filename>musl</filename>.
5402 For ARM/EABI targets, there are also "linux-gnueabi" and
5403 "linux-musleabi" values possible.
5404 </para>
5405 </glossdef>
5406 </glossentry>
5407
5408 <glossentry id='var-HOST_PREFIX'><glossterm>HOST_PREFIX</glossterm>
5409 <info>
5410 HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."
5411 </info>
5412 <glossdef>
5413 <para role="glossdeffirst">
5414 Specifies the prefix for the cross-compile toolchain.
5415 <filename>HOST_PREFIX</filename> is normally the same as
5416 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>.
5417 </para>
5418 </glossdef>
5419 </glossentry>
5420
5421 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
5422 <info>
5423 HOST_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the build is occurring in the context of the current recipe."
5424 </info>
5425 <glossdef>
5426 <para role="glossdeffirst">
5427 Specifies the system, including the architecture and the
5428 operating system, for which the build is occurring
5429 in the context of the current recipe.
5430 </para>
5431
5432 <para>
5433 The OpenEmbedded build system automatically sets this
5434 variable based on
5435 <link linkend='var-HOST_ARCH'><filename>HOST_ARCH</filename></link>,
5436 <link linkend='var-HOST_VENDOR'><filename>HOST_VENDOR</filename></link>,
5437 and
5438 <link linkend='var-HOST_OS'><filename>HOST_OS</filename></link>
5439 variables.
5440 <note>
5441 You do not need to set the variable yourself.
5442 </note>
5443 </para>
5444
5445 <para>
5446 Consider these two examples:
5447 <itemizedlist>
5448 <listitem><para>Given a native recipe on a 32-bit
5449 x86 machine running Linux, the value is
5450 "i686-linux".
5451 </para></listitem>
5452 <listitem><para>Given a recipe being built for a
5453 little-endian MIPS target running Linux,
5454 the value might be "mipsel-linux".
5455 </para></listitem>
5456 </itemizedlist>
5457 </para>
5458 </glossdef>
5459 </glossentry>
5460
5461 <glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm>
5462 <info>
5463 HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
5464 </info>
5465 <glossdef>
5466 <para role="glossdeffirst">
5467 A space-separated list (filter) of tools on the build host
5468 that should be allowed to be called from within build tasks.
5469 Using this filter helps reduce the possibility of host
5470 contamination.
5471 If a tool specified in the value of
5472 <filename>HOSTTOOLS</filename> is not found on the
5473 build host, the OpenEmbedded build system produces
5474 an error and the build is not started.
5475 </para>
5476
5477 <para>
5478 For additional information, see
5479 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>.
5480 </para>
5481 </glossdef>
5482 </glossentry>
5483
5484 <glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm>
5485 <info>
5486 HOSTTOOLS_NONFATAL[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
5487 </info>
5488 <glossdef>
5489 <para role="glossdeffirst">
5490 A space-separated list (filter) of tools on the build host
5491 that should be allowed to be called from within build tasks.
5492 Using this filter helps reduce the possibility of host
5493 contamination.
5494 Unlike
5495 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>,
5496 the OpenEmbedded build system does not produce an error
5497 if a tool specified in the value of
5498 <filename>HOSTTOOLS_NONFATAL</filename> is not found on the
5499 build host.
5500 Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename>
5501 to filter optional host tools.
5502 </para>
5503 </glossdef>
5504 </glossentry>
5505
5506 <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm>
5507 <info>
5508 HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."
5509 </info>
5510 <glossdef>
5511 <para role="glossdeffirst">
5512 Specifies the name of the vendor.
5513 <filename>HOST_VENDOR</filename> is normally the same as
5514 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>.
5515 </para>
5516 </glossdef>
5517 </glossentry>
5518
5519 </glossdiv>
5520
5521 <glossdiv id='var-glossary-i'><title>I</title>
5522
5523 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
5524 <info>
5525 ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."
5526 </info>
5527 <glossdef>
5528 <para role="glossdeffirst">
5529 Disables or enables the <filename>icecc</filename>
5530 (Icecream) function.
5531 For more information on this function and best practices
5532 for using this variable, see the
5533 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
5534 section.
5535 </para>
5536
5537 <para>
5538 Setting this variable to "1" in your
5539 <filename>local.conf</filename> disables the function:
5540 <literallayout class='monospaced'>
5541 ICECC_DISABLED ??= "1"
5542 </literallayout>
5543 To enable the function, set the variable as follows:
5544 <literallayout class='monospaced'>
5545 ICECC_DISABLED = ""
5546 </literallayout>
5547 </para>
5548 </glossdef>
5549 </glossentry>
5550
5551 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
5552 <info>
5553 ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."
5554 </info>
5555 <glossdef>
5556 <para role="glossdeffirst">
5557 Points to the <filename>icecc-create-env</filename> script
5558 that you provide.
5559 This variable is used by the
5560 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5561 class.
5562 You set this variable in your
5563 <filename>local.conf</filename> file.
5564 </para>
5565
5566 <para>
5567 If you do not point to a script that you provide, the
5568 OpenEmbedded build system uses the default script provided
5569 by the <filename>icecc-create-env.bb</filename> recipe,
5570 which is a modified version and not the one that comes with
5571 <filename>icecc</filename>.
5572 </para>
5573 </glossdef>
5574 </glossentry>
5575
5576 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
5577 <info>
5578 ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."
5579 </info>
5580 <glossdef>
5581 <para role="glossdeffirst">
5582 Extra options passed to the <filename>make</filename>
5583 command during the
5584 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
5585 task that specify parallel compilation.
5586 This variable usually takes the form of
5587 "-j <replaceable>x</replaceable>", where
5588 <replaceable>x</replaceable> represents the maximum
5589 number of parallel threads <filename>make</filename> can
5590 run.
5591 <note>
5592 The options passed affect builds on all enabled
5593 machines on the network, which are machines running the
5594 <filename>iceccd</filename> daemon.
5595 </note>
5596 </para>
5597
5598 <para>
5599 If your enabled machines support multiple cores,
5600 coming up with the maximum number of parallel threads
5601 that gives you the best performance could take some
5602 experimentation since machine speed, network lag,
5603 available memory, and existing machine loads can all
5604 affect build time.
5605 Consequently, unlike the
5606 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5607 variable, there is no rule-of-thumb for setting
5608 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
5609 optimal performance.
5610 </para>
5611
5612 <para>
5613 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
5614 the build system does not use it (i.e. the system does
5615 not detect and assign the number of cores as is done with
5616 <filename>PARALLEL_MAKE</filename>).
5617 </para>
5618 </glossdef>
5619 </glossentry>
5620
5621 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
5622 <info>
5623 ICECC_PATH[doc] = "The location of the icecc binary."
5624 </info>
5625 <glossdef>
5626 <para role="glossdeffirst">
5627 The location of the <filename>icecc</filename> binary.
5628 You can set this variable in your
5629 <filename>local.conf</filename> file.
5630 If your <filename>local.conf</filename> file does not define
5631 this variable, the
5632 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5633 class attempts to define it by locating
5634 <filename>icecc</filename> using <filename>which</filename>.
5635 </para>
5636 </glossdef>
5637 </glossentry>
5638
5639 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
5640 <info>
5641 ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."
5642 </info>
5643 <glossdef>
5644 <para role="glossdeffirst">
5645 Identifies user classes that you do not want the
5646 Icecream distributed compile support to consider.
5647 This variable is used by the
5648 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5649 class.
5650 You set this variable in your
5651 <filename>local.conf</filename> file.
5652 </para>
5653
5654 <para>
5655 When you list classes using this variable, you are
5656 "blacklisting" them from distributed compilation across
5657 remote hosts.
5658 Any classes you list will be distributed and compiled
5659 locally.
5660 </para>
5661 </glossdef>
5662 </glossentry>
5663
5664 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
5665 <info>
5666 ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."
5667 </info>
5668 <glossdef>
5669 <para role="glossdeffirst">
5670 Identifies user recipes that you do not want the
5671 Icecream distributed compile support to consider.
5672 This variable is used by the
5673 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5674 class.
5675 You set this variable in your
5676 <filename>local.conf</filename> file.
5677 </para>
5678
5679 <para>
5680 When you list packages using this variable, you are
5681 "blacklisting" them from distributed compilation across
5682 remote hosts.
5683 Any packages you list will be distributed and compiled
5684 locally.
5685 </para>
5686 </glossdef>
5687 </glossentry>
5688
5689 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
5690 <info>
5691 ICECC_USER_PACKAGE_WL[doc] = "Identifies user recipes that use an empty PARALLEL_MAKE variable that you want to force remote distributed compilation on using the Icecream distributed compile support."
5692 </info>
5693 <glossdef>
5694 <para role="glossdeffirst">
5695 Identifies user recipes that use an empty
5696 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5697 variable that you want to force remote distributed
5698 compilation on using the Icecream distributed compile
5699 support.
5700 This variable is used by the
5701 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5702 class.
5703 You set this variable in your
5704 <filename>local.conf</filename> file.
5705 </para>
5706 </glossdef>
5707 </glossentry>
5708
5709 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
5710 <info>
5711 IMAGE_BASENAME[doc] = "The base name of image output files."
5712 </info>
5713 <glossdef>
5714 <para role="glossdeffirst">
5715 The base name of image output files.
5716 This variable defaults to the recipe name
5717 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5718 </para>
5719 </glossdef>
5720 </glossentry>
5721
5722 <glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm>
5723 <info>
5724 IMAGE_BOOT_FILES[doc] = "A space-separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition."
5725 </info>
5726 <glossdef>
5727 <para role="glossdeffirst">
5728 A space-separated list of files installed into the
5729 boot partition when preparing an image using the Wic tool
5730 with the <filename>bootimg-partition</filename> or <filename>bootimg-efi</filename> source
5731 plugin.
5732 By default, the files are installed under the same name as
5733 the source files.
5734 To change the installed name, separate it from the
5735 original name with a semi-colon (;).
5736 Source files need to be located in
5737 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>.
5738 Here are two examples:
5739
5740 <literallayout class="monospaced">
5741 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
5742 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
5743 </literallayout>
5744 </para>
5745
5746 <para>
5747 Alternatively, source files can be picked up using
5748 a glob pattern.
5749 In this case, the destination file must have the same name
5750 as the base name of the source file path.
5751 To install files into a directory within the
5752 target location, pass its name after a semi-colon
5753 (;).
5754 Here are two examples:
5755 <literallayout class="monospaced">
5756 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
5757 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
5758 </literallayout>
5759 The first example installs all files from
5760 <filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>
5761 into the root of the target partition.
5762 The second example installs the same files into a
5763 <filename>boot</filename> directory within the
5764 target partition.
5765 </para>
5766
5767 <para>
5768 You can find information on how to use the Wic tool in the
5769 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
5770 section of the Yocto Project Development Tasks Manual.
5771 Reference material for Wic is located in the
5772 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (.wks) Reference</ulink>"
5773 chapter.
5774 </para>
5775 </glossdef>
5776 </glossentry>
5777
5778 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
5779 <info>
5780 IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."
5781 </info>
5782 <glossdef>
5783 <para role="glossdeffirst">
5784 A list of classes that all images should inherit.
5785 You typically use this variable to specify the list of
5786 classes that register the different types of images
5787 the OpenEmbedded build system creates.
5788 </para>
5789
5790 <para>
5791 The default value for <filename>IMAGE_CLASSES</filename> is
5792 <filename>image_types</filename>.
5793 You can set this variable in your
5794 <filename>local.conf</filename> or in a distribution
5795 configuration file.
5796 </para>
5797
5798 <para>
5799 For more information, see
5800 <filename>meta/classes/image_types.bbclass</filename> in the
5801 <link linkend='source-directory'>Source Directory</link>.
5802 </para>
5803 </glossdef>
5804 </glossentry>
5805
5806 <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>
5807 <info>
5808 IMAGE_CMD[doc] = "Specifies the command to create the image file for a specific image type, which corresponds to the value set set in IMAGE_FSTYPES, (e.g. ext3, btrfs, and so forth)."
5809 </info>
5810 <glossdef>
5811 <para role="glossdeffirst">
5812 Specifies the command to create the image file for a
5813 specific image type, which corresponds to the value set
5814 set in
5815 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
5816 (e.g. <filename>ext3</filename>,
5817 <filename>btrfs</filename>, and so forth).
5818 When setting this variable, you should use
5819 an override for the associated type.
5820 Here is an example:
5821 <literallayout class='monospaced'>
5822 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
5823 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
5824 ${EXTRA_IMAGECMD}"
5825 </literallayout>
5826 </para>
5827
5828 <para>
5829 You typically do not need to set this variable unless
5830 you are adding support for a new image type.
5831 For more examples on how to set this variable, see the
5832 <link linkend='ref-classes-image_types'><filename>image_types</filename></link>
5833 class file, which is
5834 <filename>meta/classes/image_types.bbclass</filename>.
5835 </para>
5836 </glossdef>
5837 </glossentry>
5838
5839 <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>
5840 <info>
5841 IMAGE_DEVICE_TABLES[doc] = "Specifies one or more files that contain custom device tables that are passed to the makedevs command as part of creating an image."
5842 </info>
5843 <glossdef>
5844 <para role="glossdeffirst">
5845 Specifies one or more files that contain custom device
5846 tables that are passed to the
5847 <filename>makedevs</filename> command as part of creating
5848 an image.
5849 These files list basic device nodes that should be
5850 created under <filename>/dev</filename> within the image.
5851 If <filename>IMAGE_DEVICE_TABLES</filename> is not set,
5852 <filename>files/device_table-minimal.txt</filename> is
5853 used, which is located by
5854 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
5855 For details on how you should write device table files,
5856 see <filename>meta/files/device_table-minimal.txt</filename>
5857 as an example.
5858 </para>
5859 </glossdef>
5860 </glossentry>
5861
5862 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
5863 <info>
5864 IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."
5865 </info>
5866 <glossdef>
5867 <para role="glossdeffirst">
5868 The primary list of features to include in an image.
5869 Typically, you configure this variable in an image recipe.
5870 Although you can use this variable from your
5871 <filename>local.conf</filename> file, which is found in the
5872 <link linkend='build-directory'>Build Directory</link>,
5873 best practices dictate that you do not.
5874 <note>
5875 To enable extra features from outside the image recipe,
5876 use the
5877 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
5878 </note>
5879 </para>
5880
5881 <para>
5882 For a list of image features that ships with the Yocto
5883 Project, see the
5884 "<link linkend="ref-features-image">Image Features</link>"
5885 section.
5886 </para>
5887
5888 <para>
5889 For an example that shows how to customize your image by
5890 using this variable, see the
5891 "<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>"
5892 section in the Yocto Project Development Tasks Manual.
5893 </para>
5894 </glossdef>
5895 </glossentry>
5896
5897 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
5898 <info>
5899 IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."
5900 </info>
5901 <glossdef>
5902 <para role="glossdeffirst">
5903 Specifies the formats the OpenEmbedded build system uses
5904 during the build when creating the root filesystem.
5905 For example, setting <filename>IMAGE_FSTYPES</filename>
5906 as follows causes the build system to create root
5907 filesystems using two formats: <filename>.ext3</filename>
5908 and <filename>.tar.bz2</filename>:
5909 <literallayout class='monospaced'>
5910 IMAGE_FSTYPES = "ext3 tar.bz2"
5911 </literallayout>
5912 </para>
5913
5914 <para>
5915 For the complete list of supported image formats from which
5916 you can choose, see
5917 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
5918 </para>
5919
5920 <note><title>Notes</title>
5921 <itemizedlist>
5922 <listitem><para>
5923 If an image recipe uses the "inherit image" line
5924 and you are setting
5925 <filename>IMAGE_FSTYPES</filename> inside the
5926 recipe, you must set
5927 <filename>IMAGE_FSTYPES</filename> prior to
5928 using the "inherit image" line.
5929 </para></listitem>
5930 <listitem><para>
5931 Due to the way the OpenEmbedded build system
5932 processes this variable, you cannot update its
5933 contents by using <filename>_append</filename> or
5934 <filename>_prepend</filename>.
5935 You must use the <filename>+=</filename>
5936 operator to add one or more options to the
5937 <filename>IMAGE_FSTYPES</filename> variable.
5938 </para></listitem>
5939 </itemizedlist>
5940 </note>
5941 </glossdef>
5942 </glossentry>
5943
5944 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
5945 <info>
5946 IMAGE_INSTALL[doc] = "Used by recipes to specify the packages to install into an image through image.bbclass."
5947 </info>
5948 <glossdef>
5949 <para role="glossdeffirst">
5950 Used by recipes to specify the packages to install into an
5951 image through the
5952 <link linkend='ref-classes-image'><filename>image</filename></link>
5953 class.
5954 Use the <filename>IMAGE_INSTALL</filename> variable with
5955 care to avoid ordering issues.
5956 </para>
5957
5958 <para>
5959 Image recipes set <filename>IMAGE_INSTALL</filename>
5960 to specify the packages to install into an image through
5961 <filename>image.bbclass</filename>.
5962 Additionally, "helper" classes such as the
5963 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
5964 class exist that can take lists used with
5965 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
5966 and turn them into auto-generated entries in
5967 <filename>IMAGE_INSTALL</filename> in addition to its
5968 default contents.
5969 </para>
5970
5971 <para>
5972 When you use this variable, it is best to use it as follows:
5973 <literallayout class='monospaced'>
5974 IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"
5975 </literallayout>
5976 Be sure to include the space between the quotation character
5977 and the start of the package name or names.
5978 <note><title>Caution</title>
5979 <itemizedlist>
5980 <listitem><para>
5981 When working with a
5982 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5983 image, do not use the
5984 <filename>IMAGE_INSTALL</filename> variable to
5985 specify packages for installation.
5986 Instead, use the
5987 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
5988 variable, which allows the initial RAM
5989 filesystem (initramfs) recipe to use a fixed
5990 set of packages and not be affected by
5991 <filename>IMAGE_INSTALL</filename>.
5992 For information on creating an initramfs, see
5993 the
5994 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
5995 section in the Yocto Project Development Tasks
5996 Manual.
5997 </para></listitem>
5998 <listitem><para>
5999 Using <filename>IMAGE_INSTALL</filename> with
6000 the
6001 <ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
6002 BitBake operator within the
6003 <filename>/conf/local.conf</filename> file or
6004 from within an image recipe is not recommended.
6005 Use of this operator in these ways can cause
6006 ordering issues.
6007 Since <filename>core-image.bbclass</filename>
6008 sets <filename>IMAGE_INSTALL</filename> to a
6009 default value using the
6010 <ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
6011 operator, using a <filename>+=</filename>
6012 operation against
6013 <filename>IMAGE_INSTALL</filename> results in
6014 unexpected behavior when used within
6015 <filename>conf/local.conf</filename>.
6016 Furthermore, the same operation from within
6017 an image recipe may or may not succeed
6018 depending on the specific situation.
6019 In both these cases, the behavior is contrary
6020 to how most users expect the
6021 <filename>+=</filename> operator to work.
6022 </para></listitem>
6023 </itemizedlist>
6024 </note>
6025 </para>
6026 </glossdef>
6027 </glossentry>
6028
6029 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
6030 <info>
6031 IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."
6032 </info>
6033 <glossdef>
6034 <para role="glossdeffirst">
6035 Specifies the list of locales to install into the image
6036 during the root filesystem construction process.
6037 The OpenEmbedded build system automatically splits locale
6038 files, which are used for localization, into separate
6039 packages.
6040 Setting the <filename>IMAGE_LINGUAS</filename> variable
6041 ensures that any locale packages that correspond to packages
6042 already selected for installation into the image are also
6043 installed.
6044 Here is an example:
6045 <literallayout class='monospaced'>
6046 IMAGE_LINGUAS = "pt-br de-de"
6047 </literallayout>
6048 </para>
6049
6050 <para>
6051 In this example, the build system ensures any Brazilian
6052 Portuguese and German locale files that correspond to
6053 packages in the image are installed (i.e.
6054 <filename>*-locale-pt-br</filename>
6055 and <filename>*-locale-de-de</filename> as well as
6056 <filename>*-locale-pt</filename>
6057 and <filename>*-locale-de</filename>, since some software
6058 packages only provide locale files by language and not by
6059 country-specific language).
6060 </para>
6061
6062 <para>
6063 See the
6064 <link linkend='var-GLIBC_GENERATE_LOCALES'><filename>GLIBC_GENERATE_LOCALES</filename></link>
6065 variable for information on generating GLIBC locales.
6066 </para>
6067 </glossdef>
6068 </glossentry>
6069
6070 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
6071 <info>
6072 IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."
6073 </info>
6074 <glossdef>
6075 <para role="glossdeffirst">
6076 The manifest file for the image.
6077 This file lists all the installed packages that make up
6078 the image.
6079 The file contains package information on a line-per-package
6080 basis as follows:
6081 <literallayout class='monospaced'>
6082 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
6083 </literallayout>
6084 </para>
6085
6086 <para>
6087 The
6088 <link linkend='ref-classes-image'><filename>image</filename></link>
6089 class defines the manifest file as follows:
6090 <literallayout class='monospaced'>
6091 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
6092 </literallayout>
6093 The location is derived using the
6094 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
6095 and
6096 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
6097 variables.
6098 You can find information on how the image
6099 is created in the
6100 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
6101 section in the Yocto Project Overview and Concepts Manual.
6102 </para>
6103 </glossdef>
6104 </glossentry>
6105
6106 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
6107 <info>
6108 IMAGE_NAME[doc] = "The name of the output image files minus the extension."
6109 </info>
6110 <glossdef>
6111 <para role="glossdeffirst">
6112 The name of the output image files minus the extension.
6113 This variable is derived using the
6114 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
6115 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
6116 and
6117 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
6118 variables:
6119 <literallayout class='monospaced'>
6120 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
6121 </literallayout>
6122 </para>
6123 </glossdef>
6124 </glossentry>
6125
6126 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
6127 <info>
6128 IMAGE_OVERHEAD_FACTOR[doc] = "Defines a multiplier that the build system applies to the initial image size for cases when the multiplier times the returned disk usage value for the image is greater than the sum of IMAGE_ROOTFS_SIZE and IMAGE_ROOTFS_EXTRA_SPACE."
6129 </info>
6130 <glossdef>
6131 <para role="glossdeffirst">
6132 Defines a multiplier that the build system applies to the initial image
6133 size for cases when the multiplier times the returned disk usage value
6134 for the image is greater than the sum of
6135 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6136 and
6137 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
6138 The result of the multiplier applied to the initial image size creates
6139 free disk space in the image as overhead.
6140 By default, the build process uses a multiplier of 1.3 for this variable.
6141 This default value results in 30% free disk space added to the image when this
6142 method is used to determine the final generated image size.
6143 You should be aware that post install scripts and the package management
6144 system uses disk space inside this overhead area.
6145 Consequently, the multiplier does not produce an image with
6146 all the theoretical free disk space.
6147 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6148 for information on how the build system determines the overall image size.
6149 </para>
6150
6151 <para>
6152 The default 30% free disk space typically gives the image enough room to boot
6153 and allows for basic post installs while still leaving a small amount of
6154 free disk space.
6155 If 30% free space is inadequate, you can increase the default value.
6156 For example, the following setting gives you 50% free space added to the image:
6157 <literallayout class='monospaced'>
6158 IMAGE_OVERHEAD_FACTOR = "1.5"
6159 </literallayout>
6160 </para>
6161
6162 <para>
6163 Alternatively, you can ensure a specific amount of free disk space is added
6164 to the image by using the
6165 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6166 variable.
6167 </para>
6168 </glossdef>
6169 </glossentry>
6170
6171 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
6172 <info>
6173 IMAGE_PKGTYPE[doc] = "Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."
6174 </info>
6175 <glossdef>
6176 <para role="glossdeffirst">
6177 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used
6178 by the OpenEmbedded build system.
6179 The variable is defined appropriately by the
6180 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
6181 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
6182 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
6183 or
6184 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
6185 class.
6186 <note><title>Warning</title>
6187 The <filename>package_tar</filename> class is broken
6188 and is not supported.
6189 It is recommended that you do not use it.
6190 </note>
6191 </para>
6192
6193 <para>
6194 The
6195 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_*</filename></link>
6196 and
6197 <link linkend='ref-classes-image'><filename>image</filename></link>
6198 classes use the <filename>IMAGE_PKGTYPE</filename> for
6199 packaging up images and SDKs.
6200 </para>
6201
6202 <para>
6203 You should not set the <filename>IMAGE_PKGTYPE</filename>
6204 manually.
6205 Rather, the variable is set indirectly through the
6206 appropriate
6207 <link linkend='ref-classes-package'><filename>package_*</filename></link>
6208 class using the
6209 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
6210 variable.
6211 The OpenEmbedded build system uses the first package type
6212 (e.g. DEB, RPM, or IPK) that appears with the variable
6213 <note>
6214 Files using the <filename>.tar</filename> format are
6215 never used as a substitute packaging format for DEB,
6216 RPM, and IPK formatted files for your image or SDK.
6217 </note>
6218 </para>
6219 </glossdef>
6220 </glossentry>
6221
6222 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
6223 <info>
6224 IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the final image output files."
6225 </info>
6226 <glossdef>
6227 <para role="glossdeffirst">
6228 Specifies a list of functions to call once the
6229 OpenEmbedded build system creates the final image
6230 output files.
6231 You can specify functions separated by semicolons:
6232 <literallayout class='monospaced'>
6233 IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6234 </literallayout>
6235 </para>
6236
6237 <para>
6238 If you need to pass the root filesystem path to a command
6239 within the function, you can use
6240 <filename>${IMAGE_ROOTFS}</filename>, which points to
6241 the directory that becomes the root filesystem image.
6242 See the
6243 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6244 variable for more information.
6245 </para>
6246 </glossdef>
6247 </glossentry>
6248
6249 <glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>
6250 <info>
6251 IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system creates the final image output files."
6252 </info>
6253 <glossdef>
6254 <para role="glossdeffirst">
6255 Specifies a list of functions to call before the
6256 OpenEmbedded build system creates the final image
6257 output files.
6258 You can specify functions separated by semicolons:
6259 <literallayout class='monospaced'>
6260 IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6261 </literallayout>
6262 </para>
6263
6264 <para>
6265 If you need to pass the root filesystem path to a command
6266 within the function, you can use
6267 <filename>${IMAGE_ROOTFS}</filename>, which points to
6268 the directory that becomes the root filesystem image.
6269 See the
6270 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6271 variable for more information.
6272 </para>
6273 </glossdef>
6274 </glossentry>
6275
6276 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
6277 <info>
6278 IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."
6279 </info>
6280 <glossdef>
6281 <para role="glossdeffirst">
6282 The location of the root filesystem while it is under
6283 construction (i.e. during the
6284 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
6285 task).
6286 This variable is not configurable.
6287 Do not change it.
6288 </para>
6289 </glossdef>
6290 </glossentry>
6291
6292 <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>
6293 <info>
6294 IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."
6295 </info>
6296 <glossdef>
6297 <para role="glossdeffirst">
6298 Specifies the alignment for the output image file in
6299 Kbytes.
6300 If the size of the image is not a multiple of
6301 this value, then the size is rounded up to the nearest
6302 multiple of the value.
6303 The default value is "1".
6304 See
6305 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
6306 for additional information.
6307 </para>
6308 </glossdef>
6309 </glossentry>
6310
6311 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
6312 <info>
6313 IMAGE_ROOTFS_EXTRA_SPACE[doc] = "Defines additional free disk space created in the image in Kbytes. By default, this variable is set to '0'."
6314 </info>
6315 <glossdef>
6316 <para role="glossdeffirst">
6317 Defines additional free disk space created in the image in Kbytes.
6318 By default, this variable is set to "0".
6319 This free disk space is added to the image after the build system determines
6320 the image size as described in
6321 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
6322 </para>
6323
6324 <para>
6325 This variable is particularly useful when you want to ensure that a
6326 specific amount of free disk space is available on a device after an image
6327 is installed and running.
6328 For example, to be sure 5 Gbytes of free disk space is available, set the
6329 variable as follows:
6330 <literallayout class='monospaced'>
6331 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
6332 </literallayout>
6333 </para>
6334
6335 <para>
6336 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
6337 of extra space with the line:
6338 <literallayout class='monospaced'>
6339 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
6340 </literallayout>
6341 </para>
6342 </glossdef>
6343 </glossentry>
6344
6345 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
6346 <info>
6347 IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."
6348 </info>
6349 <glossdef>
6350 <para role="glossdeffirst">
6351 Defines the size in Kbytes for the generated image.
6352 The OpenEmbedded build system determines the final size for the generated
6353 image using an algorithm that takes into account the initial disk space used
6354 for the generated image, a requested size for the image, and requested
6355 additional free disk space to be added to the image.
6356 Programatically, the build system determines the final size of the
6357 generated image as follows:
6358 <literallayout class='monospaced'>
6359 if (image-du * overhead) &lt; rootfs-size:
6360 internal-rootfs-size = rootfs-size + xspace
6361 else:
6362 internal-rootfs-size = (image-du * overhead) + xspace
6363
6364 where:
6365
6366 image-du = Returned value of the du command on
6367 the image.
6368
6369 overhead = IMAGE_OVERHEAD_FACTOR
6370
6371 rootfs-size = IMAGE_ROOTFS_SIZE
6372
6373 internal-rootfs-size = Initial root filesystem
6374 size before any modifications.
6375
6376 xspace = IMAGE_ROOTFS_EXTRA_SPACE
6377 </literallayout>
6378 </para>
6379
6380 <para>
6381 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
6382 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
6383 variables for related information.
6384<!-- In the above example, <filename>overhead</filename> is defined by the
6385 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
6386 variable, <filename>xspace</filename> is defined by the
6387 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6388 variable, and <filename>du</filename> is the results of the disk usage command
6389 on the initially generated image. -->
6390 </para>
6391 </glossdef>
6392 </glossentry>
6393
6394 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
6395 <info>
6396 IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."
6397 </info>
6398 <glossdef>
6399 <para role="glossdeffirst">
6400 Specifies a dependency from one image type on another.
6401 Here is an example from the
6402 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
6403 class:
6404 <literallayout class='monospaced'>
6405 IMAGE_TYPEDEP_live = "ext3"
6406 </literallayout>
6407 </para>
6408
6409 <para>
6410 In the previous example, the variable ensures that when
6411 "live" is listed with the
6412 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6413 variable, the OpenEmbedded build system produces an
6414 <filename>ext3</filename> image first since one of the
6415 components of the live
6416 image is an <filename>ext3</filename>
6417 formatted partition containing the root
6418 filesystem.
6419 </para>
6420 </glossdef>
6421 </glossentry>
6422
6423 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
6424 <info>
6425 IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."
6426 </info>
6427 <glossdef>
6428 <para role="glossdeffirst">
6429 Specifies the complete list of supported image types
6430 by default:
6431 <literallayout class='monospaced'>
6432 btrfs
6433 container
6434 cpio
6435 cpio.gz
6436 cpio.lz4
6437 cpio.lzma
6438 cpio.xz
6439 cramfs
6440 ext2
6441 ext2.bz2
6442 ext2.gz
6443 ext2.lzma
6444 ext3
6445 ext3.gz
6446 ext4
6447 ext4.gz
6448 f2fs
6449 hddimg
6450 iso
6451 jffs2
6452 jffs2.sum
6453 multiubi
6454 squashfs
6455 squashfs-lz4
6456 squashfs-lzo
6457 squashfs-xz
6458 tar
6459 tar.bz2
6460 tar.gz
6461 tar.lz4
6462 tar.xz
6463 tar.zst
6464 ubi
6465 ubifs
6466 wic
6467 wic.bz2
6468 wic.gz
6469 wic.lzma
6470 </literallayout>
6471 </para>
6472
6473 <para>
6474 For more information about these types of images, see
6475 <filename>meta/classes/image_types*.bbclass</filename>
6476 in the
6477 <link linkend='source-directory'>Source Directory</link>.
6478 </para>
6479 </glossdef>
6480 </glossentry>
6481
6482 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
6483 <info>
6484 INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."
6485 </info>
6486 <glossdef>
6487 <para role="glossdeffirst">
6488 Helps define the recipe revision for recipes that share
6489 a common <filename>include</filename> file.
6490 You can think of this variable as part of the recipe revision
6491 as set from within an include file.
6492 </para>
6493
6494 <para>
6495 Suppose, for example, you have a set of recipes that
6496 are used across several projects.
6497 And, within each of those recipes the revision
6498 (its <link linkend='var-PR'><filename>PR</filename></link>
6499 value) is set accordingly.
6500 In this case, when the revision of those recipes changes,
6501 the burden is on you to find all those recipes and
6502 be sure that they get changed to reflect the updated
6503 version of the recipe.
6504 In this scenario, it can get complicated when recipes
6505 that are used in many places and provide common functionality
6506 are upgraded to a new revision.
6507 </para>
6508
6509 <para>
6510 A more efficient way of dealing with this situation is
6511 to set the <filename>INC_PR</filename> variable inside
6512 the <filename>include</filename> files that the recipes
6513 share and then expand the <filename>INC_PR</filename>
6514 variable within the recipes to help
6515 define the recipe revision.
6516 </para>
6517
6518 <para>
6519 The following provides an example that shows how to use
6520 the <filename>INC_PR</filename> variable
6521 given a common <filename>include</filename> file that
6522 defines the variable.
6523 Once the variable is defined in the
6524 <filename>include</filename> file, you can use the
6525 variable to set the <filename>PR</filename> values in
6526 each recipe.
6527 You will notice that when you set a recipe's
6528 <filename>PR</filename> you can provide more granular
6529 revisioning by appending values to the
6530 <filename>INC_PR</filename> variable:
6531 <literallayout class='monospaced'>
6532 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
6533 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
6534 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
6535 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
6536 </literallayout>
6537 The first line of the example establishes the baseline
6538 revision to be used for all recipes that use the
6539 <filename>include</filename> file.
6540 The remaining lines in the example are from individual
6541 recipes and show how the <filename>PR</filename> value
6542 is set.
6543 </para>
6544 </glossdef>
6545 </glossentry>
6546
6547 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
6548 <info>
6549 INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build."
6550 </info>
6551 <glossdef>
6552 <para role="glossdeffirst">
6553 Specifies a space-separated list of license names
6554 (as they would appear in
6555 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
6556 that should be excluded from the build.
6557 Recipes that provide no alternatives to listed incompatible
6558 licenses are not built.
6559 Packages that are individually licensed with the specified
6560 incompatible licenses will be deleted.
6561 </para>
6562
6563 <note>
6564 This functionality is only regularly tested using
6565 the following setting:
6566 <literallayout class='monospaced'>
6567 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
6568 </literallayout>
6569 Although you can use other settings, you might be required
6570 to remove dependencies on or provide alternatives to
6571 components that are required to produce a functional system
6572 image.
6573 </note>
6574
6575 <note><title>Tips</title>
6576 It is possible to define a list of licenses that are allowed
6577 to be used instead of the licenses that are excluded. To do
6578 this, define a
6579 variable <filename>COMPATIBLE_LICENSES</filename> with the
6580 names of the licences that are allowed. Then
6581 define <filename>INCOMPATIBLE_LICENSE</filename> as:
6582 <literallayout class='monospaced'>
6583 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
6584 </literallayout>
6585 This will result
6586 in <filename>INCOMPATIBLE_LICENSE</filename> containing the
6587 names of all licences
6588 from <link linkend='var-AVAILABLE_LICENSES'><filename>AVAILABLE_LICENSES</filename></link>
6589 except the ones specified
6590 in <filename>COMPATIBLE_LICENSES</filename>, thus only
6591 allowing the latter licences to be used.
6592 </note>
6593 </glossdef>
6594 </glossentry>
6595
6596 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
6597 <info>
6598 INHERIT[doc] = "Causes the named class or classes to be inherited globally."
6599 </info>
6600 <glossdef>
6601 <para role="glossdeffirst">
6602 Causes the named class or classes to be inherited globally.
6603 Anonymous functions in the class or classes
6604 are not executed for the
6605 base configuration and in each individual recipe.
6606 The OpenEmbedded build system ignores changes to
6607 <filename>INHERIT</filename> in individual recipes.
6608 </para>
6609
6610 <para>
6611 For more information on <filename>INHERIT</filename>, see
6612 the
6613 "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"
6614 section in the Bitbake User Manual.
6615 </para>
6616 </glossdef>
6617 </glossentry>
6618
6619 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
6620 <info>
6621 INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."
6622 </info>
6623 <glossdef>
6624 <para role="glossdeffirst">
6625 Lists classes that will be inherited at the
6626 distribution level.
6627 It is unlikely that you want to edit this variable.
6628 </para>
6629
6630 <para>
6631 The default value of the variable is set as follows in the
6632 <filename>meta/conf/distro/defaultsetup.conf</filename>
6633 file:
6634 <literallayout class='monospaced'>
6635 INHERIT_DISTRO ?= "debian devshell sstate license"
6636 </literallayout>
6637 </para>
6638 </glossdef>
6639 </glossentry>
6640
6641 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
6642 <info>
6643 INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."
6644 </info>
6645 <glossdef>
6646 <para role="glossdeffirst">
6647 Prevents the default dependencies, namely the C compiler
6648 and standard C library (libc), from being added to
6649 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
6650 This variable is usually used within recipes that do not
6651 require any compilation using the C compiler.
6652 </para>
6653
6654 <para>
6655 Set the variable to "1" to prevent the default dependencies
6656 from being added.
6657 </para>
6658 </glossdef>
6659 </glossentry>
6660
6661 <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm>
6662 <info>
6663 INHIBIT_PACKAGE_DEBUG_SPLIT[doc] = "If set to "1", prevents the OpenEmbedded build system from splitting out debug information during packaging"
6664 </info>
6665 <glossdef>
6666 <para role="glossdeffirst">
6667 Prevents the OpenEmbedded build system from splitting
6668 out debug information during packaging.
6669 By default, the build system splits out debugging
6670 information during the
6671 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
6672 task.
6673 For more information on how debug information is split out,
6674 see the
6675 <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link>
6676 variable.
6677 </para>
6678
6679 <para>
6680 To prevent the build system from splitting out
6681 debug information during packaging, set the
6682 <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable
6683 as follows:
6684 <literallayout class='monospaced'>
6685 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
6686 </literallayout>
6687 </para>
6688 </glossdef>
6689 </glossentry>
6690
6691 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
6692 <info>
6693 INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."
6694 </info>
6695 <glossdef>
6696 <para role="glossdeffirst">
6697 If set to "1", causes the build to not strip binaries in
6698 resulting packages and prevents the
6699 <filename>-dbg</filename> package from containing the
6700 source files.
6701 </para>
6702
6703 <para>
6704 By default, the OpenEmbedded build system strips
6705 binaries and puts the debugging symbols into
6706 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.
6707 Consequently, you should not set
6708 <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan
6709 to debug in general.
6710 </para>
6711 </glossdef>
6712 </glossentry>
6713
6714 <glossentry id='var-INHIBIT_SYSROOT_STRIP'><glossterm>INHIBIT_SYSROOT_STRIP</glossterm>
6715 <info>
6716 INHIBIT_SYSROOT_STRIP[doc] = "If set to "1", causes the build to not strip binaries in the resulting sysroot."
6717 </info>
6718 <glossdef>
6719 <para role="glossdeffirst">
6720 If set to "1", causes the build to not strip binaries in
6721 the resulting sysroot.
6722 </para>
6723
6724 <para>
6725 By default, the OpenEmbedded build system strips
6726 binaries in the resulting sysroot.
6727 When you specifically set the
6728 <filename>INHIBIT_SYSROOT_STRIP</filename> variable to
6729 "1" in your recipe, you inhibit this stripping.
6730 </para>
6731
6732 <para>
6733 If you want to use this variable, include the
6734 <link linkend='ref-classes-staging'><filename>staging</filename></link>
6735 class.
6736 This class uses a <filename>sys_strip()</filename>
6737 function to test for the variable and acts accordingly.
6738 <note>
6739 Use of the <filename>INHIBIT_SYSROOT_STRIP</filename>
6740 variable occurs in rare and special circumstances.
6741 For example, suppose you are building bare-metal
6742 firmware by using an external GCC toolchain.
6743 Furthermore, even if the toolchain's binaries are
6744 strippable, other files exist that are needed for the
6745 build that are not strippable.
6746 </note>
6747 </para>
6748 </glossdef>
6749 </glossentry>
6750
6751 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
6752 <info>
6753 INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM filesystem (initramfs), which is used during boot."
6754 </info>
6755 <glossdef>
6756 <para role="glossdeffirst">
6757 Defines the format for the output image of an initial
6758 RAM filesystem (initramfs), which is used during boot.
6759 Supported formats are the same as those supported by the
6760 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6761 variable.
6762 </para>
6763
6764 <para>
6765 The default value of this variable, which is set in the
6766 <filename>meta/conf/bitbake.conf</filename> configuration
6767 file in the
6768 <link linkend='source-directory'>Source Directory</link>,
6769 is "cpio.gz".
6770 The Linux kernel's initramfs mechanism, as opposed to the
6771 initial RAM filesystem
6772 <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
6773 mechanism, expects an optionally compressed cpio
6774 archive.
6775 </para>
6776 </glossdef>
6777 </glossentry>
6778
6779 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
6780 <info>
6781 INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM filesystem (initramfs) image."
6782 </info>
6783 <glossdef>
6784 <para role="glossdeffirst">
6785 Specifies the
6786 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
6787 name of an image recipe that is used to build an initial
6788 RAM filesystem (initramfs) image.
6789 In other words, the <filename>INITRAMFS_IMAGE</filename>
6790 variable causes an additional recipe to be built as
6791 a dependency to whatever root filesystem recipe you
6792 might be using (e.g. <filename>core-image-sato</filename>).
6793 The initramfs image recipe you provide should set
6794 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6795 to
6796 <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>.
6797 </para>
6798
6799 <para>
6800 An initramfs image provides a temporary root filesystem
6801 used for early system initialization (e.g. loading of
6802 modules needed to locate and mount the "real" root
6803 filesystem).
6804 <note>
6805 See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>
6806 recipe in the
6807 <link linkend='source-directory'>Source Directory</link>
6808 for an example initramfs recipe.
6809 To select this sample recipe as the one built
6810 to provide the initramfs image,
6811 set <filename>INITRAMFS_IMAGE</filename> to
6812 "core-image-minimal-initramfs".
6813 </note>
6814 </para>
6815
6816 <para>
6817 You can also find more information by referencing the
6818 <filename>meta-poky/conf/local.conf.sample.extended</filename>
6819 configuration file in the Source Directory,
6820 the
6821 <link linkend='ref-classes-image'><filename>image</filename></link>
6822 class, and the
6823 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
6824 class to see how to use the
6825 <filename>INITRAMFS_IMAGE</filename> variable.
6826 </para>
6827
6828 <para>
6829 If <filename>INITRAMFS_IMAGE</filename> is empty, which is
6830 the default, then no initramfs image is built.
6831 </para>
6832
6833 <para>
6834 For more information, you can also see the
6835 <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
6836 variable, which allows the generated image to be bundled
6837 inside the kernel image.
6838 Additionally, for information on creating an initramfs
6839 image, see the
6840 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
6841 section in the Yocto Project Development Tasks Manual.
6842 </para>
6843 </glossdef>
6844 </glossentry>
6845
6846 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
6847 <info>
6848 INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass (do_bundle_initramfs) during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM filesystem (initramfs)."
6849 </info>
6850 <glossdef>
6851 <para role="glossdeffirst">
6852 Controls whether or not the image recipe specified by
6853 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
6854 is run through an extra pass
6855 (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
6856 during kernel compilation in order to build a single binary
6857 that contains both the kernel image and the initial RAM
6858 filesystem (initramfs) image.
6859 This makes use of the
6860 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
6861 kernel feature.
6862 <note>
6863 Using an extra compilation pass to bundle the initramfs
6864 avoids a circular dependency between the kernel recipe and
6865 the initramfs recipe should the initramfs include kernel
6866 modules.
6867 Should that be the case, the initramfs recipe depends on
6868 the kernel for the kernel modules, and the kernel depends
6869 on the initramfs recipe since the initramfs is bundled
6870 inside the kernel image.
6871 </note>
6872 </para>
6873
6874 <para>
6875 The combined binary is deposited into the
6876 <filename>tmp/deploy</filename> directory, which is part
6877 of the
6878 <link linkend='build-directory'>Build Directory</link>.
6879 </para>
6880
6881 <para>
6882 Setting the variable to "1" in a configuration file causes the
6883 OpenEmbedded build system to generate a kernel image with the
6884 initramfs specified in <filename>INITRAMFS_IMAGE</filename>
6885 bundled within:
6886 <literallayout class='monospaced'>
6887 INITRAMFS_IMAGE_BUNDLE = "1"
6888 </literallayout>
6889 By default, the
6890 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
6891 class sets this variable to a null string as follows:
6892 <literallayout class='monospaced'>
6893 INITRAMFS_IMAGE_BUNDLE ?= ""
6894 </literallayout>
6895 <note>
6896 You must set the
6897 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
6898 a configuration file.
6899 You cannot set the variable in a recipe file.
6900 </note>
6901 See the
6902 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
6903 file for additional information.
6904 Also, for information on creating an initramfs, see the
6905 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
6906 section in the Yocto Project Development Tasks Manual.
6907 </para>
6908 </glossdef>
6909 </glossentry>
6910
6911 <glossentry id='var-INITRAMFS_LINK_NAME'><glossterm>INITRAMFS_LINK_NAME</glossterm>
6912 <info>
6913 INITRAMFS_LINK_NAME[doc] = "The link name of the initial RAM filesystem image."
6914 </info>
6915 <glossdef>
6916 <para role="glossdeffirst">
6917 The link name of the initial RAM filesystem image.
6918 This variable is set in the
6919 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
6920 file as follows:
6921 <literallayout class='monospaced'>
6922 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
6923 </literallayout>
6924 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
6925 variable, which is set in the same file, has the following
6926 value:
6927 <literallayout class='monospaced'>
6928 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
6929 </literallayout>
6930 </para>
6931
6932 <para>
6933 See the
6934 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
6935 variable for additional information.
6936 </para>
6937 </glossdef>
6938 </glossentry>
6939
6940 <glossentry id='var-INITRAMFS_NAME'><glossterm>INITRAMFS_NAME</glossterm>
6941 <info>
6942 INITRAMFS_NAME[doc] = "The base name of the initial RAM filesystem image."
6943 </info>
6944 <glossdef>
6945 <para role="glossdeffirst">
6946 The base name of the initial RAM filesystem image.
6947 This variable is set in the
6948 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
6949 file as follows:
6950 <literallayout class='monospaced'>
6951 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
6952 </literallayout>
6953 The value of the
6954 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
6955 variable, which is set in the same file, has the following
6956 value:
6957 <literallayout class='monospaced'>
6958 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
6959 </literallayout>
6960 </para>
6961 </glossdef>
6962 </glossentry>
6963
6964 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
6965 <info>
6966 INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."
6967 </info>
6968 <glossdef>
6969 <para role="glossdeffirst">
6970 Indicates list of filesystem images to concatenate and use
6971 as an initial RAM disk (<filename>initrd</filename>).
6972 </para>
6973
6974 <para>
6975 The <filename>INITRD</filename> variable is an optional
6976 variable used with the
6977 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
6978 class.
6979 </para>
6980 </glossdef>
6981 </glossentry>
6982
6983 <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>
6984 <info>
6985 INITRD_IMAGE[doc] = "When building a "live" bootable image (i.e. when IMAGE_FSTYPES contains "live"), INITRD_IMAGE specifies the image recipe that should be built to provide the initial RAM disk image."
6986 </info>
6987 <glossdef>
6988 <para role="glossdeffirst">
6989 When building a "live" bootable image (i.e. when
6990 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6991 contains "live"), <filename>INITRD_IMAGE</filename>
6992 specifies the image recipe that should be built
6993 to provide the initial RAM disk image.
6994 The default value is "core-image-minimal-initramfs".
6995 </para>
6996
6997 <para>
6998 See the
6999 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
7000 class for more information.
7001 </para>
7002 </glossdef>
7003 </glossentry>
7004
7005 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
7006 <info>
7007 INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."
7008 </info>
7009 <glossdef>
7010 <para role="glossdeffirst">
7011 The filename of the initialization script as installed to
7012 <filename>${sysconfdir}/init.d</filename>.
7013 </para>
7014
7015 <para>
7016 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7017 The variable is mandatory.
7018 </para>
7019 </glossdef>
7020 </glossentry>
7021
7022 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
7023 <info>
7024 INITSCRIPT_PACKAGES[doc] = "A list of the packages that contain initscripts. This variable is used in recipes when using update-rc.d.bbclass. The variable is optional and defaults to the PN variable."
7025 </info>
7026 <glossdef>
7027 <para role="glossdeffirst">
7028 A list of the packages that contain initscripts.
7029 If multiple packages are specified, you need to append the package name
7030 to the other <filename>INITSCRIPT_*</filename> as an override.
7031 </para>
7032
7033 <para>
7034 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7035 The variable is optional and defaults to the
7036 <link linkend='var-PN'><filename>PN</filename></link> variable.
7037 </para>
7038 </glossdef>
7039 </glossentry>
7040
7041 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
7042 <info>
7043 INITSCRIPT_PARAMS[doc] = "Specifies the options to pass to update-rc.d. The variable is mandatory and is used in recipes when using update-rc.d.bbclass."
7044 </info>
7045 <glossdef>
7046 <para role="glossdeffirst">
7047 Specifies the options to pass to <filename>update-rc.d</filename>.
7048 Here is an example:
7049 <literallayout class='monospaced'>
7050 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
7051 </literallayout>
7052 </para>
7053
7054 <para>
7055 In this example, the script has a runlevel of 99,
7056 starts the script in initlevels 2 and 5, and
7057 stops the script in levels 0, 1 and 6.
7058 </para>
7059
7060 <para>
7061 The variable's default value is "defaults", which is
7062 set in the
7063 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
7064 class.
7065 </para>
7066
7067 <para>
7068 The value in
7069 <filename>INITSCRIPT_PARAMS</filename> is passed through
7070 to the <filename>update-rc.d</filename> command.
7071 For more information on valid parameters, please see the
7072 <filename>update-rc.d</filename> manual page at
7073 <ulink url='http://www.tin.org/bin/man.cgi?section=8&amp;topic=update-rc.d'></ulink>.
7074 </para>
7075 </glossdef>
7076 </glossentry>
7077
7078 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
7079 <info>
7080 INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."
7081 </info>
7082 <glossdef>
7083 <para role="glossdeffirst">
7084 Specifies the QA checks to skip for a specific package
7085 within a recipe.
7086 For example, to skip the check for symbolic link
7087 <filename>.so</filename> files in the main package of a
7088 recipe, add the following to the recipe.
7089 The package name override must be used, which in this
7090 example is <filename>${PN}</filename>:
7091 <literallayout class='monospaced'>
7092 INSANE_SKIP_${PN} += "dev-so"
7093 </literallayout>
7094 </para>
7095
7096 <para>
7097 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
7098 section for a list of the valid QA checks you can
7099 specify using this variable.
7100 </para>
7101 </glossdef>
7102 </glossentry>
7103
7104 <glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>
7105 <info>
7106 INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."
7107 </info>
7108 <glossdef>
7109 <para role="glossdeffirst">
7110 By default, the <filename>tzdata</filename> recipe packages
7111 an <filename>/etc/timezone</filename> file.
7112 Set the <filename>INSTALL_TIMEZONE_FILE</filename>
7113 variable to "0" at the configuration level to disable this
7114 behavior.
7115 </para>
7116 </glossdef>
7117 </glossentry>
7118
7119 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
7120 <info>
7121 IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."
7122 </info>
7123 <glossdef>
7124 <para role="glossdeffirst">
7125 When the IPK backend is in use and package management
7126 is enabled on the target, you can use this variable to
7127 set up <filename>opkg</filename> in the target image
7128 to point to package feeds on a nominated server.
7129 Once the feed is established, you can perform
7130 installations or upgrades using the package manager
7131 at runtime.
7132 </para>
7133 </glossdef>
7134 </glossentry>
7135
7136<!--
7137 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
7138 <glossdef>
7139 <para>
7140 An environment variable that defines the directory where
7141 post installation hooks are installed for the
7142 post install environment.
7143 This variable is fixed as follows:
7144 <literallayout class='monospaced'>
7145 ${WORKDIR}/intercept_scripts
7146 </literallayout>
7147 </para>
7148
7149 <para>
7150 After installation of a target's root filesystem,
7151 post installation scripts, which are essentially bash scripts,
7152 are all executed just a single time.
7153 Limiting execution of these scripts minimizes installation
7154 time that would be lengthened due to certain packages
7155 triggering redundant operations.
7156 For example, consider the installation of font packages
7157 as a common example.
7158 Without limiting the execution of post installation scripts,
7159 all font directories would be rescanned to create the
7160 cache after each individual font package was installed.
7161 </para>
7162
7163 <para>
7164 Do not edit the <filename>INTERCEPT_DIR</filename>
7165 variable.
7166 </para>
7167 </glossdef>
7168 </glossentry>
7169-->
7170
7171 </glossdiv>
7172
7173<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
7174<!-- </glossdiv>-->
7175
7176 <glossdiv id='var-glossary-k'><title>K</title>
7177
7178 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
7179 <info>
7180 KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."
7181 </info>
7182 <glossdef>
7183 <para role="glossdeffirst">
7184 Defines the kernel architecture used when assembling
7185 the configuration.
7186 Architectures supported for this release are:
7187 <literallayout class='monospaced'>
7188 powerpc
7189 i386
7190 x86_64
7191 arm
7192 qemu
7193 mips
7194 </literallayout>
7195 </para>
7196
7197 <para>
7198 You define the <filename>KARCH</filename> variable in the
7199 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
7200 </para>
7201 </glossdef>
7202 </glossentry>
7203
7204 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
7205 <info>
7206 KBRANCH[doc] = "A regular expression used by the build process to explicitly identify the kernel branch that is validated, patched, and configured during a build."
7207 </info>
7208 <glossdef>
7209 <para role="glossdeffirst">
7210 A regular expression used by the build process to explicitly
7211 identify the kernel branch that is validated, patched,
7212 and configured during a build.
7213 You must set this variable to ensure the exact kernel
7214 branch you want is being used by the build process.
7215 </para>
7216
7217 <para>
7218 Values for this variable are set in the kernel's recipe
7219 file and the kernel's append file.
7220 For example, if you are using the
7221 <filename>linux-yocto_4.12</filename> kernel, the kernel
7222 recipe file is the
7223 <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
7224 file.
7225 <filename>KBRANCH</filename> is set as follows in that
7226 kernel recipe file:
7227 <literallayout class='monospaced'>
7228 KBRANCH ?= "standard/base"
7229 </literallayout>
7230 </para>
7231
7232 <para>
7233 This variable is also used from the kernel's append file
7234 to identify the kernel branch specific to a particular
7235 machine or target hardware.
7236 Continuing with the previous kernel example, the kernel's
7237 append file (i.e.
7238 <filename>linux-yocto_4.12.bbappend</filename>) is located
7239 in the BSP layer for a given machine.
7240 For example, the append file for the Beaglebone,
7241 EdgeRouter, and generic versions of both 32 and 64-bit IA
7242 machines (<filename>meta-yocto-bsp</filename>) is named
7243 <filename>meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend</filename>.
7244 Here are the related statements from that append file:
7245 <literallayout class='monospaced'>
7246 KBRANCH_genericx86 = "standard/base"
7247 KBRANCH_genericx86-64 = "standard/base"
7248 KBRANCH_edgerouter = "standard/edgerouter"
7249 KBRANCH_beaglebone = "standard/beaglebone"
7250 </literallayout>
7251 The <filename>KBRANCH</filename> statements identify
7252 the kernel branch to use when building for each
7253 supported BSP.
7254 </para>
7255 </glossdef>
7256 </glossentry>
7257
7258 <glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>
7259 <info>
7260 KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."
7261 </info>
7262 <glossdef>
7263 <para role="glossdeffirst">
7264 When used with the
7265 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
7266 class, specifies an "in-tree" kernel configuration file
7267 for use during a kernel build.
7268 </para>
7269
7270 <para>
7271 Typically, when using a <filename>defconfig</filename> to
7272 configure a kernel during a build, you place the
7273 file in your layer in the same manner as you would
7274 place patch files and configuration fragment files (i.e.
7275 "out-of-tree").
7276 However, if you want to use a <filename>defconfig</filename>
7277 file that is part of the kernel tree (i.e. "in-tree"),
7278 you can use the
7279 <filename>KBUILD_DEFCONFIG</filename> variable and append
7280 the
7281 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
7282 variable to point to the <filename>defconfig</filename>
7283 file.
7284 </para>
7285
7286 <para>
7287 To use the variable, set it in the append file for your
7288 kernel recipe using the following form:
7289 <literallayout class='monospaced'>
7290 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
7291 </literallayout>
7292 Here is an example from a "raspberrypi2"
7293 <filename>KMACHINE</filename> build that uses a
7294 <filename>defconfig</filename> file named
7295 "bcm2709_defconfig":
7296 <literallayout class='monospaced'>
7297 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"
7298 </literallayout>
7299 As an alternative, you can use the following within your
7300 append file:
7301 <literallayout class='monospaced'>
7302 KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>
7303 </literallayout>
7304 For more information on how to use the
7305 <filename>KBUILD_DEFCONFIG</filename> variable, see the
7306 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file'>Using an "In-Tree" <filename>defconfig</filename> File</ulink>"
7307 section in the Yocto Project Linux Kernel Development
7308 Manual.
7309 </para>
7310 </glossdef>
7311 </glossentry>
7312
7313 <glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>
7314 <info>
7315 KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."
7316 </info>
7317 <glossdef>
7318 <para role="glossdeffirst">
7319 Specifies an alternate kernel image type for creation in
7320 addition to the kernel image type specified using the
7321 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
7322 variable.
7323 </para>
7324 </glossdef>
7325 </glossentry>
7326
7327 <glossentry id='var-KERNEL_ARTIFACT_NAME'><glossterm>KERNEL_ARTIFACT_NAME</glossterm>
7328 <info>
7329 KERNEL_ARTIFACT_NAME[doc] = "Specifies the name of all of the build artifacts."
7330 </info>
7331 <glossdef>
7332 <para role="glossdeffirst">
7333 Specifies the name of all of the build artifacts.
7334 You can change the name of the artifacts by changing the
7335 <filename>KERNEL_ARTIFACT_NAME</filename> variable.
7336 </para>
7337
7338 <para>
7339 The value of <filename>KERNEL_ARTIFACT_NAME</filename>,
7340 which is set in the
7341 <filename> meta/classes/kernel-artifact-names.bbclass</filename>
7342 file, has the following default value:
7343 <literallayout class='monospaced'>
7344 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7345 </literallayout>
7346 </para>
7347
7348 <para>
7349 See the
7350 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
7351 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
7352 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
7353 and
7354 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7355 variables for additional information.
7356 <note>
7357 The <filename>IMAGE_VERSION_SUFFIX</filename> variable
7358 is set to
7359 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
7360 </note>
7361 </para>
7362 </glossdef>
7363 </glossentry>
7364
7365 <glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>
7366 <info>
7367 KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."
7368 </info>
7369 <glossdef>
7370 <para role="glossdeffirst">
7371 A list of classes defining kernel image types that the
7372 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7373 class should inherit.
7374 You typically append this variable to enable extended image
7375 types.
7376 An example is the "kernel-fitimage", which enables
7377 fitImage support and resides in
7378 <filename>meta/classes/kernel-fitimage.bbclass</filename>.
7379 You can register custom kernel image types with the
7380 <filename>kernel</filename> class using this variable.
7381 </para>
7382 </glossdef>
7383 </glossentry>
7384
7385 <glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>
7386 <info>
7387 KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the .dtb) file."
7388 </info>
7389 <glossdef>
7390 <para role="glossdeffirst">
7391 Specifies the name of the generated Linux kernel device tree
7392 (i.e. the <filename>.dtb</filename>) file.
7393 <note>
7394 Legacy support exists for specifying the full path
7395 to the device tree.
7396 However, providing just the <filename>.dtb</filename>
7397 file is preferred.
7398 </note>
7399 In order to use this variable, the
7400 <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link>
7401 class must be inherited.
7402 </para>
7403 </glossdef>
7404 </glossentry>
7405
7406 <glossentry id='var-KERNEL_DTB_LINK_NAME'><glossterm>KERNEL_DTB_LINK_NAME</glossterm>
7407 <info>
7408 KERNEL_DTB_LINK_NAME[doc] = "The link name of the kernel device tree binary (DTB)."
7409 </info>
7410 <glossdef>
7411 <para role="glossdeffirst">
7412 The link name of the kernel device tree binary (DTB).
7413 This variable is set in the
7414 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7415 file as follows:
7416 <literallayout class='monospaced'>
7417 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7418 </literallayout>
7419 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7420 variable, which is set in the same file, has the following
7421 value:
7422 <literallayout class='monospaced'>
7423 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7424 </literallayout>
7425 </para>
7426
7427 <para>
7428 See the
7429 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7430 variable for additional information.
7431 </para>
7432 </glossdef>
7433 </glossentry>
7434
7435 <glossentry id='var-KERNEL_DTB_NAME'><glossterm>KERNEL_DTB_NAME</glossterm>
7436 <info>
7437 KERNEL_DTB_NAME[doc] = "The base name of the kernel device tree binary (DTB)."
7438 </info>
7439 <glossdef>
7440 <para role="glossdeffirst">
7441 The base name of the kernel device tree binary (DTB).
7442 This variable is set in the
7443 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7444 file as follows:
7445 <literallayout class='monospaced'>
7446 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7447 </literallayout>
7448 The value of the
7449 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7450 variable, which is set in the same file, has the following
7451 value:
7452 <literallayout class='monospaced'>
7453 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7454 </literallayout>
7455 </para>
7456 </glossdef>
7457 </glossentry>
7458
7459 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
7460 <info>
7461 KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."
7462 </info>
7463 <glossdef>
7464 <para role="glossdeffirst">
7465 Specifies additional <filename>make</filename>
7466 command-line arguments the OpenEmbedded build system
7467 passes on when compiling the kernel.
7468 </para>
7469 </glossdef>
7470 </glossentry>
7471
7472 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
7473 <info>
7474 KERNEL_FEATURES[doc] = "Includes additional kernel metadata. The metadata you add through this variable includes config fragments and features descriptions."
7475 </info>
7476 <glossdef>
7477 <para role="glossdeffirst">
7478 Includes additional kernel metadata.
7479 In the OpenEmbedded build system, the default Board Support
7480 Packages (BSPs)
7481 <link linkend='metadata'>Metadata</link>
7482 is provided through
7483 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
7484 and
7485 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
7486 variables.
7487 You can use the <filename>KERNEL_FEATURES</filename>
7488 variable from within the kernel recipe or kernel append
7489 file to further add metadata for all BSPs or specific
7490 BSPs.
7491 </para>
7492
7493 <para>
7494 The metadata you add through this variable includes config
7495 fragments and features descriptions,
7496 which usually includes patches as well as config fragments.
7497 You typically override the
7498 <filename>KERNEL_FEATURES</filename> variable for a
7499 specific machine.
7500 In this way, you can provide validated, but optional,
7501 sets of kernel configurations and features.
7502 </para>
7503
7504 <para>
7505 For example, the following example from the
7506 <filename>linux-yocto-rt_4.12</filename> kernel recipe
7507 adds "netfilter" and "taskstats" features to all BSPs
7508 as well as "virtio" configurations to all QEMU machines.
7509 The last two statements add specific configurations to
7510 targeted machine types:
7511 <literallayout class='monospaced'>
7512 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
7513 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
7514 KERNEL_FEATURES_append_qemuall = " cfg/virtio.scc"
7515 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
7516 KERNEL_FEATURES_append_qemux86-64 = " cfg/sound.scc" </literallayout></para>
7517 </glossdef>
7518 </glossentry>
7519
7520 <glossentry id='var-KERNEL_FIT_LINK_NAME'><glossterm>KERNEL_FIT_LINK_NAME</glossterm>
7521 <info>
7522 KERNEL_FIT_LINK_NAME[doc] = "The link name of the kernel flattened image tree (FIT) image."
7523 </info>
7524 <glossdef>
7525 <para role="glossdeffirst">
7526 The link name of the kernel flattened image tree (FIT) image.
7527 This variable is set in the
7528 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7529 file as follows:
7530 <literallayout class='monospaced'>
7531 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7532 </literallayout>
7533 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7534 variable, which is set in the same file, has the following
7535 value:
7536 <literallayout class='monospaced'>
7537 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7538 </literallayout>
7539 </para>
7540
7541 <para>
7542 See the
7543 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7544 variable for additional information.
7545 </para>
7546 </glossdef>
7547 </glossentry>
7548
7549 <glossentry id='var-KERNEL_FIT_NAME'><glossterm>KERNEL_FIT_NAME</glossterm>
7550 <info>
7551 KERNEL_FIT_NAME[doc] = "The base name of the kernel flattened image tree (FIT) image."
7552 </info>
7553 <glossdef>
7554 <para role="glossdeffirst">
7555 The base name of the kernel flattened image tree (FIT) image.
7556 This variable is set in the
7557 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7558 file as follows:
7559 <literallayout class='monospaced'>
7560 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7561 </literallayout>
7562 The value of the
7563 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7564 variable, which is set in the same file, has the following
7565 value:
7566 <literallayout class='monospaced'>
7567 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7568 </literallayout>
7569 </para>
7570 </glossdef>
7571 </glossentry>
7572
7573 <glossentry id='var-KERNEL_IMAGE_LINK_NAME'><glossterm>KERNEL_IMAGE_LINK_NAME</glossterm>
7574 <info>
7575 KERNEL_IMAGE_LINK_NAME[doc] = "The link name for the kernel image."
7576 </info>
7577 <glossdef>
7578 <para role="glossdeffirst">
7579 The link name for the kernel image.
7580 This variable is set in the
7581 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7582 file as follows:
7583 <literallayout class='monospaced'>
7584 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7585 </literallayout>
7586 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7587 variable, which is set in the same file, has the following
7588 value:
7589 <literallayout class='monospaced'>
7590 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7591 </literallayout>
7592 </para>
7593
7594 <para>
7595 See the
7596 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7597 variable for additional information.
7598 </para>
7599 </glossdef>
7600 </glossentry>
7601
7602 <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm>
7603 <info>
7604 KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."
7605 </info>
7606 <glossdef>
7607 <para role="glossdeffirst">
7608 Specifies the maximum size of the kernel image file in
7609 kilobytes.
7610 If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,
7611 the size of the kernel image file is checked against
7612 the set value during the
7613 <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link>
7614 task.
7615 The task fails if the kernel image file is larger than
7616 the setting.
7617 </para>
7618
7619 <para>
7620 <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for
7621 target devices that have a limited amount of space in
7622 which the kernel image must be stored.
7623 </para>
7624
7625 <para>
7626 By default, this variable is not set, which means the
7627 size of the kernel image is not checked.
7628 </para>
7629 </glossdef>
7630 </glossentry>
7631
7632 <glossentry id='var-KERNEL_IMAGE_NAME'><glossterm>KERNEL_IMAGE_NAME</glossterm>
7633 <info>
7634 KERNEL_IMAGE_NAME[doc] = "The base name of the kernel image."
7635 </info>
7636 <glossdef>
7637 <para role="glossdeffirst">
7638 The base name of the kernel image.
7639 This variable is set in the
7640 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7641 file as follows:
7642 <literallayout class='monospaced'>
7643 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7644 </literallayout>
7645 The value of the
7646 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7647 variable, which is set in the same file, has the following
7648 value:
7649 <literallayout class='monospaced'>
7650 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7651 </literallayout>
7652 </para>
7653 </glossdef>
7654 </glossentry>
7655
7656 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
7657 <info>
7658 KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."
7659 </info>
7660 <glossdef>
7661 <para role="glossdeffirst">
7662 The type of kernel to build for a device, usually set by the
7663 machine configuration files and defaults to "zImage".
7664 This variable is used
7665 when building the kernel and is passed to <filename>make</filename> as the target to
7666 build.
7667 </para>
7668
7669 <para>
7670 If you want to build an alternate kernel image type, use the
7671 <link linkend='var-KERNEL_ALT_IMAGETYPE'><filename>KERNEL_ALT_IMAGETYPE</filename></link>
7672 variable.
7673 </para>
7674 </glossdef>
7675 </glossentry>
7676
7677 <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm>
7678 <info>
7679 KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"
7680 </info>
7681 <glossdef>
7682 <para role="glossdeffirst">
7683 Lists kernel modules that need to be auto-loaded during
7684 boot.
7685 <note>
7686 This variable replaces the deprecated
7687 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
7688 variable.
7689 </note>
7690 </para>
7691
7692 <para>
7693 You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>
7694 variable anywhere that it can be
7695 recognized by the kernel recipe or by an out-of-tree kernel
7696 module recipe (e.g. a machine configuration file, a
7697 distribution configuration file, an append file for the
7698 recipe, or the recipe itself).
7699 </para>
7700
7701 <para>
7702 Specify it as follows:
7703 <literallayout class='monospaced'>
7704 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>"
7705 </literallayout>
7706 </para>
7707
7708 <para>
7709 Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes
7710 the OpenEmbedded build system to populate the
7711 <filename>/etc/modules-load.d/modname.conf</filename>
7712 file with the list of modules to be auto-loaded on boot.
7713 The modules appear one-per-line in the file.
7714 Here is an example of the most common use case:
7715 <literallayout class='monospaced'>
7716 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"
7717 </literallayout>
7718 </para>
7719
7720 <para>
7721 For information on how to populate the
7722 <filename>modname.conf</filename> file with
7723 <filename>modprobe.d</filename> syntax lines, see the
7724 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
7725 variable.
7726 </para>
7727 </glossdef>
7728 </glossentry>
7729
7730 <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
7731 <info>
7732 KERNEL_MODULE_PROBECONF[doc] = "Lists kernel modules for which the build system expects to find module_conf_* values that specify configuration for each of the modules."
7733 </info>
7734 <glossdef>
7735 <para role="glossdeffirst">
7736 Provides a list of modules for which the OpenEmbedded
7737 build system expects to find
7738 <filename>module_conf_</filename><replaceable>modname</replaceable>
7739 values that specify configuration for each of the modules.
7740 For information on how to provide those module
7741 configurations, see the
7742 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
7743 variable.
7744 </para>
7745 </glossdef>
7746 </glossentry>
7747
7748 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
7749 <info>
7750 KERNEL_PATH[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)."
7751 </info>
7752 <glossdef>
7753 <para role="glossdeffirst">
7754 The location of the kernel sources.
7755 This variable is set to the value of the
7756 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7757 within the
7758 <link linkend='ref-classes-module'><filename>module</filename></link>
7759 class.
7760 For information on how this variable is used, see the
7761 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
7762 section in the Yocto Project Linux Kernel Development
7763 Manual.
7764 </para>
7765
7766 <para>
7767 To help maximize compatibility with out-of-tree drivers
7768 used to build modules, the OpenEmbedded build system also
7769 recognizes and uses the
7770 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
7771 variable, which is identical to the
7772 <filename>KERNEL_PATH</filename> variable.
7773 Both variables are common variables used by external
7774 Makefiles to point to the kernel source directory.
7775 </para>
7776 </glossdef>
7777 </glossentry>
7778
7779 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
7780 <info>
7781 KERNEL_SRC[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)."
7782 </info>
7783 <glossdef>
7784 <para role="glossdeffirst">
7785 The location of the kernel sources.
7786 This variable is set to the value of the
7787 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7788 within the
7789 <link linkend='ref-classes-module'><filename>module</filename></link>
7790 class.
7791 For information on how this variable is used, see the
7792 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
7793 section in the Yocto Project Linux Kernel Development
7794 Manual.
7795 </para>
7796
7797 <para>
7798 To help maximize compatibility with out-of-tree drivers
7799 used to build modules, the OpenEmbedded build system also
7800 recognizes and uses the
7801 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
7802 variable, which is identical to the
7803 <filename>KERNEL_SRC</filename> variable.
7804 Both variables are common variables used by external
7805 Makefiles to point to the kernel source directory.
7806 </para>
7807 </glossdef>
7808 </glossentry>
7809
7810 <glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>
7811 <info>
7812 KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."
7813 </info>
7814 <glossdef>
7815 <para role="glossdeffirst">
7816 Specifies the version of the kernel as extracted from
7817 <filename>version.h</filename> or
7818 <filename>utsrelease.h</filename> within the kernel sources.
7819 Effects of setting this variable do not take affect until
7820 the kernel has been configured.
7821 Consequently, attempting to refer to this variable in
7822 contexts prior to configuration will not work.
7823 </para>
7824 </glossdef>
7825 </glossentry>
7826
7827 <glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>
7828 <info>
7829 KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."
7830 </info>
7831 <glossdef>
7832 <para role="glossdeffirst">
7833 Specifies whether the data referenced through
7834 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
7835 is needed or not.
7836 The <filename>KERNELDEPMODDEPEND</filename> does not
7837 control whether or not that data exists,
7838 but simply whether or not it is used.
7839 If you do not need to use the data, set the
7840 <filename>KERNELDEPMODDEPEND</filename> variable in your
7841 <filename>initramfs</filename> recipe.
7842 Setting the variable there when the data is not needed
7843 avoids a potential dependency loop.
7844 </para>
7845 </glossdef>
7846 </glossentry>
7847
7848 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
7849 <info>
7850 KFEATURE_DESCRIPTION[doc] = "Provides a short description of a configuration fragment. You use this variable in the .scc file that describes a configuration fragment file."
7851 </info>
7852 <glossdef>
7853 <para role="glossdeffirst">
7854 Provides a short description of a configuration fragment.
7855 You use this variable in the <filename>.scc</filename>
7856 file that describes a configuration fragment file.
7857 Here is the variable used in a file named
7858 <filename>smp.scc</filename> to describe SMP being
7859 enabled:
7860 <literallayout class='monospaced'>
7861 define KFEATURE_DESCRIPTION "Enable SMP"
7862 </literallayout>
7863 </para>
7864 </glossdef>
7865 </glossentry>
7866
7867 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
7868 <info>
7869 KMACHINE[doc] = "The machine as known by the kernel."
7870 </info>
7871 <glossdef>
7872 <para role="glossdeffirst">
7873 The machine as known by the kernel.
7874 Sometimes the machine name used by the kernel does not
7875 match the machine name used by the OpenEmbedded build
7876 system.
7877 For example, the machine name that the OpenEmbedded build
7878 system understands as
7879 <filename>core2-32-intel-common</filename> goes by a
7880 different name in the Linux Yocto kernel.
7881 The kernel understands that machine as
7882 <filename>intel-core2-32</filename>.
7883 For cases like these, the <filename>KMACHINE</filename>
7884 variable maps the kernel machine name to the OpenEmbedded
7885 build system machine name.
7886 </para>
7887
7888 <para>
7889 These mappings between different names occur in the
7890 Yocto Linux Kernel's <filename>meta</filename> branch.
7891 As an example take a look in the
7892 <filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>
7893 file:
7894 <literallayout class='monospaced'>
7895 LINUX_VERSION_core2-32-intel-common = "3.19.0"
7896 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
7897 SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
7898 SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
7899 KMACHINE_core2-32-intel-common = "intel-core2-32"
7900 KBRANCH_core2-32-intel-common = "standard/base"
7901 KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
7902 </literallayout>
7903 The <filename>KMACHINE</filename> statement says that
7904 the kernel understands the machine name as
7905 "intel-core2-32".
7906 However, the OpenEmbedded build system understands the
7907 machine as "core2-32-intel-common".
7908 </para>
7909
7910 </glossdef>
7911 </glossentry>
7912
7913 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
7914 <info>
7915 KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
7916 </info>
7917 <glossdef>
7918 <para role="glossdeffirst">
7919 Defines the kernel type to be used in assembling the
7920 configuration.
7921 The linux-yocto recipes define "standard", "tiny",
7922 and "preempt-rt" kernel types.
7923 See the
7924 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
7925 section in the Yocto Project Linux Kernel Development
7926 Manual for more information on kernel types.
7927 </para>
7928
7929 <para>
7930 You define the <filename>KTYPE</filename> variable in the
7931 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
7932 The value you use must match the value used for the
7933 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
7934 value used by the kernel recipe.
7935 </para>
7936 </glossdef>
7937 </glossentry>
7938 </glossdiv>
7939
7940 <glossdiv id='var-glossary-l'><title>L</title>
7941
7942 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
7943 <info>
7944 LABELS[doc] = "Provides a list of targets for automatic configuration."
7945 </info>
7946 <glossdef>
7947 <para role="glossdeffirst">
7948 Provides a list of targets for automatic configuration.
7949 </para>
7950
7951 <para>
7952 See the
7953 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
7954 class for more information on how this variable is used.
7955 </para>
7956 </glossdef>
7957 </glossentry>
7958
7959 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
7960 <info>
7961 LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, on which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."
7962 </info>
7963 <glossdef>
7964 <para role="glossdeffirst">
7965 Lists the layers, separated by spaces, on which this
7966 recipe depends.
7967 Optionally, you can specify a specific layer version for a
7968 dependency by adding it to the end of the layer name.
7969 Here is an example:
7970 <literallayout class='monospaced'>
7971 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
7972 </literallayout>
7973 In this previous example, version 3 of "anotherlayer"
7974 is compared against
7975 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>.
7976 </para>
7977
7978 <para>
7979 An error is produced if any dependency is missing or
7980 the version numbers (if specified) do not match exactly.
7981 This variable is used in the
7982 <filename>conf/layer.conf</filename> file and must be
7983 suffixed with the name of the specific layer (e.g.
7984 <filename>LAYERDEPENDS_mylayer</filename>).
7985 </para>
7986 </glossdef>
7987 </glossentry>
7988
7989 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
7990 <info>
7991 LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."
7992 </info>
7993 <glossdef>
7994 <para role="glossdeffirst">
7995 When used inside the <filename>layer.conf</filename> configuration
7996 file, this variable provides the path of the current layer.
7997 This variable is not available outside of <filename>layer.conf</filename>
7998 and references are expanded immediately when parsing of the file completes.
7999 </para>
8000 </glossdef>
8001 </glossentry>
8002
8003 <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm>
8004 <info>
8005 LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."
8006 </info>
8007 <glossdef>
8008 <para role="glossdeffirst">
8009 Lists the layers, separated by spaces, recommended for
8010 use with this layer.
8011 </para>
8012
8013 <para>
8014 Optionally, you can specify a specific layer version for a
8015 recommendation by adding the version to the end of the
8016 layer name.
8017 Here is an example:
8018 <literallayout class='monospaced'>
8019 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
8020 </literallayout>
8021 In this previous example, version 3 of "anotherlayer" is
8022 compared against
8023 <filename>LAYERVERSION_anotherlayer</filename>.
8024 </para>
8025
8026 <para>
8027 This variable is used in the
8028 <filename>conf/layer.conf</filename> file and must be
8029 suffixed with the name of the specific layer (e.g.
8030 <filename>LAYERRECOMMENDS_mylayer</filename>).
8031 </para>
8032 </glossdef>
8033 </glossentry>
8034
8035 <glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>
8036 <info>
8037 LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."
8038 </info>
8039 <glossdef>
8040 <para role="glossdeffirst">
8041 Lists the versions of the
8042 <link linkend='oe-core'>OpenEmbedded-Core</link> for which
8043 a layer is compatible.
8044 Using the <filename>LAYERSERIES_COMPAT</filename> variable
8045 allows the layer maintainer to indicate which combinations
8046 of the layer and OE-Core can be expected to work.
8047 The variable gives the system a way to detect when a layer
8048 has not been tested with new releases of OE-Core (e.g.
8049 the layer is not maintained).
8050 </para>
8051
8052 <para>
8053 To specify the OE-Core versions for which a layer is
8054 compatible, use this variable in your layer's
8055 <filename>conf/layer.conf</filename> configuration file.
8056 For the list, use the Yocto Project
8057 <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>
8058 (e.g. &DISTRO_NAME_NO_CAP;).
8059 To specify multiple OE-Core versions for the layer,
8060 use a space-separated list:
8061 <literallayout class='monospaced'>
8062 LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
8063 </literallayout>
8064 <note>
8065 Setting <filename>LAYERSERIES_COMPAT</filename> is
8066 required by the Yocto Project Compatible version 2
8067 standard.
8068 The OpenEmbedded build system produces a warning if
8069 the variable is not set for any given layer.
8070 </note>
8071 </para>
8072
8073 <para>
8074 See the
8075 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
8076 section in the Yocto Project Development Tasks Manual.
8077 </para>
8078 </glossdef>
8079 </glossentry>
8080
8081 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
8082 <info>
8083 LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."
8084 </info>
8085 <glossdef>
8086 <para role="glossdeffirst">
8087 Optionally specifies the version of a layer as a single number.
8088 You can use this within
8089 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
8090 for another layer in order to depend on a specific version
8091 of the layer.
8092 This variable is used in the <filename>conf/layer.conf</filename> file
8093 and must be suffixed with the name of the specific layer (e.g.
8094 <filename>LAYERVERSION_mylayer</filename>).
8095 </para>
8096 </glossdef>
8097 </glossentry>
8098
8099 <glossentry id='var-LD'><glossterm>LD</glossterm>
8100 <info>
8101 LD[doc] = "Minimal command and arguments to run the linker."
8102 </info>
8103 <glossdef>
8104 <para role="glossdeffirst">
8105 The minimal command and arguments used to run the
8106 linker.
8107 </para>
8108 </glossdef>
8109 </glossentry>
8110
8111 <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
8112 <info>
8113 LDFLAGS[doc] = "Specifies the flags to pass to the linker."
8114 </info>
8115 <glossdef>
8116 <para role="glossdeffirst">
8117 Specifies the flags to pass to the linker.
8118 This variable is exported to an environment
8119 variable and thus made visible to the software being
8120 built during the compilation step.
8121 </para>
8122
8123 <para>
8124 Default initialization for <filename>LDFLAGS</filename>
8125 varies depending on what is being built:
8126 <itemizedlist>
8127 <listitem><para>
8128 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
8129 when building for the target
8130 </para></listitem>
8131 <listitem><para>
8132 <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
8133 when building for the build host (i.e.
8134 <filename>-native</filename>)
8135 </para></listitem>
8136 <listitem><para>
8137 <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
8138 when building for an SDK (i.e.
8139 <filename>nativesdk-</filename>)
8140 </para></listitem>
8141 </itemizedlist>
8142 </para>
8143 </glossdef>
8144 </glossentry>
8145
8146 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
8147 <info>
8148 LEAD_SONAME[doc] = "Specifies the lead (or primary) compiled library file (i.e. .so) that the debian class applies its naming policy to given a recipe that packages multiple libraries."
8149 </info>
8150 <glossdef>
8151 <para role="glossdeffirst">
8152 Specifies the lead (or primary) compiled library file
8153 (i.e. <filename>.so</filename>) that the
8154 <link linkend='ref-classes-debian'><filename>debian</filename></link>
8155 class applies its naming policy to given a recipe that
8156 packages multiple libraries.
8157 </para>
8158
8159 <para>
8160 This variable works in conjunction with the
8161 <filename>debian</filename> class.
8162 </para>
8163 </glossdef>
8164 </glossentry>
8165
8166 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
8167 <info>
8168 LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."
8169 </info>
8170 <glossdef>
8171 <para role="glossdeffirst">
8172 Checksums of the license text in the recipe source code.
8173 </para>
8174
8175 <para>
8176 This variable tracks changes in license text of the source
8177 code files.
8178 If the license text is changed, it will trigger a build
8179 failure, which gives the developer an opportunity to review any
8180 license change.
8181 </para>
8182
8183 <para>
8184 This variable must be defined for all recipes (unless
8185 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8186 is set to "CLOSED").</para>
8187 <para>For more information, see the
8188 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
8189 section in the Yocto Project Development Tasks Manual.
8190 </para>
8191 </glossdef>
8192 </glossentry>
8193
8194 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
8195 <info>
8196 LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &amp;, '|', and parentheses can be used."
8197 </info>
8198 <glossdef>
8199 <para role="glossdeffirst">
8200 The list of source licenses for the recipe.
8201 Follow these rules:
8202 <itemizedlist>
8203 <listitem><para>Do not use spaces within individual
8204 license names.</para></listitem>
8205 <listitem><para>Separate license names using
8206 | (pipe) when there is a choice between licenses.
8207 </para></listitem>
8208 <listitem><para>Separate license names using
8209 &amp; (ampersand) when multiple licenses exist
8210 that cover different parts of the source.
8211 </para></listitem>
8212 <listitem><para>You can use spaces between license
8213 names.</para></listitem>
8214 <listitem><para>For standard licenses, use the names
8215 of the files in
8216 <filename>meta/files/common-licenses/</filename>
8217 or the
8218 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
8219 flag names defined in
8220 <filename>meta/conf/licenses.conf</filename>.
8221 </para></listitem>
8222 </itemizedlist>
8223 </para>
8224
8225 <para>
8226 Here are some examples:
8227 <literallayout class='monospaced'>
8228 LICENSE = "LGPLv2.1 | GPLv3"
8229 LICENSE = "MPL-1 &amp; LGPLv2.1"
8230 LICENSE = "GPLv2+"
8231 </literallayout>
8232 The first example is from the recipes for Qt, which the user
8233 may choose to distribute under either the LGPL version
8234 2.1 or GPL version 3.
8235 The second example is from Cairo where two licenses cover
8236 different parts of the source code.
8237 The final example is from <filename>sysstat</filename>,
8238 which presents a single license.
8239 </para>
8240
8241 <para>
8242 You can also specify licenses on a per-package basis to
8243 handle situations where components of the output have
8244 different licenses.
8245 For example, a piece of software whose code is
8246 licensed under GPLv2 but has accompanying documentation
8247 licensed under the GNU Free Documentation License 1.2 could
8248 be specified as follows:
8249 <literallayout class='monospaced'>
8250 LICENSE = "GFDL-1.2 &amp; GPLv2"
8251 LICENSE_${PN} = "GPLv2"
8252 LICENSE_${PN}-doc = "GFDL-1.2"
8253 </literallayout>
8254 </para>
8255 </glossdef>
8256 </glossentry>
8257
8258 <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>
8259 <info>
8260 LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."
8261 </info>
8262 <glossdef>
8263 <para role="glossdeffirst">
8264 Setting <filename>LICENSE_CREATE_PACKAGE</filename>
8265 to "1" causes the OpenEmbedded build system to create
8266 an extra package (i.e.
8267 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)
8268 for each recipe and to add those packages to the
8269 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>.
8270 </para>
8271
8272 <para>
8273 The <filename>${PN}-lic</filename> package installs a
8274 directory in <filename>/usr/share/licenses</filename>
8275 named <filename>${PN}</filename>, which is the recipe's
8276 base name, and installs files in that directory that
8277 contain license and copyright information (i.e. copies of
8278 the appropriate license files from
8279 <filename>meta/common-licenses</filename> that match the
8280 licenses specified in the
8281 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8282 variable of the recipe metadata and copies of files marked
8283 in
8284 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
8285 as containing license text).
8286 </para>
8287
8288 <para>
8289 For related information on providing license text, see the
8290 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
8291 variable, the
8292 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
8293 variable, and the
8294 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
8295 section in the Yocto Project Development Tasks Manual.
8296 </para>
8297 </glossdef>
8298 </glossentry>
8299
8300 <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>
8301 <info>
8302 LICENSE_FLAGS[doc] = "Specifies additional flags for a recipe you must whitelist through LICENSE_FLAGS_WHITELIST in order to allow the recipe to be built."
8303 </info>
8304 <glossdef>
8305 <para role="glossdeffirst">
8306 Specifies additional flags for a recipe you must
8307 whitelist through
8308 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
8309 in order to allow the recipe to be built.
8310 When providing multiple flags, separate them with
8311 spaces.
8312 </para>
8313
8314 <para>
8315 This value is independent of
8316 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8317 and is typically used to mark recipes that might
8318 require additional licenses in order to be used in a
8319 commercial product.
8320 For more information, see the
8321 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8322 section in the Yocto Project Development Tasks Manual.
8323 </para>
8324 </glossdef>
8325 </glossentry>
8326
8327 <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm>
8328 <info>
8329 LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built."
8330 </info>
8331 <glossdef>
8332 <para role="glossdeffirst">
8333 Lists license flags that when specified in
8334 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
8335 within a recipe should not prevent that recipe from being
8336 built.
8337 This practice is otherwise known as "whitelisting"
8338 license flags.
8339 For more information, see the
8340 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8341 section in the Yocto Project Development Tasks Manual.
8342 </para>
8343 </glossdef>
8344 </glossentry>
8345
8346 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
8347 <info>
8348 LICENSE_PATH[doc] = "Path to additional licenses used during the build."
8349 </info>
8350 <glossdef>
8351 <para role="glossdeffirst">
8352 Path to additional licenses used during the build.
8353 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
8354 to define the directory that holds common license text used during the build.
8355 The <filename>LICENSE_PATH</filename> variable allows you to extend that
8356 location to other areas that have additional licenses:
8357 <literallayout class='monospaced'>
8358 LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"
8359 </literallayout>
8360 </para>
8361 </glossdef>
8362 </glossentry>
8363
8364 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
8365 <info>
8366 LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8367 </info>
8368 <glossdef>
8369 <para role="glossdeffirst">
8370 Defines the kernel type to be used in assembling the
8371 configuration.
8372 The linux-yocto recipes define "standard", "tiny", and
8373 "preempt-rt" kernel types.
8374 See the
8375 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8376 section in the Yocto Project Linux Kernel Development
8377 Manual for more information on kernel types.
8378 </para>
8379
8380 <para>
8381 If you do not specify a
8382 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
8383 "standard".
8384 Together with
8385 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
8386 the <filename>LINUX_KERNEL_TYPE</filename> variable
8387 defines the search
8388 arguments used by the kernel tools to find the appropriate
8389 description within the kernel
8390 <link linkend='metadata'>Metadata</link>
8391 with which to build out the sources and configuration.
8392 </para>
8393 </glossdef>
8394 </glossentry>
8395
8396 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
8397 <info>
8398 LINUX_VERSION[doc] = "The Linux version from kernel.org on which the Linux kernel image being built using the OpenEmbedded build system is based. You define this variable in the kernel recipe."
8399 </info>
8400 <glossdef>
8401 <para role="glossdeffirst">
8402 The Linux version from <filename>kernel.org</filename>
8403 on which the Linux kernel image being built using the
8404 OpenEmbedded build system is based.
8405 You define this variable in the kernel recipe.
8406 For example, the <filename>linux-yocto-3.4.bb</filename>
8407 kernel recipe found in
8408 <filename>meta/recipes-kernel/linux</filename>
8409 defines the variables as follows:
8410 <literallayout class='monospaced'>
8411 LINUX_VERSION ?= "3.4.24"
8412 </literallayout>
8413 </para>
8414
8415 <para>
8416 The <filename>LINUX_VERSION</filename> variable is used to
8417 define <link linkend='var-PV'><filename>PV</filename></link>
8418 for the recipe:
8419 <literallayout class='monospaced'>
8420 PV = "${LINUX_VERSION}+git${SRCPV}"
8421 </literallayout>
8422 </para>
8423 </glossdef>
8424 </glossentry>
8425
8426 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
8427 <info>
8428 LINUX_VERSION_EXTENSION[doc] = "A string extension compiled into the version string of the Linux kernel built with the OpenEmbedded build system. You define this variable in the kernel recipe."
8429 </info>
8430 <glossdef>
8431 <para role="glossdeffirst">
8432 A string extension compiled into the version
8433 string of the Linux kernel built with the OpenEmbedded
8434 build system.
8435 You define this variable in the kernel recipe.
8436 For example, the linux-yocto kernel recipes all define
8437 the variable as follows:
8438 <literallayout class='monospaced'>
8439 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
8440 </literallayout>
8441 </para>
8442
8443 <para>
8444 Defining this variable essentially sets the
8445 Linux kernel configuration item
8446 <filename>CONFIG_LOCALVERSION</filename>, which is visible
8447 through the <filename>uname</filename> command.
8448 Here is an example that shows the extension assuming it
8449 was set as previously shown:
8450 <literallayout class='monospaced'>
8451 $ uname -r
8452 3.7.0-rc8-custom
8453 </literallayout>
8454 </para>
8455 </glossdef>
8456 </glossentry>
8457
8458 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
8459 <info>
8460 LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log"
8461 </info>
8462 <glossdef>
8463 <para role="glossdeffirst">
8464 Specifies the directory to which the OpenEmbedded build
8465 system writes overall log files.
8466 The default directory is <filename>${TMPDIR}/log</filename>.
8467 </para>
8468
8469 <para>
8470 For the directory containing logs specific to each task,
8471 see the <link linkend='var-T'><filename>T</filename></link>
8472 variable.
8473 </para>
8474 </glossdef>
8475 </glossentry>
8476
8477 </glossdiv>
8478
8479 <glossdiv id='var-glossary-m'><title>M</title>
8480
8481 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
8482 <info>
8483 MACHINE[doc] = "Specifies the target device for which the image is built. You define MACHINE in the conf/local.conf file in the Build Directory."
8484 </info>
8485 <glossdef>
8486 <para role="glossdeffirst">
8487 Specifies the target device for which the image is built.
8488 You define <filename>MACHINE</filename> in the
8489 <filename>local.conf</filename> file found in the
8490 <link linkend='build-directory'>Build Directory</link>.
8491 By default, <filename>MACHINE</filename> is set to
8492 "qemux86", which is an x86-based architecture machine to
8493 be emulated using QEMU:
8494 <literallayout class='monospaced'>
8495 MACHINE ?= "qemux86"
8496 </literallayout>
8497 </para>
8498
8499 <para>
8500 The variable corresponds to a machine configuration file of the
8501 same name, through which machine-specific configurations are set.
8502 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
8503 exists the corresponding <filename>qemux86.conf</filename> machine
8504 configuration file, which can be found in the
8505 <link linkend='source-directory'>Source Directory</link>
8506 in <filename>meta/conf/machine</filename>.
8507 </para>
8508
8509 <para>
8510 The list of machines supported by the Yocto Project as
8511 shipped include the following:
8512 <literallayout class='monospaced'>
8513 MACHINE ?= "qemuarm"
8514 MACHINE ?= "qemuarm64"
8515 MACHINE ?= "qemumips"
8516 MACHINE ?= "qemumips64"
8517 MACHINE ?= "qemuppc"
8518 MACHINE ?= "qemux86"
8519 MACHINE ?= "qemux86-64"
8520 MACHINE ?= "genericx86"
8521 MACHINE ?= "genericx86-64"
8522 MACHINE ?= "beaglebone"
8523 MACHINE ?= "edgerouter"
8524 </literallayout>
8525 The last five are Yocto Project reference hardware boards, which
8526 are provided in the <filename>meta-yocto-bsp</filename> layer.
8527 <note>Adding additional Board Support Package (BSP) layers
8528 to your configuration adds new possible settings for
8529 <filename>MACHINE</filename>.
8530 </note>
8531 </para>
8532 </glossdef>
8533 </glossentry>
8534
8535 <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
8536 <info>
8537 MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."
8538 </info>
8539 <glossdef>
8540 <para role="glossdeffirst">
8541 Specifies the name of the machine-specific architecture.
8542 This variable is set automatically from
8543 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
8544 or
8545 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
8546 You should not hand-edit the
8547 <filename>MACHINE_ARCH</filename> variable.
8548 </para>
8549 </glossdef>
8550 </glossentry>
8551
8552 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
8553 <info>
8554 MACHINE_ESSENTIAL_EXTRA_RDEPENDS[doc] = "A list of required machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."
8555 </info>
8556 <glossdef>
8557 <para role="glossdeffirst">
8558 A list of required machine-specific packages to install as part of
8559 the image being built.
8560 The build process depends on these packages being present.
8561 Furthermore, because this is a "machine-essential" variable, the list of
8562 packages are essential for the machine to boot.
8563 The impact of this variable affects images based on
8564 <filename>packagegroup-core-boot</filename>,
8565 including the <filename>core-image-minimal</filename> image.
8566 </para>
8567
8568 <para>
8569 This variable is similar to the
8570 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
8571 variable with the exception that the image being built has a build
8572 dependency on the variable's list of packages.
8573 In other words, the image will not build if a file in this list is not found.
8574 </para>
8575
8576 <para>
8577 As an example, suppose the machine for which you are building requires
8578 <filename>example-init</filename> to be run during boot to initialize the hardware.
8579 In this case, you would use the following in the machine's
8580 <filename>.conf</filename> configuration file:
8581 <literallayout class='monospaced'>
8582 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
8583 </literallayout>
8584 </para>
8585 </glossdef>
8586 </glossentry>
8587
8588 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
8589 <info>
8590 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS[doc] = "A list of recommended machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."
8591 </info>
8592 <glossdef>
8593 <para role="glossdeffirst">
8594 A list of recommended machine-specific packages to install as part of
8595 the image being built.
8596 The build process does not depend on these packages being present.
8597 However, because this is a "machine-essential" variable, the list of
8598 packages are essential for the machine to boot.
8599 The impact of this variable affects images based on
8600 <filename>packagegroup-core-boot</filename>,
8601 including the <filename>core-image-minimal</filename> image.
8602 </para>
8603
8604 <para>
8605 This variable is similar to the
8606 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
8607 variable with the exception that the image being built does not have a build
8608 dependency on the variable's list of packages.
8609 In other words, the image will still build if a package in this list is not found.
8610 Typically, this variable is used to handle essential kernel modules, whose
8611 functionality may be selected to be built into the kernel rather than as a module,
8612 in which case a package will not be produced.
8613 </para>
8614
8615 <para>
8616 Consider an example where you have a custom kernel where a specific touchscreen
8617 driver is required for the machine to be usable.
8618 However, the driver can be built as a module or
8619 into the kernel depending on the kernel configuration.
8620 If the driver is built as a module, you want it to be installed.
8621 But, when the driver is built into the kernel, you still want the
8622 build to succeed.
8623 This variable sets up a "recommends" relationship so that in the latter case,
8624 the build will not fail due to the missing package.
8625 To accomplish this, assuming the package for the module was called
8626 <filename>kernel-module-ab123</filename>, you would use the
8627 following in the machine's <filename>.conf</filename> configuration
8628 file:
8629 <literallayout class='monospaced'>
8630 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
8631 </literallayout>
8632 <note>
8633 In this example, the
8634 <filename>kernel-module-ab123</filename> recipe
8635 needs to explicitly set its
8636 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
8637 variable to ensure that BitBake does not use the
8638 kernel recipe's
8639 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
8640 variable to satisfy the dependency.
8641 </note>
8642 </para>
8643
8644 <para>
8645 Some examples of these machine essentials are flash, screen, keyboard, mouse,
8646 or touchscreen drivers (depending on the machine).
8647 </para>
8648 </glossdef>
8649 </glossentry>
8650
8651 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
8652 <info>
8653 MACHINE_EXTRA_RDEPENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for the machine to boot. However, the build process for more fully-featured images depends on the packages being present."
8654 </info>
8655 <glossdef>
8656 <para role="glossdeffirst">
8657 A list of machine-specific packages to install as part of the
8658 image being built that are not essential for the machine to boot.
8659 However, the build process for more fully-featured images
8660 depends on the packages being present.
8661 </para>
8662
8663 <para>
8664 This variable affects all images based on
8665 <filename>packagegroup-base</filename>, which does not include the
8666 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8667 images.
8668 </para>
8669
8670 <para>
8671 The variable is similar to the
8672 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
8673 variable with the exception that the image being built has a build
8674 dependency on the variable's list of packages.
8675 In other words, the image will not build if a file in this list is not found.
8676 </para>
8677
8678 <para>
8679 An example is a machine that has WiFi capability but is not
8680 essential for the machine to boot the image.
8681 However, if you are building a more fully-featured image, you want to enable
8682 the WiFi.
8683 The package containing the firmware for the WiFi hardware is always
8684 expected to exist, so it is acceptable for the build process to depend upon
8685 finding the package.
8686 In this case, assuming the package for the firmware was called
8687 <filename>wifidriver-firmware</filename>, you would use the following in the
8688 <filename>.conf</filename> file for the machine:
8689 <literallayout class='monospaced'>
8690 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
8691 </literallayout>
8692 </para>
8693 </glossdef>
8694 </glossentry>
8695
8696 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
8697 <info>
8698 MACHINE_EXTRA_RRECOMMENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for booting the machine. The image being built has no build dependencies on the packages in this list."
8699 </info>
8700 <glossdef>
8701 <para role="glossdeffirst">
8702 A list of machine-specific packages to install as part of the
8703 image being built that are not essential for booting the machine.
8704 The image being built has no build dependency on this list of packages.
8705 </para>
8706
8707 <para>
8708 This variable affects only images based on
8709 <filename>packagegroup-base</filename>, which does not include the
8710 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8711 images.
8712 </para>
8713
8714 <para>
8715 This variable is similar to the
8716 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
8717 variable with the exception that the image being built does not have a build
8718 dependency on the variable's list of packages.
8719 In other words, the image will build if a file in this list is not found.
8720 </para>
8721
8722 <para>
8723 An example is a machine that has WiFi capability but is not essential
8724 For the machine to boot the image.
8725 However, if you are building a more fully-featured image, you want to enable
8726 WiFi.
8727 In this case, the package containing the WiFi kernel module will not be produced
8728 if the WiFi driver is built into the kernel, in which case you still want the
8729 build to succeed instead of failing as a result of the package not being found.
8730 To accomplish this, assuming the package for the module was called
8731 <filename>kernel-module-examplewifi</filename>, you would use the
8732 following in the <filename>.conf</filename> file for the machine:
8733 <literallayout class='monospaced'>
8734 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
8735 </literallayout>
8736 </para>
8737 </glossdef>
8738 </glossentry>
8739
8740 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
8741 <info>
8742 MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."
8743 </info>
8744 <glossdef>
8745 <para role="glossdeffirst">
8746 Specifies the list of hardware features the
8747 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
8748 of supporting.
8749 For related information on enabling features, see the
8750 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
8751 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
8752 and
8753 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
8754 variables.
8755 </para>
8756
8757 <para>
8758 For a list of hardware features supported by the Yocto
8759 Project as shipped, see the
8760 "<link linkend='ref-features-machine'>Machine Features</link>"
8761 section.
8762 </para>
8763 </glossdef>
8764 </glossentry>
8765
8766 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
8767 <info>
8768 MACHINE_FEATURES_BACKFILL[doc] = "Features to be added to MACHINE_FEATURES if not also present in MACHINE_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and is not intended to be user-configurable."
8769 </info>
8770 <glossdef>
8771 <para role="glossdeffirst">
8772 Features to be added to
8773 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
8774 if not also present in
8775 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
8776 </para>
8777
8778 <para>
8779 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
8780 It is not intended to be user-configurable.
8781 It is best to just reference the variable to see which machine features are
8782 being backfilled for all machine configurations.
8783 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
8784 more information.
8785 </para>
8786 </glossdef>
8787 </glossentry>
8788
8789 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
8790 <info>
8791 MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build."
8792 </info>
8793 <glossdef>
8794 <para role="glossdeffirst">
8795 Features from
8796 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
8797 that should not be backfilled (i.e. added to
8798 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
8799 during the build.
8800 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
8801 more information.
8802 </para>
8803 </glossdef>
8804 </glossentry>
8805
8806 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
8807 <info>
8808 MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."
8809 </info>
8810 <glossdef>
8811 <para role="glossdeffirst">
8812 A colon-separated list of overrides that apply to the
8813 current machine.
8814 By default, this list includes the value of
8815 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>.
8816 </para>
8817
8818 <para>
8819 You can extend <filename>MACHINEOVERRIDES</filename>
8820 to add extra overrides that should apply to a machine.
8821 For example, all machines emulated in QEMU (e.g.
8822 <filename>qemuarm</filename>, <filename>qemux86</filename>,
8823 and so forth) include a file named
8824 <filename>meta/conf/machine/include/qemu.inc</filename>
8825 that prepends the following override to
8826 <filename>MACHINEOVERRIDES</filename>:
8827 <literallayout class='monospaced'>
8828 MACHINEOVERRIDES =. "qemuall:"
8829 </literallayout>
8830 This override allows variables to be overriden for all
8831 machines emulated in QEMU, like in the following example
8832 from the <filename>connman-conf</filename> recipe:
8833 <literallayout class='monospaced'>
8834 SRC_URI_append_qemuall = "file://wired.config \
8835 file://wired-setup \
8836 "
8837 </literallayout>
8838 The underlying mechanism behind
8839 <filename>MACHINEOVERRIDES</filename> is simply that it is
8840 included in the default value of
8841 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
8842 </para>
8843 </glossdef>
8844 </glossentry>
8845
8846 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
8847 <info>
8848 MAINTAINER[doc] = "The email address of the distribution maintainer."
8849 </info>
8850 <glossdef>
8851 <para role="glossdeffirst">
8852 The email address of the distribution maintainer.
8853 </para>
8854 </glossdef>
8855 </glossentry>
8856
8857 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
8858 <info>
8859 MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
8860 </info>
8861 <glossdef>
8862 <para role="glossdeffirst">
8863 Specifies additional paths from which the OpenEmbedded
8864 build system gets source code.
8865 When the build system searches for source code, it first
8866 tries the local download directory.
8867 If that location fails, the build system tries locations
8868 defined by
8869 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
8870 the upstream source, and then locations specified by
8871 <filename>MIRRORS</filename> in that order.
8872 </para>
8873
8874 <para>
8875 Assuming your distribution
8876 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
8877 is "poky", the default value for
8878 <filename>MIRRORS</filename> is defined in the
8879 <filename>conf/distro/poky.conf</filename> file in the
8880 <filename>meta-poky</filename> Git repository.
8881 </para>
8882 </glossdef>
8883 </glossentry>
8884
8885 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
8886 <info>
8887 MLPREFIX[doc] = "Specifies a prefix has been added to PN to create a special version of a recipe or package (i.e. a Multilib version)."
8888 </info>
8889 <glossdef>
8890 <para role="glossdeffirst">
8891 Specifies a prefix has been added to
8892 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
8893 of a recipe or package (i.e. a Multilib version).
8894 The variable is used in places where the prefix needs to be
8895 added to or removed from a the name (e.g. the
8896 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
8897 <filename>MLPREFIX</filename> gets set when a prefix has been
8898 added to <filename>PN</filename>.
8899 <note>
8900 The "ML" in <filename>MLPREFIX</filename> stands for
8901 "MultiLib".
8902 This representation is historical and comes from
8903 a time when <filename>nativesdk</filename> was a suffix
8904 rather than a prefix on the recipe name.
8905 When <filename>nativesdk</filename> was turned into a
8906 prefix, it made sense to set
8907 <filename>MLPREFIX</filename> for it as well.
8908 </note>
8909 </para>
8910
8911 <para>
8912 To help understand when <filename>MLPREFIX</filename>
8913 might be needed, consider when
8914 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
8915 is used to provide a <filename>nativesdk</filename> version
8916 of a recipe in addition to the target version.
8917 If that recipe declares build-time dependencies on tasks in
8918 other recipes by using
8919 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
8920 then a dependency on "foo" will automatically get rewritten
8921 to a dependency on "nativesdk-foo".
8922 However, dependencies like the following will not get
8923 rewritten automatically:
8924 <literallayout class='monospaced'>
8925 do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"
8926 </literallayout>
8927 If you want such a dependency to also get transformed,
8928 you can do the following:
8929 <literallayout class='monospaced'>
8930 do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"
8931 </literallayout>
8932 </para>
8933 </glossdef>
8934 </glossentry>
8935
8936 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
8937 <info>
8938 module_autoload[doc] = "This variable has been replaced by the KERNEL_MODULE_AUTOLOAD variable. You should replace all occurrences of module_autoload with additions to KERNEL_MODULE_AUTOLOAD."
8939 </info>
8940 <glossdef>
8941 <para role="glossdeffirst">
8942 This variable has been replaced by the
8943 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
8944 You should replace all occurrences of
8945 <filename>module_autoload</filename> with additions to
8946 <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
8947 <literallayout class='monospaced'>
8948 module_autoload_rfcomm = "rfcomm"
8949 </literallayout>
8950 </para>
8951
8952 <para>
8953 should now be replaced with:
8954 <literallayout class='monospaced'>
8955 KERNEL_MODULE_AUTOLOAD += "rfcomm"
8956 </literallayout>
8957 See the
8958 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
8959 variable for more information.
8960 </para>
8961 </glossdef>
8962 </glossentry>
8963
8964 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
8965 <info>
8966 module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."
8967 </info>
8968 <glossdef>
8969 <para role="glossdeffirst">
8970 Specifies
8971 <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>
8972 syntax lines for inclusion in the
8973 <filename>/etc/modprobe.d/modname.conf</filename> file.
8974 </para>
8975
8976 <para>
8977 You can use this variable anywhere that it can be
8978 recognized by the kernel recipe or out-of-tree kernel
8979 module recipe (e.g. a machine configuration file, a
8980 distribution configuration file, an append file for the
8981 recipe, or the recipe itself).
8982 If you use this variable, you must also be sure to list
8983 the module name in the
8984 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
8985 variable.
8986 </para>
8987
8988 <para>
8989 Here is the general syntax:
8990 <literallayout class='monospaced'>
8991 module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"
8992 </literallayout>
8993 You must use the kernel module name override.
8994 </para>
8995
8996 <para>
8997 Run <filename>man modprobe.d</filename> in the shell to
8998 find out more information on the exact syntax
8999 you want to provide with <filename>module_conf</filename>.
9000 </para>
9001
9002 <para>
9003 Including <filename>module_conf</filename> causes the
9004 OpenEmbedded build system to populate the
9005 <filename>/etc/modprobe.d/modname.conf</filename>
9006 file with <filename>modprobe.d</filename> syntax lines.
9007 Here is an example that adds the options
9008 <filename>arg1</filename> and <filename>arg2</filename>
9009 to a module named <filename>mymodule</filename>:
9010 <literallayout class='monospaced'>
9011 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
9012 </literallayout>
9013 </para>
9014
9015 <para>
9016 For information on how to specify kernel modules to
9017 auto-load on boot, see the
9018 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9019 variable.
9020 </para>
9021 </glossdef>
9022 </glossentry>
9023
9024 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
9025 <info>
9026 MODULE_TARBALL_DEPLOY[doc] = "Controls creation of the modules-*.tgz file. Set this variable to "0" to disable creation of this file, which contains all of the kernel modules resulting from a kernel build."
9027 </info>
9028 <glossdef>
9029 <para role="glossdeffirst">
9030 Controls creation of the <filename>modules-*.tgz</filename>
9031 file.
9032 Set this variable to "0" to disable creation of this
9033 file, which contains all of the kernel modules resulting
9034 from a kernel build.
9035 </para>
9036 </glossdef>
9037 </glossentry>
9038
9039 <glossentry id='var-MODULE_TARBALL_LINK_NAME'><glossterm>MODULE_TARBALL_LINK_NAME</glossterm>
9040 <info>
9041 MODULE_TARBALL_LINK_NAME[doc] = "The link name of the kernel module tarball."
9042 </info>
9043 <glossdef>
9044 <para role="glossdeffirst">
9045 The link name of the kernel module tarball.
9046 This variable is set in the
9047 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9048 file as follows:
9049 <literallayout class='monospaced'>
9050 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
9051 </literallayout>
9052 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
9053 variable, which is set in the same file, has the following
9054 value:
9055 <literallayout class='monospaced'>
9056 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
9057 </literallayout>
9058 </para>
9059
9060 <para>
9061 See the
9062 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
9063 variable for additional information.
9064 </para>
9065 </glossdef>
9066 </glossentry>
9067
9068 <glossentry id='var-MODULE_TARBALL_NAME'><glossterm>MODULE_TARBALL_NAME</glossterm>
9069 <info>
9070 MODULE_TARBALL_NAME[doc] = "The base name of the kernel module tarball."
9071 </info>
9072 <glossdef>
9073 <para role="glossdeffirst">
9074 The base name of the kernel module tarball.
9075 This variable is set in the
9076 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9077 file as follows:
9078 <literallayout class='monospaced'>
9079 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
9080 </literallayout>
9081 The value of the
9082 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
9083 variable, which is set in the same file, has the following
9084 value:
9085 <literallayout class='monospaced'>
9086 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
9087 </literallayout>
9088 </para>
9089 </glossdef>
9090 </glossentry>
9091
9092<!--
9093 <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>
9094 <info>
9095 MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."
9096 </info>
9097 <glossdef>
9098 <para role="glossdeffirst">
9099-->
9100<!--
9101 Serves the same purpose as
9102 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
9103 but for the "HOST" system, in situations that involve a
9104 "HOST" and a "TARGET" system.
9105 See the
9106 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9107 variable for more information.
9108 </para>
9109
9110 <para>
9111 The default value of this variable is:
9112 <literallayout class='monospaced'>
9113 ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}
9114 </literallayout>
9115 </para>
9116 </glossdef>
9117 </glossentry>
9118-->
9119
9120 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
9121 <info>
9122 MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."
9123 </info>
9124 <glossdef>
9125 <para role="glossdeffirst">
9126 Uniquely identifies the type of the target system for
9127 which packages are being built.
9128 This variable allows output for different types of target
9129 systems to be put into different subdirectories of the same
9130 output directory.
9131 </para>
9132
9133 <para>
9134 The default value of this variable is:
9135 <literallayout class='monospaced'>
9136 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
9137 </literallayout>
9138 Some classes (e.g.
9139 <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>)
9140 modify the <filename>MULTIMACH_TARGET_SYS</filename> value.
9141 </para>
9142
9143 <para>
9144 See the
9145 <link linkend='var-STAMP'><filename>STAMP</filename></link>
9146 variable for an example.
9147 See the
9148 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9149 variable for more information.
9150 </para>
9151 </glossdef>
9152 </glossentry>
9153
9154 </glossdiv>
9155
9156 <glossdiv id='var-glossary-n'><title>N</title>
9157
9158 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
9159 <info>
9160 NATIVELSBSTRING[doc] = "A string identifying the host distribution."
9161 </info>
9162 <glossdef>
9163 <para role="glossdeffirst">
9164 A string identifying the host distribution.
9165 Strings consist of the host distributor ID
9166 followed by the release, as reported by the
9167 <filename>lsb_release</filename> tool
9168 or as read from <filename>/etc/lsb-release</filename>.
9169 For example, when running a build on Ubuntu 12.10, the value
9170 is "Ubuntu-12.10".
9171 If this information is unable to be determined, the value
9172 resolves to "Unknown".
9173 </para>
9174
9175 <para>
9176 This variable is used by default to isolate native shared
9177 state packages for different distributions (e.g. to avoid
9178 problems with <filename>glibc</filename> version
9179 incompatibilities).
9180 Additionally, the variable is checked against
9181 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
9182 if that variable is set.
9183 </para>
9184 </glossdef>
9185 </glossentry>
9186
9187 <glossentry id='var-NM'><glossterm>NM</glossterm>
9188 <info>
9189 NM[doc] = "Minimal command and arguments to run 'nm'."
9190 </info>
9191 <glossdef>
9192 <para role="glossdeffirst">
9193 The minimal command and arguments to run
9194 <filename>nm</filename>.
9195 </para>
9196 </glossdef>
9197 </glossentry>
9198
9199 <glossentry id='var-NO_GENERIC_LICENSE'><glossterm>NO_GENERIC_LICENSE</glossterm>
9200 <info>
9201 NO_GENERIC_LICENSE[doc] = "Used to allow copying a license that does not exist in common licenses."
9202 </info>
9203 <glossdef>
9204 <para role="glossdeffirst">
9205 Avoids QA errors when you use a non-common, non-CLOSED
9206 license in a recipe.
9207 Packages exist, such as the linux-firmware package, with
9208 many licenses that are not in any way common.
9209 Also, new licenses are added occasionally to avoid
9210 introducing a lot of common license files, which are only
9211 applicable to a specific package.
9212 <filename>NO_GENERIC_LICENSE</filename> is used to allow
9213 copying a license that does not exist in common licenses.
9214 </para>
9215
9216 <para>
9217 The following example shows how to add
9218 <filename>NO_GENERIC_LICENSE</filename> to a recipe:
9219 <literallayout class='monospaced'>
9220 NO_GENERIC_LICENSE[<replaceable>license_name</replaceable>] = "<replaceable>license_file_in_fetched_source</replaceable>"
9221 </literallayout>
9222 The following is an example that uses the
9223 <filename>LICENSE.Abilis.txt</filename> file as the license
9224 from the fetched source:
9225 <literallayout class='monospaced'>
9226 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
9227 </literallayout>
9228 </para>
9229 </glossdef>
9230 </glossentry>
9231
9232 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
9233 <info>
9234 NO_RECOMMENDATIONS[doc] = "When set to '1', no recommended packages will be installed. Some recommended packages might be required for certain system functionality, such as kernel-modules. It is up to the user to add packages to IMAGE_INSTALL as needed."
9235 </info>
9236 <glossdef>
9237 <para role="glossdeffirst">
9238 Prevents installation of all "recommended-only" packages.
9239 Recommended-only packages are packages installed only
9240 through the
9241 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
9242 variable).
9243 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
9244 to "1" turns this feature on:
9245 <literallayout class='monospaced'>
9246 NO_RECOMMENDATIONS = "1"
9247 </literallayout>
9248 </para>
9249
9250 <para>
9251 You can set this variable globally in your
9252 <filename>local.conf</filename> file or you can attach it to
9253 a specific image recipe by using the recipe name override:
9254 <literallayout class='monospaced'>
9255 NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"
9256 </literallayout>
9257 </para>
9258
9259 <para>
9260 It is important to realize that if you choose to not install
9261 packages using this variable and some other packages are
9262 dependent on them (i.e. listed in a recipe's
9263 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
9264 variable), the OpenEmbedded build system ignores your
9265 request and will install the packages to avoid dependency
9266 errors.
9267 <note>
9268 Some recommended packages might be required for certain
9269 system functionality, such as kernel modules.
9270 It is up to you to add packages with the
9271 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
9272 variable.
9273 </note>
9274 </para>
9275
9276 <para>
9277 Support for this variable exists only when using the
9278 IPK and RPM packaging backend.
9279 Support does not exist for DEB.
9280 </para>
9281
9282 <para>
9283 See the
9284 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
9285 and the
9286 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
9287 variables for related information.
9288 </para>
9289 </glossdef>
9290 </glossentry>
9291
9292 <glossentry id='var-NOAUTOPACKAGEDEBUG'><glossterm>NOAUTOPACKAGEDEBUG</glossterm>
9293 <info>
9294 NOAUTOPACKAGEDEBUG[doc] = "Disables auto package from splitting .debug files."
9295 </info>
9296 <glossdef>
9297 <para role="glossdeffirst">
9298 Disables auto package from splitting
9299 <filename>.debug</filename> files. If a recipe requires
9300 <filename>FILES_${PN}-dbg</filename> to be set manually,
9301 the <filename>NOAUTOPACKAGEDEBUG</filename> can be defined
9302 allowing you to define the content of the debug package.
9303 For example:
9304 <literallayout class='monospaced'>
9305 NOAUTOPACKAGEDEBUG = "1"
9306 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
9307 FILES_${PN}-dbg = "/usr/src/debug/"
9308 FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
9309 </literallayout>
9310 </para>
9311 </glossdef>
9312 </glossentry>
9313 </glossdiv>
9314
9315 <glossdiv id='var-glossary-o'><title>O</title>
9316
9317 <glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>
9318 <info>
9319 OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."
9320 </info>
9321 <glossdef>
9322 <para role="glossdeffirst">
9323 The minimal command and arguments to run
9324 <filename>objcopy</filename>.
9325 </para>
9326 </glossdef>
9327 </glossentry>
9328
9329 <glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>
9330 <info>
9331 OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."
9332 </info>
9333 <glossdef>
9334 <para role="glossdeffirst">
9335 The minimal command and arguments to run
9336 <filename>objdump</filename>.
9337 </para>
9338 </glossdef>
9339 </glossentry>
9340
9341 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
9342 <info>
9343 OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command."
9344 </info>
9345 <glossdef>
9346 <para role="glossdeffirst">
9347 When inheriting the
9348 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
9349 class, this variable
9350 specifies additional arguments passed to the "sed" command.
9351 The sed command alters any paths in configuration scripts
9352 that have been set up during compilation.
9353 Inheriting this class results in all paths in these scripts
9354 being changed to point into the
9355 <filename>sysroots/</filename> directory so that all builds
9356 that use the script will use the correct directories
9357 for the cross compiling layout.
9358 </para>
9359
9360 <para>
9361 See the <filename>meta/classes/binconfig.bbclass</filename>
9362 in the
9363 <link linkend='source-directory'>Source Directory</link>
9364 for details on how this class applies these additional
9365 sed command arguments.
9366 For general information on the
9367 <filename>binconfig</filename> class, see the
9368 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
9369 section.
9370 </para>
9371 </glossdef>
9372 </glossentry>
9373
9374 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
9375 <info>
9376 OE_IMPORTS[doc] = "An internal variable used to tell the OpenEmbedded build system what Python modules to import for every Python function run by the system."
9377 </info>
9378 <glossdef>
9379 <para role="glossdeffirst">
9380 An internal variable used to tell the OpenEmbedded build
9381 system what Python modules to import for every Python
9382 function run by the system.
9383 </para>
9384
9385 <note>
9386 Do not set this variable.
9387 It is for internal use only.
9388 </note>
9389 </glossdef>
9390 </glossentry>
9391
9392 <glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>
9393 <info>
9394 OE_INIT_ENV_SCRIPT[doc] = "The name of the build environment setup script for the purposes of setting up the environment within the extensible SDK."
9395 </info>
9396 <glossdef>
9397 <para role="glossdeffirst">
9398 The name of the build environment setup script for the
9399 purposes of setting up the environment within the
9400 extensible SDK.
9401 The default value is "oe-init-build-env".
9402 </para>
9403
9404 <para>
9405 If you use a custom script to set up your build
9406 environment, set the
9407 <filename>OE_INIT_ENV_SCRIPT</filename> variable to its
9408 name.
9409 </para>
9410 </glossdef>
9411 </glossentry>
9412
9413 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
9414 <info>
9415 OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."
9416 </info>
9417 <glossdef>
9418 <para role="glossdeffirst">
9419 Controls how the OpenEmbedded build system spawns
9420 interactive terminals on the host development system
9421 (e.g. using the BitBake command with the
9422 <filename>-c devshell</filename> command-line option).
9423 For more information, see the
9424 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
9425 in the Yocto Project Development Tasks Manual.
9426 </para>
9427
9428 <para>
9429 You can use the following values for the
9430 <filename>OE_TERMINAL</filename> variable:
9431 <literallayout class='monospaced'>
9432 auto
9433 gnome
9434 xfce
9435 rxvt
9436 screen
9437 konsole
9438 none
9439 </literallayout>
9440 </para>
9441 </glossdef>
9442 </glossentry>
9443
9444 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
9445 <info>
9446 OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."
9447 </info>
9448 <glossdef>
9449 <para role="glossdeffirst">
9450 The directory from which the top-level build environment
9451 setup script is sourced.
9452 The Yocto Project provides a top-level build environment
9453 setup script:
9454 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
9455 When you run this script, the
9456 <filename>OEROOT</filename> variable resolves to the
9457 directory that contains the script.
9458 </para>
9459
9460 <para>
9461 For additional information on how this variable is used,
9462 see the initialization script.
9463 </para>
9464 </glossdef>
9465 </glossentry>
9466
9467 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
9468 <info>
9469 OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."
9470 </info>
9471 <glossdef>
9472 <para role="glossdeffirst">
9473 Declares the oldest version of the Linux kernel that the
9474 produced binaries must support.
9475 This variable is passed into the build of the Embedded
9476 GNU C Library (<filename>glibc</filename>).
9477 </para>
9478
9479 <para>
9480 The default for this variable comes from the
9481 <filename>meta/conf/bitbake.conf</filename> configuration
9482 file.
9483 You can override this default by setting the variable
9484 in a custom distribution configuration file.
9485 </para>
9486 </glossdef>
9487 </glossentry>
9488
9489 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
9490 <info>
9491 OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."
9492 </info>
9493 <glossdef>
9494 <para role="glossdeffirst">
9495 A colon-separated list of overrides that currently apply.
9496 Overrides are a BitBake mechanism that allows variables to
9497 be selectively overridden at the end of parsing.
9498 The set of overrides in <filename>OVERRIDES</filename>
9499 represents the "state" during building, which includes
9500 the current recipe being built, the machine for which
9501 it is being built, and so forth.
9502 </para>
9503
9504 <para>
9505 As an example, if the string "an-override" appears as an
9506 element in the colon-separated list in
9507 <filename>OVERRIDES</filename>, then the following
9508 assignment will override <filename>FOO</filename> with the
9509 value "overridden" at the end of parsing:
9510 <literallayout class='monospaced'>
9511 FOO_an-override = "overridden"
9512 </literallayout>
9513 See the
9514 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
9515 section in the BitBake User Manual for more information on
9516 the overrides mechanism.
9517 </para>
9518
9519 <para>
9520 The default value of <filename>OVERRIDES</filename>
9521 includes the values of the
9522 <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>,
9523 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>,
9524 and
9525 <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
9526 variables.
9527 Another important override included by default is
9528 <filename>pn-${PN}</filename>.
9529 This override allows variables to be set for a single
9530 recipe within configuration (<filename>.conf</filename>)
9531 files.
9532 Here is an example:
9533 <literallayout class='monospaced'>
9534 FOO_pn-myrecipe = "myrecipe-specific value"
9535 </literallayout>
9536 <note><title>Tip</title>
9537 An easy way to see what overrides apply is to search for
9538 <filename>OVERRIDES</filename> in the output of the
9539 <filename>bitbake -e</filename> command.
9540 See the
9541 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
9542 section in the Yocto Project Development Tasks
9543 Manual for more information.
9544 </note>
9545 </para>
9546 </glossdef>
9547 </glossentry>
9548 </glossdiv>
9549
9550 <glossdiv id='var-glossary-p'><title>P</title>
9551
9552 <glossentry id='var-P'><glossterm>P</glossterm>
9553 <info>
9554 P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."
9555 </info>
9556 <glossdef>
9557 <para role="glossdeffirst">
9558 The recipe name and version.
9559 <filename>P</filename> is comprised of the following:
9560 <literallayout class='monospaced'>
9561 ${PN}-${PV}
9562 </literallayout>
9563 </para>
9564 </glossdef>
9565 </glossentry>
9566
9567 <glossentry id='var-PACKAGE_ADD_METADATA'><glossterm>PACKAGE_ADD_METADATA</glossterm>
9568 <info>
9569 PACKAGE_ADD_METADATA[doc] = "This variable defines additional metadata to add to packages."
9570 </info>
9571 <glossdef>
9572 <para role="glossdeffirst">
9573<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9574 This variable defines additional metdata to add to packages.
9575 </para>
9576
9577 <para>
9578 You may find you need to inject additional metadata into
9579 packages. This variable allows you to do that by setting
9580 the injected data as the value. Multiple fields can be
9581 added by splitting the content with the literal separator
9582 "\n".
9583 </para>
9584
9585 <para>
9586 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to
9587 the variable to do package type specific settings. It can
9588 also be made package specific by using the package name as
9589 a suffix.
9590 </para>
9591
9592 <para>
9593 You can find out more about applying this variable in
9594 the
9595 "<ulink url='&YOCTO_DOCS_DEV_URL;#adding-custom-metadata-to-packages'>Adding custom metadata to packages</ulink>"
9596 section in the Yocto Project Development Tasks Manual.
9597 </para>
9598 </glossdef>
9599 </glossentry>
9600
9601 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
9602 <info>
9603 PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."
9604 </info>
9605 <glossdef>
9606 <para role="glossdeffirst">
9607 The architecture of the resulting package or packages.
9608 </para>
9609
9610 <para>
9611 By default, the value of this variable is set to
9612 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
9613 when building for the target,
9614 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>
9615 when building for the
9616 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
9617 for the SDK.
9618 <note>
9619 See
9620 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>
9621 for more information.
9622 </note>
9623 However, if your recipe's output packages are built
9624 specific to the target machine rather than generally for
9625 the architecture of the machine, you should set
9626 <filename>PACKAGE_ARCH</filename> to the value of
9627 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
9628 in the recipe as follows:
9629 <literallayout class='monospaced'>
9630 PACKAGE_ARCH = "${MACHINE_ARCH}"
9631 </literallayout>
9632 </para>
9633 </glossdef>
9634 </glossentry>
9635
9636 <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
9637 <info>
9638 PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."
9639 </info>
9640 <glossdef>
9641 <para role="glossdeffirst">
9642 Specifies a list of architectures compatible with
9643 the target machine.
9644 This variable is set automatically and should not
9645 normally be hand-edited.
9646 Entries are separated using spaces and listed in order
9647 of priority.
9648 The default value for
9649 <filename>PACKAGE_ARCHS</filename> is "all any noarch
9650 ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
9651 </para>
9652 </glossdef>
9653 </glossentry>
9654
9655 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
9656 <info>
9657 PACKAGE_BEFORE_PN[doc] = "Enables easily adding packages to PACKAGES before ${PN} so that the packages can pick up files that would normally be included in the default package."
9658 </info>
9659 <glossdef>
9660 <para role="glossdeffirst">
9661 Enables easily adding packages to
9662 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
9663 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
9664 so that those added packages can pick up files that would normally be
9665 included in the default package.
9666 </para>
9667 </glossdef>
9668 </glossentry>
9669
9670 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
9671 <info>
9672 PACKAGE_CLASSES[doc] = "This variable specifies the package manager to use when packaging data. It is set in the conf/local.conf file in the Build Directory."
9673 </info>
9674 <glossdef>
9675 <para role="glossdeffirst">
9676 This variable, which is set in the
9677 <filename>local.conf</filename> configuration file found in
9678 the <filename>conf</filename> folder of the
9679 <link linkend='build-directory'>Build Directory</link>,
9680 specifies the package manager the OpenEmbedded build system
9681 uses when packaging data.
9682 </para>
9683
9684 <para>
9685 You can provide one or more of the following arguments for
9686 the variable:
9687 <literallayout class='monospaced'>
9688 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
9689 </literallayout>
9690 <note><title>Warning</title>
9691 While it is a legal option, the
9692 <filename>package_tar</filename> class has limited
9693 functionality due to no support for package
9694 dependencies by that backend.
9695 Therefore, it is recommended that you do not use it.
9696 </note>
9697 The build system uses only the first argument in the list
9698 as the package manager when creating your image or SDK.
9699 However, packages will be created using any additional
9700 packaging classes you specify.
9701 For example, if you use the following in your
9702 <filename>local.conf</filename> file:
9703 <literallayout class='monospaced'>
9704 PACKAGE_CLASSES ?= "package_ipk"
9705 </literallayout>
9706 The OpenEmbedded build system uses the IPK package manager
9707 to create your image or SDK.
9708 </para>
9709
9710 <para>
9711 For information on packaging and build performance effects
9712 as a result of the package manager in use, see the
9713 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
9714 section.
9715 </para>
9716 </glossdef>
9717 </glossentry>
9718
9719 <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>
9720 <info>
9721 PACKAGE_DEBUG_SPLIT_STYLE[doc] = "Determines how to split up the binary and debug information when creating *-dbg packages to be used with the GNU Project Debugger (GDB)."
9722 </info>
9723 <glossdef>
9724 <para role="glossdeffirst">
9725 Determines how to split up the binary and debug information
9726 when creating <filename>*-dbg</filename> packages to be
9727 used with the GNU Project Debugger (GDB).
9728 </para>
9729
9730 <para>
9731 With the
9732 <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,
9733 you can control where debug information, which can include
9734 or exclude source files, is stored:
9735 <itemizedlist>
9736 <listitem><para>
9737 ".debug": Debug symbol files are placed next
9738 to the binary in a <filename>.debug</filename>
9739 directory on the target.
9740 For example, if a binary is installed into
9741 <filename>/bin</filename>, the corresponding debug
9742 symbol files are installed in
9743 <filename>/bin/.debug</filename>.
9744 Source files are placed in
9745 <filename>/usr/src/debug</filename>.
9746 </para></listitem>
9747 <listitem><para>
9748 "debug-file-directory": Debug symbol files are
9749 placed under <filename>/usr/lib/debug</filename>
9750 on the target, and separated by the path from where
9751 the binary is installed.
9752 For example, if a binary is installed in
9753 <filename>/bin</filename>, the corresponding debug
9754 symbols are installed in
9755 <filename>/usr/lib/debug/bin</filename>.
9756 Source files are placed in
9757 <filename>/usr/src/debug</filename>.
9758 </para></listitem>
9759 <listitem><para>
9760 "debug-without-src": The same behavior as
9761 ".debug" previously described with the exception
9762 that no source files are installed.
9763 </para></listitem>.
9764 <listitem><para>
9765 "debug-with-srcpkg": The same behavior as
9766 ".debug" previously described with the exception
9767 that all source files are placed in a separate
9768 <filename>*-src</filename> pkg.
9769 This is the default behavior.
9770 </para></listitem>
9771 </itemizedlist>
9772 </para>
9773
9774 <para>
9775 You can find out more about debugging using GDB by reading
9776 the
9777 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
9778 section in the Yocto Project Development Tasks Manual.
9779 </para>
9780 </glossdef>
9781 </glossentry>
9782
9783 <glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>
9784 <info>
9785 PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."
9786 </info>
9787 <glossdef>
9788 <para role="glossdeffirst">
9789 Prevents specific packages from being installed when
9790 you are installing complementary packages.
9791 </para>
9792
9793 <para>
9794 You might find that you want to prevent installing certain
9795 packages when you are installing complementary packages.
9796 For example, if you are using
9797 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
9798 to install <filename>dev-pkgs</filename>, you might not want
9799 to install all packages from a particular multilib.
9800 If you find yourself in this situation, you can use the
9801 <filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable
9802 to specify regular expressions to match the packages you
9803 want to exclude.
9804 </para>
9805 </glossdef>
9806 </glossentry>
9807
9808 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
9809 <info>
9810 PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."
9811 </info>
9812 <glossdef>
9813 <para role="glossdeffirst">
9814 Lists packages that should not be installed into an image.
9815 For example:
9816 <literallayout class='monospaced'>
9817 PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
9818 </literallayout>
9819 </para>
9820
9821 <para>
9822 You can set this variable globally in your
9823 <filename>local.conf</filename> file or you can attach it to
9824 a specific image recipe by using the recipe name override:
9825 <literallayout class='monospaced'>
9826 PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
9827 </literallayout>
9828 </para>
9829
9830 <para>
9831 If you choose to not install
9832 a package using this variable and some other package is
9833 dependent on it (i.e. listed in a recipe's
9834 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
9835 variable), the OpenEmbedded build system generates a fatal
9836 installation error.
9837 Because the build system halts the process with a fatal
9838 error, you can use the variable with an iterative
9839 development process to remove specific components from a
9840 system.
9841 </para>
9842
9843 <para>
9844 Support for this variable exists only when using the
9845 IPK and RPM packaging backend.
9846 Support does not exist for DEB.
9847 </para>
9848
9849 <para>
9850 See the
9851 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
9852 and the
9853 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
9854 variables for related information.
9855 </para>
9856 </glossdef>
9857 </glossentry>
9858
9859 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
9860 <info>
9861 PACKAGE_EXTRA_ARCHS[doc] = "Specifies the list of architectures compatible with the device CPU. This variable is useful when you build for several different devices that use miscellaneous processors."
9862 </info>
9863 <glossdef>
9864 <para role="glossdeffirst">
9865 Specifies the list of architectures compatible with the device CPU.
9866 This variable is useful when you build for several different devices that use
9867 miscellaneous processors such as XScale and ARM926-EJS.
9868 </para>
9869 </glossdef>
9870 </glossentry>
9871
9872 <glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>
9873 <info>
9874 PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."
9875 </info>
9876 <glossdef>
9877 <para role="glossdeffirst">
9878 Optionally specifies the package architectures used as
9879 part of the package feed URIs during the build.
9880 When used, the <filename>PACKAGE_FEED_ARCHS</filename>
9881 variable is appended to the final package feed URI, which
9882 is constructed using the
9883 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
9884 and
9885 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>
9886 variables.
9887 <note><title>Tip</title>
9888 You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>
9889 variable to whitelist specific package architectures.
9890 If you do not need to whitelist specific architectures,
9891 which is a common case, you can omit this variable.
9892 Omitting the variable results in all available
9893 architectures for the current machine being included
9894 into remote package feeds.
9895 </note>
9896 </para>
9897
9898 <para>
9899 Consider the following example where the
9900 <filename>PACKAGE_FEED_URIS</filename>,
9901 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
9902 <filename>PACKAGE_FEED_ARCHS</filename> variables are
9903 defined in your <filename>local.conf</filename> file:
9904 <literallayout class='monospaced'>
9905 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
9906 https://example.com/packagerepos/updates"
9907 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
9908 PACKAGE_FEED_ARCHS = "all core2-64"
9909 </literallayout>
9910 Given these settings, the resulting package feeds are
9911 as follows:
9912 <literallayout class='monospaced'>
9913 https://example.com/packagerepos/release/rpm/all
9914 https://example.com/packagerepos/release/rpm/core2-64
9915 https://example.com/packagerepos/release/rpm-dev/all
9916 https://example.com/packagerepos/release/rpm-dev/core2-64
9917 https://example.com/packagerepos/updates/rpm/all
9918 https://example.com/packagerepos/updates/rpm/core2-64
9919 https://example.com/packagerepos/updates/rpm-dev/all
9920 https://example.com/packagerepos/updates/rpm-dev/core2-64
9921 </literallayout>
9922 </para>
9923 </glossdef>
9924 </glossentry>
9925
9926 <glossentry id='var-PACKAGE_FEED_BASE_PATHS'><glossterm>PACKAGE_FEED_BASE_PATHS</glossterm>
9927 <info>
9928 PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."
9929 </info>
9930 <glossdef>
9931 <para role="glossdeffirst">
9932 Specifies the base path used when constructing package feed
9933 URIs.
9934 The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable
9935 makes up the middle portion of a package feed URI used
9936 by the OpenEmbedded build system.
9937 The base path lies between the
9938 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
9939 and
9940 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
9941 variables.
9942 </para>
9943
9944 <para>
9945 Consider the following example where the
9946 <filename>PACKAGE_FEED_URIS</filename>,
9947 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
9948 <filename>PACKAGE_FEED_ARCHS</filename> variables are
9949 defined in your <filename>local.conf</filename> file:
9950 <literallayout class='monospaced'>
9951 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
9952 https://example.com/packagerepos/updates"
9953 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
9954 PACKAGE_FEED_ARCHS = "all core2-64"
9955 </literallayout>
9956 Given these settings, the resulting package feeds are
9957 as follows:
9958 <literallayout class='monospaced'>
9959 https://example.com/packagerepos/release/rpm/all
9960 https://example.com/packagerepos/release/rpm/core2-64
9961 https://example.com/packagerepos/release/rpm-dev/all
9962 https://example.com/packagerepos/release/rpm-dev/core2-64
9963 https://example.com/packagerepos/updates/rpm/all
9964 https://example.com/packagerepos/updates/rpm/core2-64
9965 https://example.com/packagerepos/updates/rpm-dev/all
9966 https://example.com/packagerepos/updates/rpm-dev/core2-64
9967 </literallayout>
9968 </para>
9969 </glossdef>
9970 </glossentry>
9971
9972 <glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>
9973 <info>
9974 PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."
9975 </info>
9976 <glossdef>
9977 <para role="glossdeffirst">
9978 Specifies the front portion of the package feed URI
9979 used by the OpenEmbedded build system.
9980 Each final package feed URI is comprised of
9981 <filename>PACKAGE_FEED_URIS</filename>,
9982 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>,
9983 and
9984 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
9985 variables.
9986 </para>
9987
9988 <para>
9989 Consider the following example where the
9990 <filename>PACKAGE_FEED_URIS</filename>,
9991 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
9992 <filename>PACKAGE_FEED_ARCHS</filename> variables are
9993 defined in your <filename>local.conf</filename> file:
9994 <literallayout class='monospaced'>
9995 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
9996 https://example.com/packagerepos/updates"
9997 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
9998 PACKAGE_FEED_ARCHS = "all core2-64"
9999 </literallayout>
10000 Given these settings, the resulting package feeds are
10001 as follows:
10002 <literallayout class='monospaced'>
10003 https://example.com/packagerepos/release/rpm/all
10004 https://example.com/packagerepos/release/rpm/core2-64
10005 https://example.com/packagerepos/release/rpm-dev/all
10006 https://example.com/packagerepos/release/rpm-dev/core2-64
10007 https://example.com/packagerepos/updates/rpm/all
10008 https://example.com/packagerepos/updates/rpm/core2-64
10009 https://example.com/packagerepos/updates/rpm-dev/all
10010 https://example.com/packagerepos/updates/rpm-dev/core2-64
10011 </literallayout>
10012 </para>
10013 </glossdef>
10014 </glossentry>
10015
10016 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
10017 <info>
10018 PACKAGE_INSTALL[doc] = "List of the packages to be installed into the image. The variable is generally not user-defined and uses IMAGE_INSTALL as part of the list."
10019 </info>
10020 <glossdef>
10021 <para role="glossdeffirst">
10022 The final list of packages passed to the package manager
10023 for installation into the image.
10024 </para>
10025
10026 <para>
10027 Because the package manager controls actual installation
10028 of all packages, the list of packages passed using
10029 <filename>PACKAGE_INSTALL</filename> is not the final list
10030 of packages that are actually installed.
10031 This variable is internal to the image construction
10032 code.
10033 Consequently, in general, you should use the
10034 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
10035 variable to specify packages for installation.
10036 The exception to this is when working with
10037 the
10038 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
10039 image.
10040 When working with an initial RAM filesystem (initramfs)
10041 image, use the <filename>PACKAGE_INSTALL</filename>
10042 variable.
10043 For information on creating an initramfs, see the
10044 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
10045 section in the Yocto Project Development Tasks Manual.
10046 </para>
10047 </glossdef>
10048 </glossentry>
10049
10050 <glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm>
10051 <info>
10052 PACKAGE_INSTALL_ATTEMPTONLY[doc] = "List of packages attempted to be installed when creating an image. If a listed package fails to install, the build system does not generate an error. This variable is generally not user-defined."
10053 </info>
10054 <glossdef>
10055 <para role="glossdeffirst">
10056 Specifies a list of packages the OpenEmbedded build
10057 system attempts to install when creating an image.
10058 If a listed package fails to install, the build system
10059 does not generate an error.
10060 This variable is generally not user-defined.
10061 </para>
10062 </glossdef>
10063 </glossentry>
10064
10065 <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
10066 <info>
10067 PACKAGE_PREPROCESS_FUNCS[doc] = "Specifies a list of functions run to pre-process the PKGD directory prior to splitting the files out to individual packages."
10068 </info>
10069 <glossdef>
10070 <para role="glossdeffirst">
10071 Specifies a list of functions run to pre-process the
10072 <link linkend='var-PKGD'><filename>PKGD</filename></link>
10073 directory prior to splitting the files out to individual
10074 packages.
10075 </para>
10076 </glossdef>
10077 </glossentry>
10078
10079 <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>
10080 <info>
10081 PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."
10082 </info>
10083 <glossdef>
10084 <para role="glossdeffirst">
10085 Specifies a list of dependencies for post-installation and
10086 pre-installation scripts on native/cross tools.
10087 If your post-installation or pre-installation script can
10088 execute at rootfs creation time rather than on the
10089 target but depends on a native tool in order to execute,
10090 you need to list the tools in
10091 <filename>PACKAGE_WRITE_DEPS</filename>.
10092 </para>
10093
10094 <para>
10095 For information on running post-installation scripts, see
10096 the
10097 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
10098 section in the Yocto Project Development Tasks Manual.
10099 </para>
10100 </glossdef>
10101 </glossentry>
10102
10103 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
10104 <info>
10105 PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."
10106 </info>
10107 <glossdef>
10108 <para role="glossdeffirst">
10109 This variable provides a means of enabling or disabling
10110 features of a recipe on a per-recipe basis.
10111 <filename>PACKAGECONFIG</filename> blocks are defined
10112 in recipes when you specify features and then arguments
10113 that define feature behaviors.
10114 Here is the basic block structure (broken over multiple
10115 lines for readability):
10116 <literallayout class='monospaced'>
10117 PACKAGECONFIG ??= "f1 f2 f3 ..."
10118 PACKAGECONFIG[f1] = "\
10119 --with-f1, \
10120 --without-f1, \
10121 build-deps-for-f1, \
10122 runtime-deps-for-f1, \
10123 runtime-recommends-for-f1, \
10124 packageconfig-conflicts-for-f1 \
10125 "
10126 PACKAGECONFIG[f2] = "\
10127 ... and so on and so on ...
10128 </literallayout>
10129 </para>
10130
10131 <para>
10132 The <filename>PACKAGECONFIG</filename>
10133 variable itself specifies a space-separated list of the
10134 features to enable.
10135 Following the features, you can determine the behavior of
10136 each feature by providing up to six order-dependent
10137 arguments, which are separated by commas.
10138 You can omit any argument you like but must retain the
10139 separating commas.
10140 The order is important and specifies the following:
10141 <orderedlist>
10142 <listitem><para>Extra arguments
10143 that should be added to the configure script
10144 argument list
10145 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
10146 or
10147 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>)
10148 if the feature is enabled.</para></listitem>
10149 <listitem><para>Extra arguments
10150 that should be added to <filename>EXTRA_OECONF</filename>
10151 or <filename>PACKAGECONFIG_CONFARGS</filename>
10152 if the feature is disabled.
10153 </para></listitem>
10154 <listitem><para>Additional build dependencies
10155 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
10156 that should be added if the feature is enabled.
10157 </para></listitem>
10158 <listitem><para>Additional runtime dependencies
10159 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10160 that should be added if the feature is enabled.
10161 </para></listitem>
10162 <listitem><para>Additional runtime recommendations
10163 (<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
10164 that should be added if the feature is enabled.
10165 </para></listitem>
10166 <listitem><para>Any conflicting (that is, mutually
10167 exclusive) <filename>PACKAGECONFIG</filename>
10168 settings for this feature.
10169 </para></listitem>
10170 </orderedlist>
10171 </para>
10172
10173 <para>
10174 Consider the following
10175 <filename>PACKAGECONFIG</filename> block taken from the
10176 <filename>librsvg</filename> recipe.
10177 In this example the feature is <filename>gtk</filename>,
10178 which has three arguments that determine the feature's
10179 behavior.
10180 <literallayout class='monospaced'>
10181 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
10182 </literallayout>
10183 The <filename>--with-gtk3</filename> and
10184 <filename>gtk+3</filename> arguments apply only if
10185 the feature is enabled.
10186 In this case, <filename>--with-gtk3</filename> is
10187 added to the configure script argument list and
10188 <filename>gtk+3</filename> is added to
10189 <filename>DEPENDS</filename>.
10190 On the other hand, if the feature is disabled say through
10191 a <filename>.bbappend</filename> file in another layer, then
10192 the second argument <filename>--without-gtk3</filename> is
10193 added to the configure script instead.
10194 </para>
10195
10196 <para>
10197 The basic <filename>PACKAGECONFIG</filename> structure
10198 previously described holds true regardless of whether you
10199 are creating a block or changing a block.
10200 When creating a block, use the structure inside your
10201 recipe.
10202 </para>
10203
10204 <para>
10205 If you want to change an existing
10206 <filename>PACKAGECONFIG</filename> block, you can do so
10207 one of two ways:
10208 <itemizedlist>
10209 <listitem><para><emphasis>Append file:</emphasis>
10210 Create an append file named
10211 <replaceable>recipename</replaceable><filename>.bbappend</filename>
10212 in your layer and override the value of
10213 <filename>PACKAGECONFIG</filename>.
10214 You can either completely override the variable:
10215 <literallayout class='monospaced'>
10216 PACKAGECONFIG = "f4 f5"
10217 </literallayout>
10218 Or, you can just append the variable:
10219 <literallayout class='monospaced'>
10220 PACKAGECONFIG_append = " f4"
10221 </literallayout></para></listitem>
10222 <listitem><para><emphasis>Configuration file:</emphasis>
10223 This method is identical to changing the block
10224 through an append file except you edit your
10225 <filename>local.conf</filename> or
10226 <filename><replaceable>mydistro</replaceable>.conf</filename> file.
10227 As with append files previously described,
10228 you can either completely override the variable:
10229 <literallayout class='monospaced'>
10230 PACKAGECONFIG_pn-<replaceable>recipename</replaceable> = "f4 f5"
10231 </literallayout>
10232 Or, you can just amend the variable:
10233 <literallayout class='monospaced'>
10234 PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"
10235 </literallayout></para></listitem>
10236 </itemizedlist>
10237 </para>
10238 </glossdef>
10239 </glossentry>
10240
10241 <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>
10242 <info>
10243 PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from the PACKAGECONFIG setting."
10244 </info>
10245 <glossdef>
10246 <para role="glossdeffirst">
10247 A space-separated list of configuration options generated
10248 from the
10249 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
10250 setting.
10251 </para>
10252
10253 <para>
10254 Classes such as
10255 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
10256 and
10257 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
10258 use <filename>PACKAGECONFIG_CONFARGS</filename> to pass
10259 <filename>PACKAGECONFIG</filename> options to
10260 <filename>configure</filename> and
10261 <filename>cmake</filename>, respectively.
10262 If you are using
10263 <filename>PACKAGECONFIG</filename> but not a class that
10264 handles the <filename>do_configure</filename> task, then
10265 you need to use
10266 <filename>PACKAGECONFIG_CONFARGS</filename> appropriately.
10267 </para>
10268 </glossdef>
10269 </glossentry>
10270
10271 <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>
10272 <info>
10273 PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."
10274 </info>
10275 <glossdef>
10276 <para role="glossdeffirst">
10277 For recipes inheriting the
10278 <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link>
10279 class, setting
10280 <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to
10281 "1" specifies that the normal complementary packages
10282 (i.e. <filename>-dev</filename>,
10283 <filename>-dbg</filename>, and so forth) should not be
10284 automatically created by the
10285 <filename>packagegroup</filename> recipe, which is the
10286 default behavior.
10287 </para>
10288 </glossdef>
10289 </glossentry>
10290
10291 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
10292 <info>
10293 PACKAGES[doc] = "The list of packages the recipe creates."
10294 </info>
10295 <glossdef>
10296 <para role="glossdeffirst">
10297 The list of packages the recipe creates.
10298 The default value is the following:
10299 <literallayout class='monospaced'>
10300 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
10301 </literallayout>
10302 </para>
10303
10304 <para>
10305 During packaging, the
10306 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
10307 task goes through <filename>PACKAGES</filename> and uses
10308 the
10309 <link linkend='var-FILES'><filename>FILES</filename></link>
10310 variable corresponding to each package to assign files to
10311 the package.
10312 If a file matches the <filename>FILES</filename> variable
10313 for more than one package in <filename>PACKAGES</filename>,
10314 it will be assigned to the earliest (leftmost) package.
10315 </para>
10316
10317 <para>
10318 Packages in the variable's list that are empty (i.e. where
10319 none of the patterns in
10320 <filename>FILES_</filename><replaceable>pkg</replaceable>
10321 match any files installed by the
10322 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10323 task) are not generated, unless generation is forced through
10324 the
10325 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
10326 variable.
10327 </para>
10328 </glossdef>
10329 </glossentry>
10330
10331 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
10332 <info>
10333 PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."
10334 </info>
10335 <glossdef>
10336 <para role="glossdeffirst">
10337 A promise that your recipe satisfies runtime dependencies
10338 for optional modules that are found in other recipes.
10339 <filename>PACKAGES_DYNAMIC</filename>
10340 does not actually satisfy the dependencies, it only states that
10341 they should be satisfied.
10342 For example, if a hard, runtime dependency
10343 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10344 of another package is satisfied
10345 at build time through the <filename>PACKAGES_DYNAMIC</filename>
10346 variable, but a package with the module name is never actually
10347 produced, then the other package will be broken.
10348 Thus, if you attempt to include that package in an image,
10349 you will get a dependency failure from the packaging system
10350 during the
10351 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
10352 task.
10353 </para>
10354
10355 <para>
10356 Typically, if there is a chance that such a situation can
10357 occur and the package that is not created is valid
10358 without the dependency being satisfied, then you should use
10359 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
10360 (a soft runtime dependency) instead of
10361 <filename>RDEPENDS</filename>.
10362 </para>
10363
10364 <para>
10365 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
10366 variable when you are splitting packages, see the
10367 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
10368 in the Yocto Project Development Tasks Manual.
10369 </para>
10370 </glossdef>
10371 </glossentry>
10372
10373 <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
10374 <info>
10375 PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."
10376 </info>
10377 <glossdef>
10378 <para role="glossdeffirst">
10379 Specifies a list of functions run to perform additional
10380 splitting of files into individual packages.
10381 Recipes can either prepend to this variable or prepend
10382 to the <filename>populate_packages</filename> function
10383 in order to perform additional package splitting.
10384 In either case, the function should set
10385 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
10386 <link linkend='var-FILES'><filename>FILES</filename></link>,
10387 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10388 and other packaging variables appropriately in order to
10389 perform the desired splitting.
10390 </para>
10391 </glossdef>
10392 </glossentry>
10393
10394 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
10395 <info>
10396 PARALLEL_MAKE[doc] = "Specifies extra options that are passed to the make command during the compile tasks. This variable is usually in the form -j x, where x represents the maximum number of parallel threads make can run."
10397 </info>
10398 <glossdef>
10399 <para role="glossdeffirst">
10400 Extra options passed to the <filename>make</filename>
10401 command during the
10402 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
10403 task in order to specify parallel compilation on the local
10404 build host.
10405 This variable is usually in the form "-j <replaceable>x</replaceable>",
10406 where <replaceable>x</replaceable> represents the maximum
10407 number of parallel threads <filename>make</filename> can
10408 run.
10409 <note><title>Caution</title>
10410 In order for <filename>PARALLEL_MAKE</filename> to be
10411 effective, <filename>make</filename> must be called
10412 with
10413 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10414 An easy way to ensure this is to use the
10415 <filename>oe_runmake</filename> function.
10416 </note>
10417 </para>
10418
10419 <para>
10420 By default, the OpenEmbedded build system automatically
10421 sets this variable to be equal to the number of cores the
10422 build system uses.
10423 <note>
10424 If the software being built experiences dependency
10425 issues during the <filename>do_compile</filename>
10426 task that result in race conditions, you can clear
10427 the <filename>PARALLEL_MAKE</filename> variable within
10428 the recipe as a workaround.
10429 For information on addressing race conditions, see the
10430 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
10431 section in the Yocto Project Development Tasks Manual.
10432 </note>
10433 For single socket systems (i.e. one CPU), you should not
10434 have to override this variable to gain optimal parallelism
10435 during builds.
10436 However, if you have very large systems that employ
10437 multiple physical CPUs, you might want to make sure the
10438 <filename>PARALLEL_MAKE</filename> variable is not
10439 set higher than "-j 20".
10440 </para>
10441
10442 <para>
10443 For more information on speeding up builds, see the
10444 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
10445 section in the Yocto Project Development Tasks Manual.
10446 </para>
10447 </glossdef>
10448 </glossentry>
10449
10450 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
10451 <info>
10452 PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."
10453 </info>
10454 <glossdef>
10455 <para role="glossdeffirst">
10456 Extra options passed to the
10457 <filename>make install</filename> command during the
10458 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10459 task in order to specify parallel installation.
10460 This variable defaults to the value of
10461 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
10462 <note><title>Notes and Cautions</title>
10463 <para>In order for <filename>PARALLEL_MAKEINST</filename>
10464 to be
10465 effective, <filename>make</filename> must be called
10466 with
10467 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10468 An easy way to ensure this is to use the
10469 <filename>oe_runmake</filename> function.</para>
10470
10471 <para>If the software being built experiences
10472 dependency issues during the
10473 <filename>do_install</filename> task that result in
10474 race conditions, you can clear the
10475 <filename>PARALLEL_MAKEINST</filename> variable within
10476 the recipe as a workaround.
10477 For information on addressing race conditions, see the
10478 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
10479 section in the Yocto Project Development Tasks Manual.
10480 </para>
10481 </note>
10482 </para>
10483 </glossdef>
10484 </glossentry>
10485
10486 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
10487 <info>
10488 PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."
10489 </info>
10490 <glossdef>
10491 <para role="glossdeffirst">
10492 Determines the action to take when a patch fails.
10493 You can set this variable to one of two values: "noop" and
10494 "user".
10495 </para>
10496
10497 <para>
10498 The default value of "noop" causes the build to simply fail
10499 when the OpenEmbedded build system cannot successfully
10500 apply a patch.
10501 Setting the value to "user" causes the build system to
10502 launch a shell and places you in the right location so that
10503 you can manually resolve the conflicts.
10504 </para>
10505
10506 <para>
10507 Set this variable in your
10508 <filename>local.conf</filename> file.
10509 </para>
10510 </glossdef>
10511 </glossentry>
10512
10513 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
10514 <info>
10515 PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."
10516 </info>
10517 <glossdef>
10518 <para role="glossdeffirst">
10519 Specifies the utility used to apply patches for a recipe
10520 during the
10521 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
10522 task.
10523 You can specify one of three utilities: "patch", "quilt", or
10524 "git".
10525 The default utility used is "quilt" except for the
10526 quilt-native recipe itself.
10527 Because the quilt tool is not available at the
10528 time quilt-native is being patched, it uses "patch".
10529 </para>
10530
10531 <para>
10532 If you wish to use an alternative patching tool, set the
10533 variable in the recipe using one of the following:
10534 <literallayout class='monospaced'>
10535 PATCHTOOL = "patch"
10536 PATCHTOOL = "quilt"
10537 PATCHTOOL = "git"
10538 </literallayout>
10539 </para>
10540 </glossdef>
10541 </glossentry>
10542
10543 <glossentry id='var-PE'><glossterm>PE</glossterm>
10544 <info>
10545 PE[doc] = "The epoch of the recipe. The default value is '0'. The field is used to make upgrades possible when the versioning scheme changes in some backwards incompatible way."
10546 </info>
10547 <glossdef>
10548 <para role="glossdeffirst">
10549 The epoch of the recipe.
10550 By default, this variable is unset.
10551 The variable is used to make upgrades possible when the
10552 versioning scheme changes in some backwards incompatible
10553 way.
10554 </para>
10555
10556 <para>
10557 <filename>PE</filename> is the default value of the
10558 <link linkend='var-PKGE'><filename>PKGE</filename></link>
10559 variable.
10560 </para>
10561 </glossdef>
10562 </glossentry>
10563
10564 <glossentry id='var-PF'><glossterm>PF</glossterm>
10565 <info>
10566 PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}."
10567 </info>
10568 <glossdef>
10569 <para role="glossdeffirst">
10570 Specifies the recipe or package name and includes all version and revision
10571 numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and
10572 <filename>bash-4.2-r1/</filename>).
10573 This variable is comprised of the following:
10574 <literallayout class='monospaced'>
10575 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
10576 </literallayout>
10577 </para>
10578 </glossdef>
10579 </glossentry>
10580
10581 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
10582 <info>
10583 PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."
10584 </info>
10585 <glossdef>
10586 <para role="glossdeffirst">
10587 When inheriting the
10588 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
10589 class, this variable identifies packages that contain
10590 the pixbuf loaders used with
10591 <filename>gdk-pixbuf</filename>.
10592 By default, the <filename>pixbufcache</filename> class
10593 assumes that the loaders are in the recipe's main package
10594 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
10595 Use this variable if the loaders you need are in a package
10596 other than that main package.
10597 </para>
10598 </glossdef>
10599 </glossentry>
10600
10601 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
10602 <info>
10603 PKG[doc] = "The name of the resulting package created by the OpenEmbedded build system. When you use this variable, you must use a package name override."
10604 </info>
10605 <glossdef>
10606 <para role="glossdeffirst">
10607 The name of the resulting package created by the
10608 OpenEmbedded build system.
10609 <note>
10610 When using the <filename>PKG</filename> variable, you
10611 must use a package name override.
10612 </note>
10613 </para>
10614
10615 <para>
10616 For example, when the
10617 <link linkend='ref-classes-debian'><filename>debian</filename></link>
10618 class renames the output package, it does so by setting
10619 <filename>PKG_<replaceable>packagename</replaceable></filename>.
10620 </para>
10621 </glossdef>
10622 </glossentry>
10623
10624 <glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>
10625 <info>
10626 PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."
10627 </info>
10628 <glossdef>
10629 <para role="glossdeffirst">
10630 The path to <filename>pkg-config</filename> files for the
10631 current build context.
10632 <filename>pkg-config</filename> reads this variable
10633 from the environment.
10634 </para>
10635 </glossdef>
10636 </glossentry>
10637
10638 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
10639 <info>
10640 PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages."
10641 </info>
10642 <glossdef>
10643 <para role="glossdeffirst">
10644 Points to the destination directory for files to be
10645 packaged before they are split into individual packages.
10646 This directory defaults to the following:
10647 <literallayout class='monospaced'>
10648 ${WORKDIR}/package
10649 </literallayout>
10650 </para>
10651
10652 <para>
10653 Do not change this default.
10654 </para>
10655 </glossdef>
10656 </glossentry>
10657
10658 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
10659 <info>
10660 PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."
10661 </info>
10662 <glossdef>
10663 <para role="glossdeffirst">
10664 Points to a shared, global-state directory that holds data
10665 generated during the packaging process.
10666 During the packaging process, the
10667 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10668 task packages data for each recipe and installs it into
10669 this temporary, shared area.
10670 This directory defaults to the following, which you should
10671 not change:
10672 <literallayout class='monospaced'>
10673 ${STAGING_DIR_HOST}/pkgdata
10674 </literallayout>
10675 For examples of how this data is used, see the
10676 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10677 section in the Yocto Project Overview and Concepts Manual
10678 and the
10679 "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
10680 section in the Yocto Project Development Tasks Manual.
10681 For more information on the shared, global-state directory,
10682 see
10683 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
10684 </para>
10685 </glossdef>
10686 </glossentry>
10687
10688 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
10689 <info>
10690 PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."
10691 </info>
10692 <glossdef>
10693 <para role="glossdeffirst">
10694 Points to the parent directory for files to be packaged
10695 after they have been split into individual packages.
10696 This directory defaults to the following:
10697 <literallayout class='monospaced'>
10698 ${WORKDIR}/packages-split
10699 </literallayout>
10700 </para>
10701
10702 <para>
10703 Under this directory, the build system creates
10704 directories for each package specified in
10705 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
10706 Do not change this default.
10707 </para>
10708 </glossdef>
10709 </glossentry>
10710
10711 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
10712 <info>
10713 PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."
10714 </info>
10715 <glossdef>
10716 <para role="glossdeffirst">
10717 Points to a temporary work area where the
10718 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
10719 task saves package metadata.
10720 The <filename>PKGDESTWORK</filename> location defaults to
10721 the following:
10722 <literallayout class='monospaced'>
10723 ${WORKDIR}/pkgdata
10724 </literallayout>
10725 Do not change this default.
10726 </para>
10727
10728 <para>
10729 The
10730 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10731 task copies the package metadata from
10732 <filename>PKGDESTWORK</filename> to
10733 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
10734 to make it available globally.
10735 </para>
10736 </glossdef>
10737 </glossentry>
10738
10739 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
10740 <info>
10741 PKGE[doc] = "The epoch of the package(s) built by the recipe."
10742 </info>
10743 <glossdef>
10744 <para role="glossdeffirst">
10745 The epoch of the package(s) built by the recipe.
10746 By default, <filename>PKGE</filename> is set to
10747 <link linkend='var-PE'><filename>PE</filename></link>.
10748 </para>
10749 </glossdef>
10750 </glossentry>
10751
10752 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
10753 <info>
10754 PKGR[doc] = "The revision of the package(s) built by the recipe."
10755 </info>
10756 <glossdef>
10757 <para role="glossdeffirst">
10758 The revision of the package(s) built by the recipe.
10759 By default, <filename>PKGR</filename> is set to
10760 <link linkend='var-PR'><filename>PR</filename></link>.
10761 </para>
10762 </glossdef>
10763 </glossentry>
10764
10765 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
10766 <info>
10767 PKGV[doc] = "The version of the package(s) built by the recipe."
10768 </info>
10769 <glossdef>
10770 <para role="glossdeffirst">
10771 The version of the package(s) built by the
10772 recipe.
10773 By default, <filename>PKGV</filename> is set to
10774 <link linkend='var-PV'><filename>PV</filename></link>.
10775 </para>
10776 </glossdef>
10777 </glossentry>
10778
10779 <glossentry id='var-PN'><glossterm>PN</glossterm>
10780 <info>
10781 PN[doc] = "PN refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package."
10782 </info>
10783 <glossdef>
10784 <para role="glossdeffirst">
10785 This variable can have two separate functions depending on the context: a recipe
10786 name or a resulting package name.
10787 </para>
10788
10789 <para>
10790 <filename>PN</filename> refers to a recipe name in the context of a file used
10791 by the OpenEmbedded build system as input to create a package.
10792 The name is normally extracted from the recipe file name.
10793 For example, if the recipe is named
10794 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
10795 will be "expat".
10796 </para>
10797
10798 <para>
10799 The variable refers to a package name in the context of a file created or produced by the
10800 OpenEmbedded build system.
10801 </para>
10802
10803 <para>
10804 If applicable, the <filename>PN</filename> variable also contains any special
10805 suffix or prefix.
10806 For example, using <filename>bash</filename> to build packages for the native
10807 machine, <filename>PN</filename> is <filename>bash-native</filename>.
10808 Using <filename>bash</filename> to build packages for the target and for Multilib,
10809 <filename>PN</filename> would be <filename>bash</filename> and
10810 <filename>lib64-bash</filename>, respectively.
10811 </para>
10812 </glossdef>
10813 </glossentry>
10814
10815 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
10816 <info>
10817 PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."
10818 </info>
10819 <glossdef>
10820 <para role="glossdeffirst">
10821 Lists recipes you do not want the OpenEmbedded build system
10822 to build.
10823 This variable works in conjunction with the
10824 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
10825 class, which is inherited globally.
10826 </para>
10827
10828 <para>
10829 To prevent a recipe from being built, use the
10830 <filename>PNBLACKLIST</filename> variable in your
10831 <filename>local.conf</filename> file.
10832 Here is an example that prevents
10833 <filename>myrecipe</filename> from being built:
10834 <literallayout class='monospaced'>
10835 PNBLACKLIST[myrecipe] = "Not supported by our organization."
10836 </literallayout>
10837 </para>
10838 </glossdef>
10839 </glossentry>
10840
10841 <glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
10842 <info>
10843 POPULATE_SDK_POST_HOST_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created host part of the SDK."
10844 </info>
10845 <glossdef>
10846 <para role="glossdeffirst">
10847 Specifies a list of functions to call once the
10848 OpenEmbedded build system has created the host part of
10849 the SDK.
10850 You can specify functions separated by semicolons:
10851 <literallayout class='monospaced'>
10852 POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "
10853 </literallayout>
10854 </para>
10855
10856 <para>
10857 If you need to pass the SDK path to a command
10858 within a function, you can use
10859 <filename>${SDK_DIR}</filename>, which points to
10860 the parent directory used by the OpenEmbedded build
10861 system when creating SDK output.
10862 See the
10863 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
10864 variable for more information.
10865 </para>
10866 </glossdef>
10867 </glossentry>
10868
10869 <glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>
10870 <info>
10871 POPULATE_SDK_POST_TARGET_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created target part of the SDK."
10872 </info>
10873 <glossdef>
10874 <para role="glossdeffirst">
10875 Specifies a list of functions to call once the
10876 OpenEmbedded build system has created the target part of
10877 the SDK.
10878 You can specify functions separated by semicolons:
10879 <literallayout class='monospaced'>
10880 POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "
10881 </literallayout>
10882 </para>
10883
10884 <para>
10885 If you need to pass the SDK path to a command
10886 within a function, you can use
10887 <filename>${SDK_DIR}</filename>, which points to
10888 the parent directory used by the OpenEmbedded build
10889 system when creating SDK output.
10890 See the
10891 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
10892 variable for more information.
10893 </para>
10894 </glossdef>
10895 </glossentry>
10896
10897 <glossentry id='var-PR'><glossterm>PR</glossterm>
10898 <info>
10899 PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."
10900 </info>
10901 <glossdef>
10902 <para role="glossdeffirst">
10903 The revision of the recipe. The default value for this
10904 variable is "r0".
10905 Subsequent revisions of the recipe conventionally have the
10906 values "r1", "r2", and so forth.
10907 When
10908 <link linkend='var-PV'><filename>PV</filename></link>
10909 increases, <filename>PR</filename> is conventionally reset
10910 to "r0".
10911 <note>
10912 The OpenEmbedded build system does not need the aid of
10913 <filename>PR</filename> to know when to rebuild a
10914 recipe.
10915 The build system uses the task
10916 <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>
10917 along with the
10918 <link linkend='structure-build-tmp-stamps'>stamp</link>
10919 and
10920 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>
10921 mechanisms.
10922 </note>
10923 The <filename>PR</filename> variable primarily becomes
10924 significant when a package manager dynamically installs
10925 packages on an already built image.
10926 In this case, <filename>PR</filename>, which is the default
10927 value of
10928 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
10929 helps the package manager distinguish which package is the
10930 most recent one in cases where many packages have the same
10931 <filename>PV</filename> (i.e. <filename>PKGV</filename>).
10932 A component having many packages with the same
10933 <filename>PV</filename> usually means that the packages all
10934 install the same upstream version, but with later
10935 (<filename>PR</filename>) version packages including
10936 packaging fixes.
10937 <note>
10938 <filename>PR</filename> does not need to be increased
10939 for changes that do not change the package contents or
10940 metadata.
10941 </note>
10942 Because manually managing <filename>PR</filename> can be
10943 cumbersome and error-prone, an automated solution exists.
10944 See the
10945 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
10946 section in the Yocto Project Development Tasks Manual
10947 for more information.
10948 </para>
10949 </glossdef>
10950 </glossentry>
10951
10952 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
10953 <info>
10954 PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."
10955 </info>
10956 <glossdef>
10957 <para role="glossdeffirst">
10958 If multiple recipes provide the same item, this variable
10959 determines which recipe is preferred and thus provides
10960 the item (i.e. the preferred provider).
10961 You should always suffix this variable with the name of the
10962 provided item.
10963 And, you should define the variable using the preferred
10964 recipe's name
10965 (<link linkend='var-PN'><filename>PN</filename></link>).
10966 Here is a common example:
10967 <literallayout class='monospaced'>
10968 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
10969 </literallayout>
10970 In the previous example, multiple recipes are providing
10971 "virtual/kernel".
10972 The <filename>PREFERRED_PROVIDER</filename> variable is
10973 set with the name (<filename>PN</filename>) of the recipe
10974 you prefer to provide "virtual/kernel".
10975 </para>
10976
10977 <para>
10978 Following are more examples:
10979 <literallayout class='monospaced'>
10980 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
10981 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
10982 </literallayout>
10983 For more information, see the
10984 "<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"
10985 section in the Yocto Project Development Tasks Manual.
10986 <note>
10987 If you use a <filename>virtual/*</filename> item
10988 with <filename>PREFERRED_PROVIDER</filename>, then any
10989 recipe that
10990 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
10991 that item but is not selected (defined) by
10992 <filename>PREFERRED_PROVIDER</filename> is prevented
10993 from building, which is usually desirable since this
10994 mechanism is designed to select between mutually
10995 exclusive alternative providers.
10996 </note>
10997 </para>
10998 </glossdef>
10999 </glossentry>
11000
11001 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
11002 <info>
11003 PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."
11004 </info>
11005 <glossdef>
11006 <para role="glossdeffirst">
11007 If multiple versions of recipes exist, this
11008 variable determines which version is given preference.
11009 You must always suffix the variable with the
11010 <link linkend='var-PN'><filename>PN</filename></link>
11011 you want to select, and you should set the
11012 <link linkend='var-PV'><filename>PV</filename></link>
11013 accordingly for precedence.
11014 </para>
11015
11016 <para>
11017 The <filename>PREFERRED_VERSION</filename> variable
11018 supports limited wildcard use through the
11019 "<filename>%</filename>" character.
11020 You can use the character to match any number of
11021 characters, which can be useful when specifying versions
11022 that contain long revision numbers that potentially change.
11023 Here are two examples:
11024 <literallayout class='monospaced'>
11025 PREFERRED_VERSION_python = "3.4.0"
11026 PREFERRED_VERSION_linux-yocto = "5.0%"
11027 </literallayout>
11028 <note><title>Important</title>
11029 The use of the "<filename>%</filename>" character
11030 is limited in that it only works at the end of the
11031 string.
11032 You cannot use the wildcard character in any other
11033 location of the string.
11034 </note>
11035 </para>
11036
11037 <para>
11038 The specified version is matched against
11039 <link linkend='var-PV'><filename>PV</filename></link>,
11040 which does not necessarily match the version part of
11041 the recipe's filename.
11042 For example, consider two recipes
11043 <filename>foo_1.2.bb</filename> and
11044 <filename>foo_git.bb</filename> where
11045 <filename>foo_git.bb</filename> contains the following
11046 assignment:
11047 <literallayout class='monospaced'>
11048 PV = "1.1+git${SRCPV}"
11049 </literallayout>
11050 In this case, the correct way to select
11051 <filename>foo_git.bb</filename> is by using an
11052 assignment such as the following:
11053 <literallayout class='monospaced'>
11054 PREFERRED_VERSION_foo = "1.1+git%"
11055 </literallayout>
11056 Compare that previous example against the following
11057 incorrect example, which does not work:
11058 <literallayout class='monospaced'>
11059 PREFERRED_VERSION_foo = "git"
11060 </literallayout>
11061 </para>
11062
11063 <para>
11064 Sometimes the <filename>PREFERRED_VERSION</filename>
11065 variable can be set by configuration files in a way that
11066 is hard to change.
11067 You can use
11068 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
11069 to set a machine-specific override.
11070 Here is an example:
11071 <literallayout class='monospaced'>
11072 PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%"
11073 </literallayout>
11074 Although not recommended, worst case, you can also use the
11075 "forcevariable" override, which is the strongest override
11076 possible.
11077 Here is an example:
11078 <literallayout class='monospaced'>
11079 PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%"
11080 </literallayout>
11081 <note>
11082 The <filename>_forcevariable</filename> override is
11083 not handled specially.
11084 This override only works because the default value of
11085 <filename>OVERRIDES</filename> includes
11086 "forcevariable".
11087 </note>
11088 </para>
11089 </glossdef>
11090 </glossentry>
11091
11092 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
11093 <info>
11094 PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
11095 </info>
11096 <glossdef>
11097 <para role="glossdeffirst">
11098 Specifies additional paths from which the OpenEmbedded
11099 build system gets source code.
11100 When the build system searches for source code, it first
11101 tries the local download directory.
11102 If that location fails, the build system tries locations
11103 defined by <filename>PREMIRRORS</filename>, the upstream
11104 source, and then locations specified by
11105 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
11106 in that order.
11107 </para>
11108
11109 <para>
11110 Assuming your distribution
11111 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
11112 is "poky", the default value for
11113 <filename>PREMIRRORS</filename> is defined in the
11114 <filename>conf/distro/poky.conf</filename> file in the
11115 <filename>meta-poky</filename> Git repository.
11116 </para>
11117
11118 <para>
11119 Typically, you could add a specific server for the
11120 build system to attempt before any others by adding
11121 something like the following to the
11122 <filename>local.conf</filename> configuration file in the
11123 <link linkend='build-directory'>Build Directory</link>:
11124 <literallayout class='monospaced'>
11125 PREMIRRORS_prepend = "\
11126 git://.*/.* http://www.yoctoproject.org/sources/ \n \
11127 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
11128 http://.*/.* http://www.yoctoproject.org/sources/ \n \
11129 https://.*/.* http://www.yoctoproject.org/sources/ \n"
11130 </literallayout>
11131 These changes cause the build system to intercept
11132 Git, FTP, HTTP, and HTTPS requests and direct them to
11133 the <filename>http://</filename> sources mirror.
11134 You can use <filename>file://</filename> URLs to point
11135 to local directories or network shares as well.
11136 </para>
11137 </glossdef>
11138 </glossentry>
11139
11140 <glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>
11141 <info>
11142 PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard', and 'extra'."
11143 </info>
11144 <glossdef>
11145 <para role="glossdeffirst">
11146 Indicates the importance of a package.
11147 </para>
11148
11149 <para>
11150 <filename>PRIORITY</filename> is considered to be part of
11151 the distribution policy because the importance of any given
11152 recipe depends on the purpose for which the distribution
11153 is being produced.
11154 Thus, <filename>PRIORITY</filename> is not normally set
11155 within recipes.
11156 </para>
11157
11158 <para>
11159 You can set <filename>PRIORITY</filename> to "required",
11160 "standard", "extra", and "optional", which is the default.
11161 </para>
11162 </glossdef>
11163 </glossentry>
11164
11165 <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
11166 <info>
11167 PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."
11168 </info>
11169 <glossdef>
11170 <para role="glossdeffirst">
11171 Specifies libraries installed within a recipe that
11172 should be ignored by the OpenEmbedded build system's
11173 shared library resolver.
11174 This variable is typically used when software being
11175 built by a recipe has its own private versions of a
11176 library normally provided by another recipe.
11177 In this case, you would not want the package containing
11178 the private libraries to be set as a dependency on other
11179 unrelated packages that should instead depend on the
11180 package providing the standard version of the library.
11181 </para>
11182
11183 <para>
11184 Libraries specified in this variable should be specified
11185 by their file name.
11186 For example, from the Firefox recipe in meta-browser:
11187 <literallayout class='monospaced'>
11188 PRIVATE_LIBS = "libmozjs.so \
11189 libxpcom.so \
11190 libnspr4.so \
11191 libxul.so \
11192 libmozalloc.so \
11193 libplc4.so \
11194 libplds4.so"
11195 </literallayout>
11196 </para>
11197
11198 <para>
11199 For more information, see the
11200 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11201 section in the Yocto Project Overview and Concepts Manual.
11202 </para>
11203 </glossdef>
11204 </glossentry>
11205
11206 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
11207 <info>
11208 PROVIDES[doc] = "A list of aliases that a recipe also provides. These aliases are useful for satisfying dependencies of other recipes during the build as specified by DEPENDS."
11209 </info>
11210 <glossdef>
11211 <para role="glossdeffirst">
11212 A list of aliases by which a particular recipe can be
11213 known.
11214 By default, a recipe's own
11215 <filename><link linkend='var-PN'>PN</link></filename>
11216 is implicitly already in its <filename>PROVIDES</filename>
11217 list and therefore does not need to mention that it provides itself.
11218 If a recipe uses <filename>PROVIDES</filename>, the
11219 additional aliases are synonyms for the recipe and can
11220 be useful for satisfying dependencies of other recipes during
11221 the build as specified by
11222 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
11223 </para>
11224
11225 <para>
11226 Consider the following example
11227 <filename>PROVIDES</filename> statement from the recipe
11228 file <filename>eudev_3.2.9.bb</filename>:
11229 <literallayout class='monospaced'>
11230 PROVIDES = "udev"
11231 </literallayout>
11232 The <filename>PROVIDES</filename> statement results in
11233 the "eudev" recipe also being available as simply "udev".
11234
11235 <note>
11236 Given that a recipe's own recipe name is already
11237 implicitly in its own <filename>PROVIDES</filename> list,
11238 it is unnecessary to add aliases with the "+=" operator;
11239 using a simple assignment will be sufficient. In other
11240 words, while you could write:
11241 <literallayout class='monospaced'>
11242 PROVIDES += "udev"
11243 </literallayout>
11244 in the above, the "+=" is overkill and unnecessary.
11245 </note>
11246 </para>
11247
11248 <para>
11249 In addition to providing recipes under alternate names,
11250 the <filename>PROVIDES</filename> mechanism is also used
11251 to implement virtual targets.
11252 A virtual target is a name that corresponds to some
11253 particular functionality (e.g. a Linux kernel).
11254 Recipes that provide the functionality in question list the
11255 virtual target in <filename>PROVIDES</filename>.
11256 Recipes that depend on the functionality in question can
11257 include the virtual target in <filename>DEPENDS</filename>
11258 to leave the choice of provider open.
11259 </para>
11260
11261 <para>
11262 Conventionally, virtual targets have names on the form
11263 "virtual/function" (e.g. "virtual/kernel").
11264 The slash is simply part of the name and has no
11265 syntactical significance.
11266 </para>
11267
11268 <para>
11269 The
11270 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
11271 variable is used to select which particular recipe
11272 provides a virtual target.
11273 <note>
11274 <para>A corresponding mechanism for virtual runtime
11275 dependencies (packages) exists.
11276 However, the mechanism does not depend on any special
11277 functionality beyond ordinary variable assignments.
11278 For example,
11279 <filename>VIRTUAL-RUNTIME_dev_manager</filename>
11280 refers to the package of the component that manages
11281 the <filename>/dev</filename> directory.</para>
11282
11283 <para>Setting the "preferred provider" for runtime
11284 dependencies is as simple as using the following
11285 assignment in a configuration file:</para>
11286 <literallayout class='monospaced'>
11287 VIRTUAL-RUNTIME_dev_manager = "udev"
11288 </literallayout>
11289 </note>
11290 </para>
11291 </glossdef>
11292 </glossentry>
11293
11294 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
11295 <info>
11296 PRSERV_HOST[doc] = "The network based PR service host and port."
11297 </info>
11298 <glossdef>
11299 <para role="glossdeffirst">
11300 The network based
11301 <link linkend='var-PR'><filename>PR</filename></link>
11302 service host and port.
11303 </para>
11304
11305 <para>
11306 The <filename>conf/local.conf.sample.extended</filename>
11307 configuration file in the
11308 <link linkend='source-directory'>Source Directory</link>
11309 shows how the <filename>PRSERV_HOST</filename> variable is
11310 set:
11311 <literallayout class='monospaced'>
11312 PRSERV_HOST = "localhost:0"
11313 </literallayout>
11314 You must set the variable if you want to automatically
11315 start a local
11316 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
11317 You can set <filename>PRSERV_HOST</filename> to other
11318 values to use a remote PR service.
11319 </para>
11320 </glossdef>
11321 </glossentry>
11322
11323 <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>
11324 <info>
11325 PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."
11326 </info>
11327 <glossdef>
11328 <para role="glossdeffirst">
11329 Specifies whether or not
11330 <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>
11331 (ptest) functionality is enabled when building a recipe.
11332 You should not set this variable directly.
11333 Enabling and disabling building Package Tests
11334 at build time should be done by adding "ptest" to (or
11335 removing it from)
11336 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
11337 </para>
11338 </glossdef>
11339 </glossentry>
11340
11341 <glossentry id='var-PV'><glossterm>PV</glossterm>
11342 <info>
11343 PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename."
11344 </info>
11345 <glossdef>
11346 <para role="glossdeffirst">
11347 The version of the recipe.
11348 The version is normally extracted from the recipe filename.
11349 For example, if the recipe is named
11350 <filename>expat_2.0.1.bb</filename>, then the default value
11351 of <filename>PV</filename> will be "2.0.1".
11352 <filename>PV</filename> is generally not overridden within
11353 a recipe unless it is building an unstable (i.e.
11354 development) version from a source code repository
11355 (e.g. Git or Subversion).
11356 </para>
11357
11358 <para>
11359 <filename>PV</filename> is the default value of the
11360 <link linkend='var-PKGV'><filename>PKGV</filename></link>
11361 variable.
11362 </para>
11363 </glossdef>
11364 </glossentry>
11365
11366 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
11367 <info>
11368 PYTHON_ABI[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, denotes the Application Binary Interface (ABI) currently in use for Python."
11369 </info>
11370 <glossdef>
11371 <para role="glossdeffirst">
11372 When used by recipes that inherit the
11373 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11374 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11375 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11376 or
11377 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11378 classes, denotes the Application Binary Interface (ABI)
11379 currently in use for Python.
11380 By default, the ABI is "m".
11381 You do not have to set this variable as the OpenEmbedded
11382 build system sets it for you.
11383 </para>
11384
11385 <para>
11386 The OpenEmbedded build system uses the ABI to construct
11387 directory names used when installing the Python headers
11388 and libraries in sysroot
11389 (e.g. <filename>.../python3.3m/...</filename>).
11390 </para>
11391
11392 <para>
11393 Recipes that inherit the <filename>distutils</filename>
11394 class during cross-builds also use this variable to
11395 locate the headers and libraries of the appropriate Python
11396 that the extension is targeting.
11397 </para>
11398 </glossdef>
11399 </glossentry>
11400
11401 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
11402 <info>
11403 PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."
11404 </info>
11405 <glossdef>
11406 <para role="glossdeffirst">
11407 When used by recipes that inherit the
11408 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11409 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11410 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11411 or
11412 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11413 classes, specifies the major Python version being built.
11414 For Python 3.x, <filename>PYTHON_PN</filename> would be
11415 "python3".
11416 You do not have to set this variable as the
11417 OpenEmbedded build system automatically sets it for you.
11418 </para>
11419
11420 <para>
11421 The variable allows recipes to use common infrastructure
11422 such as the following:
11423 <literallayout class='monospaced'>
11424 DEPENDS += "${PYTHON_PN}-native"
11425 </literallayout>
11426 In the previous example, the version of the dependency
11427 is <filename>PYTHON_PN</filename>.
11428 </para>
11429 </glossdef>
11430 </glossentry>
11431
11432 </glossdiv>
11433
11434 <glossdiv id='var-glossary-r'><title>R</title>
11435
11436 <glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>
11437 <info>
11438 RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."
11439 </info>
11440 <glossdef>
11441 <para role="glossdeffirst">
11442 The minimal command and arguments to run
11443 <filename>ranlib</filename>.
11444 </para>
11445 </glossdef>
11446 </glossentry>
11447
11448 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
11449 <info>
11450 RCONFLICTS[doc] = "The list of packages that conflict with another package. Note that the package will not be installed if the conflicting packages are not first removed."
11451 </info>
11452 <glossdef>
11453 <para role="glossdeffirst">
11454 The list of packages that conflict with packages.
11455 Note that packages will not be installed if conflicting
11456 packages are not first removed.
11457 </para>
11458
11459 <para>
11460 Like all package-controlling variables, you must always use
11461 them in conjunction with a package name override.
11462 Here is an example:
11463 <literallayout class='monospaced'>
11464 RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"
11465 </literallayout>
11466 </para>
11467
11468 <para>
11469 BitBake, which the OpenEmbedded build system uses, supports
11470 specifying versioned dependencies.
11471 Although the syntax varies depending on the packaging
11472 format, BitBake hides these differences from you.
11473 Here is the general syntax to specify versions with
11474 the <filename>RCONFLICTS</filename> variable:
11475 <literallayout class='monospaced'>
11476 RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11477 </literallayout>
11478 For <filename>operator</filename>, you can specify the
11479 following:
11480 <literallayout class='monospaced'>
11481 =
11482 &lt;
11483 &gt;
11484 &lt;=
11485 &gt;=
11486 </literallayout>
11487 For example, the following sets up a dependency on version
11488 1.2 or greater of the package <filename>foo</filename>:
11489 <literallayout class='monospaced'>
11490 RCONFLICTS_${PN} = "foo (>= 1.2)"
11491 </literallayout>
11492 </para>
11493 </glossdef>
11494 </glossentry>
11495
11496 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
11497 <info>
11498 RDEPENDS[doc] = "Lists runtime dependencies of a package."
11499 </info>
11500 <glossdef>
11501 <para role="glossdeffirst">
11502 Lists runtime dependencies of a package.
11503 These dependencies are other packages that must be
11504 installed in order for the package to function correctly.
11505 As an example, the following assignment declares that the
11506 package <filename>foo</filename> needs the packages
11507 <filename>bar</filename> and <filename>baz</filename> to
11508 be installed:
11509 <literallayout class='monospaced'>
11510 RDEPENDS_foo = "bar baz"
11511 </literallayout>
11512 The most common types of package runtime dependencies are
11513 automatically detected and added.
11514 Therefore, most recipes do not need to set
11515 <filename>RDEPENDS</filename>.
11516 For more information, see the
11517 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11518 section in the Yocto Project Overview and Concepts Manual.
11519 </para>
11520
11521 <para>
11522 The practical effect of the above
11523 <filename>RDEPENDS</filename> assignment is that
11524 <filename>bar</filename> and <filename>baz</filename>
11525 will be declared as dependencies inside the package
11526 <filename>foo</filename> when it is written out by one of
11527 the
11528 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
11529 tasks.
11530 Exactly how this is done depends on which package format
11531 is used, which is determined by
11532 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>.
11533 When the corresponding package manager installs the
11534 package, it will know to also install the packages on
11535 which it depends.
11536 </para>
11537
11538 <para>
11539 To ensure that the packages <filename>bar</filename> and
11540 <filename>baz</filename> get built, the previous
11541 <filename>RDEPENDS</filename> assignment also causes a task
11542 dependency to be added.
11543 This dependency is from the recipe's
11544 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
11545 (not to be confused with
11546 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>)
11547 task to the <filename>do_package_write_*</filename>
11548 task of the recipes that build <filename>bar</filename> and
11549 <filename>baz</filename>.
11550 </para>
11551
11552 <para>
11553 The names of the packages you list within
11554 <filename>RDEPENDS</filename> must be the names of other
11555 packages - they cannot be recipe names.
11556 Although package names and recipe names usually match,
11557 the important point here is that you are
11558 providing package names within the
11559 <filename>RDEPENDS</filename> variable.
11560 For an example of the default list of packages created from
11561 a recipe, see the
11562 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
11563 variable.
11564 </para>
11565
11566 <para>
11567 Because the <filename>RDEPENDS</filename> variable applies
11568 to packages being built, you should always use the variable
11569 in a form with an attached package name (remember that a
11570 single recipe can build multiple packages).
11571 For example, suppose you are building a development package
11572 that depends on the <filename>perl</filename> package.
11573 In this case, you would use the following
11574 <filename>RDEPENDS</filename> statement:
11575 <literallayout class='monospaced'>
11576 RDEPENDS_${PN}-dev += "perl"
11577 </literallayout>
11578 In the example, the development package depends on
11579 the <filename>perl</filename> package.
11580 Thus, the <filename>RDEPENDS</filename> variable has the
11581 <filename>${PN}-dev</filename> package name as part of the
11582 variable.
11583 <note>
11584 <title>Caution</title>
11585 <filename>RDEPENDS_${PN}-dev</filename> includes
11586 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>
11587 by default.
11588 This default is set in the BitBake configuration file
11589 (<filename>meta/conf/bitbake.conf</filename>).
11590 Be careful not to accidentally remove
11591 <filename>${PN}</filename> when modifying
11592 <filename>RDEPENDS_${PN}-dev</filename>.
11593 Use the "+=" operator rather than the "=" operator.
11594 </note>
11595 </para>
11596
11597 <para>
11598 The package names you use with
11599 <filename>RDEPENDS</filename> must appear as they would in
11600 the <filename>PACKAGES</filename> variable.
11601 The
11602 <link linkend='var-PKG'><filename>PKG</filename></link>
11603 variable allows a different name to be used for
11604 the final package (e.g. the
11605 <link linkend='ref-classes-debian'><filename>debian</filename></link>
11606 class uses this to rename packages), but this final package
11607 name cannot be used with <filename>RDEPENDS</filename>,
11608 which makes sense as <filename>RDEPENDS</filename> is meant
11609 to be independent of the package format used.
11610 </para>
11611
11612 <para>
11613 BitBake, which the OpenEmbedded build system uses, supports
11614 specifying versioned dependencies.
11615 Although the syntax varies depending on the packaging
11616 format, BitBake hides these differences from you.
11617 Here is the general syntax to specify versions with
11618 the <filename>RDEPENDS</filename> variable:
11619 <literallayout class='monospaced'>
11620 RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11621 </literallayout>
11622 For <replaceable>operator</replaceable>, you can specify the
11623 following:
11624 <literallayout class='monospaced'>
11625 =
11626 &lt;
11627 &gt;
11628 &lt;=
11629 &gt;=
11630 </literallayout>
11631 For <replaceable>version</replaceable>, provide the version
11632 number.
11633 <note><title>Tip</title>
11634 You can use
11635 <link linkend='var-EXTENDPKGV'><filename>EXTENDPKGV</filename></link>
11636 to provide a full package version specification.
11637 </note>
11638 For example, the following sets up a dependency on version
11639 1.2 or greater of the package <filename>foo</filename>:
11640 <literallayout class='monospaced'>
11641 RDEPENDS_${PN} = "foo (>= 1.2)"
11642 </literallayout>
11643 </para>
11644
11645 <para>
11646 For information on build-time dependencies, see the
11647 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
11648 variable.
11649 You can also see the
11650 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
11651 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
11652 sections in the BitBake User Manual for additional
11653 information on tasks and dependencies.
11654 </para>
11655 </glossdef>
11656 </glossentry>
11657
11658 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
11659 <info>
11660 REQUIRED_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that must exist in the current configuration in order for the OpenEmbedded build system to build the recipe."
11661 </info>
11662 <glossdef>
11663 <para role="glossdeffirst">
11664 When inheriting the
11665 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
11666 class, this
11667 variable identifies distribution features that must
11668 exist in the current configuration in order for the
11669 OpenEmbedded build system to build the recipe.
11670 In other words, if the
11671 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
11672 lists a feature that does not appear in
11673 <filename>DISTRO_FEATURES</filename> within the
11674 current configuration, an error occurs and the
11675 build stops.
11676 </para>
11677 </glossdef>
11678 </glossentry>
11679
11680 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
11681 <info>
11682 RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."
11683 </info>
11684 <glossdef>
11685 <para role="glossdeffirst">
11686 With <filename>rm_work</filename> enabled, this
11687 variable specifies a list of recipes whose work directories
11688 should not be removed.
11689 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
11690 section for more details.
11691 </para>
11692 </glossdef>
11693 </glossentry>
11694
11695 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
11696 <info>
11697 ROOT_HOME[doc] = "Defines the root home directory."
11698 </info>
11699 <glossdef>
11700 <para role="glossdeffirst">
11701 Defines the root home directory.
11702 By default, this directory is set as follows in the
11703 BitBake configuration file:
11704 <literallayout class='monospaced'>
11705 ROOT_HOME ??= "/home/root"
11706 </literallayout>
11707 <note>
11708 This default value is likely used because some
11709 embedded solutions prefer to have a read-only root
11710 filesystem and prefer to keep writeable data in one
11711 place.
11712 </note>
11713 </para>
11714
11715 <para>
11716 You can override the default by setting the variable
11717 in any layer or in the <filename>local.conf</filename> file.
11718 Because the default is set using a "weak" assignment
11719 (i.e. "??="), you can use either of the following forms
11720 to define your override:
11721 <literallayout class='monospaced'>
11722 ROOT_HOME = "/root"
11723 ROOT_HOME ?= "/root"
11724 </literallayout>
11725 These override examples use <filename>/root</filename>,
11726 which is probably the most commonly used override.
11727 </para>
11728 </glossdef>
11729 </glossentry>
11730
11731 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
11732 <info>
11733 ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."
11734 </info>
11735 <glossdef>
11736 <para role="glossdeffirst">
11737 Indicates a filesystem image to include as the root
11738 filesystem.
11739 </para>
11740
11741 <para>
11742 The <filename>ROOTFS</filename> variable is an optional
11743 variable used with the
11744 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
11745 class.
11746 </para>
11747 </glossdef>
11748 </glossentry>
11749
11750 <glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>
11751 <info>
11752 ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."
11753 </info>
11754 <glossdef>
11755 <para role="glossdeffirst">
11756 Specifies a list of functions to call after the
11757 OpenEmbedded build system has installed packages.
11758 You can specify functions separated by semicolons:
11759 <literallayout class='monospaced'>
11760 ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
11761 </literallayout>
11762 </para>
11763
11764 <para>
11765 If you need to pass the root filesystem path to a command
11766 within a function, you can use
11767 <filename>${IMAGE_ROOTFS}</filename>, which points to
11768 the directory that becomes the root filesystem image.
11769 See the
11770 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
11771 variable for more information.
11772 </para>
11773 </glossdef>
11774 </glossentry>
11775
11776 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
11777 <info>
11778 ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."
11779 </info>
11780 <glossdef>
11781 <para role="glossdeffirst">
11782 Specifies a list of functions to call once the
11783 OpenEmbedded build system has created the root filesystem.
11784 You can specify functions separated by semicolons:
11785 <literallayout class='monospaced'>
11786 ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
11787 </literallayout>
11788 </para>
11789
11790 <para>
11791 If you need to pass the root filesystem path to a command
11792 within a function, you can use
11793 <filename>${IMAGE_ROOTFS}</filename>, which points to
11794 the directory that becomes the root filesystem image.
11795 See the
11796 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
11797 variable for more information.
11798 </para>
11799 </glossdef>
11800 </glossentry>
11801
11802 <glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>
11803 <info>
11804 ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."
11805 </info>
11806 <glossdef>
11807 <para role="glossdeffirst">
11808 Specifies a list of functions to call after the
11809 OpenEmbedded build system has removed unnecessary
11810 packages.
11811 When runtime package management is disabled in the
11812 image, several packages are removed including
11813 <filename>base-passwd</filename>,
11814 <filename>shadow</filename>, and
11815 <filename>update-alternatives</filename>.
11816 You can specify functions separated by semicolons:
11817 <literallayout class='monospaced'>
11818 ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
11819 </literallayout>
11820 </para>
11821
11822 <para>
11823 If you need to pass the root filesystem path to a command
11824 within a function, you can use
11825 <filename>${IMAGE_ROOTFS}</filename>, which points to
11826 the directory that becomes the root filesystem image.
11827 See the
11828 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
11829 variable for more information.
11830 </para>
11831 </glossdef>
11832 </glossentry>
11833
11834 <glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>
11835 <info>
11836 ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."
11837 </info>
11838 <glossdef>
11839 <para role="glossdeffirst">
11840 Specifies a list of functions to call before the
11841 OpenEmbedded build system has created the root filesystem.
11842 You can specify functions separated by semicolons:
11843 <literallayout class='monospaced'>
11844 ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
11845 </literallayout>
11846 </para>
11847
11848 <para>
11849 If you need to pass the root filesystem path to a command
11850 within a function, you can use
11851 <filename>${IMAGE_ROOTFS}</filename>, which points to
11852 the directory that becomes the root filesystem image.
11853 See the
11854 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
11855 variable for more information.
11856 </para>
11857 </glossdef>
11858 </glossentry>
11859
11860 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
11861 <info>
11862 RPROVIDES[doc] = "A list of package name aliases that a package also provides. These aliases are useful for satisfying runtime dependencies of other packages both during the build and on the target."
11863 </info>
11864 <glossdef>
11865 <para role="glossdeffirst">
11866 A list of package name aliases that a package also provides.
11867 These aliases are useful for satisfying runtime dependencies
11868 of other packages both during the build and on the target
11869 (as specified by
11870 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
11871 <note>
11872 A package's own name is implicitly already in its
11873 <filename>RPROVIDES</filename> list.
11874 </note>
11875 </para>
11876
11877 <para>
11878 As with all package-controlling variables, you must always
11879 use the variable in conjunction with a package name override.
11880 Here is an example:
11881 <literallayout class='monospaced'>
11882 RPROVIDES_${PN} = "widget-abi-2"
11883 </literallayout>
11884 </para>
11885 </glossdef>
11886 </glossentry>
11887
11888 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
11889 <info>
11890 RRECOMMENDS[doc] = "A list of packages that extends the usability of a package being built. The package being built does not depend on this list of packages in order to successfully build, but needs them for the extended usability."
11891 </info>
11892 <glossdef>
11893 <para role="glossdeffirst">
11894 A list of packages that extends the usability of a package
11895 being built.
11896 The package being built does not depend on this list of
11897 packages in order to successfully build, but rather
11898 uses them for extended usability.
11899 To specify runtime dependencies for packages, see the
11900 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
11901 variable.
11902 </para>
11903
11904 <para>
11905 The package manager will automatically install the
11906 <filename>RRECOMMENDS</filename> list of packages when
11907 installing the built package.
11908 However, you can prevent listed packages from being
11909 installed by using the
11910 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
11911 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
11912 and
11913 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
11914 variables.
11915 </para>
11916
11917 <para>
11918 Packages specified in
11919 <filename>RRECOMMENDS</filename> need not actually be
11920 produced.
11921 However, a recipe must exist that provides each package,
11922 either through the
11923 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
11924 or
11925 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
11926 variables or the
11927 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>
11928 variable, or an error will occur during the build.
11929 If such a recipe does exist and the package is not produced,
11930 the build continues without error.
11931 </para>
11932
11933 <para>
11934 Because the <filename>RRECOMMENDS</filename> variable
11935 applies to packages being built, you should always attach
11936 an override to the variable to specify the particular
11937 package whose usability is being extended.
11938 For example, suppose you are building a development package
11939 that is extended to support wireless functionality.
11940 In this case, you would use the following:
11941 <literallayout class='monospaced'>
11942 RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"
11943 </literallayout>
11944 In the example, the package name
11945 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
11946 must appear as it would in the
11947 <filename>PACKAGES</filename> namespace before any renaming
11948 of the output package by classes such as
11949 <filename>debian.bbclass</filename>.
11950 </para>
11951
11952 <para>
11953 BitBake, which the OpenEmbedded build system uses, supports
11954 specifying versioned recommends.
11955 Although the syntax varies depending on the packaging
11956 format, BitBake hides these differences from you.
11957 Here is the general syntax to specify versions with
11958 the <filename>RRECOMMENDS</filename> variable:
11959 <literallayout class='monospaced'>
11960 RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11961 </literallayout>
11962 For <filename>operator</filename>, you can specify the
11963 following:
11964 <literallayout class='monospaced'>
11965 =
11966 &lt;
11967 &gt;
11968 &lt;=
11969 &gt;=
11970 </literallayout>
11971 For example, the following sets up a recommend on version
11972 1.2 or greater of the package <filename>foo</filename>:
11973 <literallayout class='monospaced'>
11974 RRECOMMENDS_${PN} = "foo (>= 1.2)"
11975 </literallayout>
11976 </para>
11977 </glossdef>
11978 </glossentry>
11979
11980 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
11981 <info>
11982 RREPLACES[doc] = "A list of packages replaced by a package. The package manager uses this variable to determine which package should be installed to replace other package(s) during an upgrade."
11983 </info>
11984 <glossdef>
11985 <para role="glossdeffirst">
11986 A list of packages replaced by a package.
11987 The package manager uses this variable to determine which
11988 package should be installed to replace other package(s)
11989 during an upgrade.
11990 In order to also have the other package(s) removed at the
11991 same time, you must add the name of the other
11992 package to the
11993 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
11994 </para>
11995
11996 <para>
11997 As with all package-controlling variables, you must use
11998 this variable in conjunction with a package name
11999 override.
12000 Here is an example:
12001 <literallayout class='monospaced'>
12002 RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>"
12003 </literallayout>
12004 </para>
12005
12006 <para>
12007 BitBake, which the OpenEmbedded build system uses, supports
12008 specifying versioned replacements.
12009 Although the syntax varies depending on the packaging
12010 format, BitBake hides these differences from you.
12011 Here is the general syntax to specify versions with
12012 the <filename>RREPLACES</filename> variable:
12013 <literallayout class='monospaced'>
12014 RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12015 </literallayout>
12016 For <filename>operator</filename>, you can specify the
12017 following:
12018 <literallayout class='monospaced'>
12019 =
12020 &lt;
12021 &gt;
12022 &lt;=
12023 &gt;=
12024 </literallayout>
12025 For example, the following sets up a replacement using
12026 version 1.2 or greater of the package
12027 <filename>foo</filename>:
12028 <literallayout class='monospaced'>
12029 RREPLACES_${PN} = "foo (>= 1.2)"
12030 </literallayout>
12031 </para>
12032 </glossdef>
12033 </glossentry>
12034
12035 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
12036 <info>
12037 RSUGGESTS[doc] = "A list of additional packages that you can suggest for installation by the package manager at the time a package is installed. Not all package managers support this functionality."
12038 </info>
12039 <glossdef>
12040 <para role="glossdeffirst">
12041 A list of additional packages that you can suggest for
12042 installation by the package manager at the time a package
12043 is installed.
12044 Not all package managers support this functionality.
12045 </para>
12046
12047 <para>
12048 As with all package-controlling variables, you must always
12049 use this variable in conjunction with a package name
12050 override.
12051 Here is an example:
12052 <literallayout class='monospaced'>
12053 RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>"
12054 </literallayout>
12055 </para>
12056 </glossdef>
12057 </glossentry>
12058
12059 </glossdiv>
12060
12061 <glossdiv id='var-glossary-s'><title>S</title>
12062
12063 <glossentry id='var-S'><glossterm>S</glossterm>
12064 <info>
12065 S[doc] = "The location in the Build Directory where unpacked package source code resides."
12066 </info>
12067 <glossdef>
12068 <para role="glossdeffirst">
12069 The location in the
12070 <link linkend='build-directory'>Build Directory</link>
12071 where unpacked recipe source code resides.
12072 By default, this directory is
12073 <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/${</filename><link linkend='var-BPN'><filename>BPN</filename></link><filename>}-${</filename><link linkend='var-PV'><filename>PV</filename></link><filename>}</filename>,
12074 where <filename>${BPN}</filename> is the base recipe name
12075 and <filename>${PV}</filename> is the recipe version.
12076 If the source tarball extracts the code to a directory
12077 named anything other than <filename>${BPN}-${PV}</filename>,
12078 or if the source code is fetched from an SCM such as
12079 Git or Subversion, then you must set <filename>S</filename>
12080 in the recipe so that the OpenEmbedded build system
12081 knows where to find the unpacked source.
12082 </para>
12083
12084 <para>
12085 As an example, assume a
12086 <link linkend='source-directory'>Source Directory</link>
12087 top-level folder named <filename>poky</filename> and a
12088 default Build Directory at <filename>poky/build</filename>.
12089 In this case, the work directory the build system uses
12090 to keep the unpacked recipe for <filename>db</filename>
12091 is the following:
12092 <literallayout class='monospaced'>
12093 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
12094 </literallayout>
12095 The unpacked source code resides in the
12096 <filename>db-5.1.19</filename> folder.
12097 </para>
12098
12099 <para>
12100 This next example assumes a Git repository.
12101 By default, Git repositories are cloned to
12102 <filename>${WORKDIR}/git</filename> during
12103 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>.
12104 Since this path is different from the default value of
12105 <filename>S</filename>, you must set it specifically
12106 so the source can be located:
12107 <literallayout class='monospaced'>
12108 SRC_URI = "git://path/to/repo.git"
12109 S = "${WORKDIR}/git"
12110 </literallayout>
12111 </para>
12112 </glossdef>
12113 </glossentry>
12114
12115 <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>
12116 <info>
12117 SANITY_REQUIRED_UTILITIES[doc] = "Specifies a list of command-line utilities that should be checked for during the initial sanity checking process when running BitBake."
12118 </info>
12119 <glossdef>
12120 <para role="glossdeffirst">
12121 Specifies a list of command-line utilities that should be
12122 checked for during the initial sanity checking process when
12123 running BitBake.
12124 If any of the utilities are not installed on the build host,
12125 then BitBake immediately exits with an error.
12126 </para>
12127 </glossdef>
12128 </glossentry>
12129
12130 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
12131 <info>
12132 SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."
12133 </info>
12134 <glossdef>
12135 <para role="glossdeffirst">
12136 A list of the host distribution identifiers that the
12137 build system has been tested against.
12138 Identifiers consist of the host distributor ID
12139 followed by the release,
12140 as reported by the <filename>lsb_release</filename> tool
12141 or as read from <filename>/etc/lsb-release</filename>.
12142 Separate the list items with explicit newline
12143 characters (<filename>\n</filename>).
12144 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
12145 and the current value of
12146 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
12147 does not appear in the list, then the build system reports
12148 a warning that indicates the current host distribution has
12149 not been tested as a build host.
12150 </para>
12151 </glossdef>
12152 </glossentry>
12153
12154 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
12155 <info>
12156 SDK_ARCH[doc] = "The target architecture for the SDK."
12157 </info>
12158 <glossdef>
12159 <para role="glossdeffirst">
12160 The target architecture for the SDK.
12161 Typically, you do not directly set this variable.
12162 Instead, use
12163 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
12164 </para>
12165 </glossdef>
12166 </glossentry>
12167
12168 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
12169 <info>
12170 SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."
12171 </info>
12172 <glossdef>
12173 <para role="glossdeffirst">
12174 The directory set up and used by the
12175 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
12176 class to which the SDK is deployed.
12177 The <filename>populate_sdk_base</filename> class defines
12178 <filename>SDK_DEPLOY</filename> as follows:
12179 <literallayout class='monospaced'>
12180 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
12181 </literallayout>
12182 </para>
12183 </glossdef>
12184 </glossentry>
12185
12186 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
12187 <info>
12188 SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."
12189 </info>
12190 <glossdef>
12191 <para role="glossdeffirst">
12192 The parent directory used by the OpenEmbedded build system
12193 when creating SDK output.
12194 The
12195 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12196 class defines the variable as follows:
12197 <literallayout class='monospaced'>
12198 SDK_DIR = "${WORKDIR}/sdk"
12199 </literallayout>
12200 <note>
12201 The <filename>SDK_DIR</filename> directory is a
12202 temporary directory as it is part of
12203 <filename>WORKDIR</filename>.
12204 The final output directory is
12205 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12206 </note>
12207 </para>
12208 </glossdef>
12209 </glossentry>
12210
12211 <glossentry id='var-SDK_EXT_TYPE'><glossterm>SDK_EXT_TYPE</glossterm>
12212 <info>
12213 SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."
12214 </info>
12215 <glossdef>
12216 <para role="glossdeffirst">
12217 Controls whether or not shared state artifacts are copied
12218 into the extensible SDK.
12219 The default value of "full" copies all of the required
12220 shared state artifacts into the extensible SDK.
12221 The value "minimal" leaves these artifacts out of the
12222 SDK.
12223 <note>
12224 If you set the variable to "minimal", you need to
12225 ensure
12226 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
12227 is set in the SDK's configuration to enable the
12228 artifacts to be fetched as needed.
12229 </note>
12230 </para>
12231 </glossdef>
12232 </glossentry>
12233
12234 <glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>
12235 <info>
12236 SDK_HOST_MANIFEST[doc] = "The manifest file for the host part of the SDK. This file lists all the installed packages that make up the host part of the SDK."
12237 </info>
12238 <glossdef>
12239 <para role="glossdeffirst">
12240 The manifest file for the host part of the SDK.
12241 This file lists all the installed packages that make up
12242 the host part of the SDK.
12243 The file contains package information on a line-per-package
12244 basis as follows:
12245 <literallayout class='monospaced'>
12246 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12247 </literallayout>
12248 </para>
12249
12250 <para>
12251 The
12252 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12253 class defines the manifest file as follows:
12254 <literallayout class='monospaced'>
12255 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
12256 </literallayout>
12257 The location is derived using the
12258 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12259 and
12260 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12261 variables.
12262 </para>
12263 </glossdef>
12264 </glossentry>
12265
12266 <glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>
12267 <info>
12268 SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target in the extensible SDK."
12269 </info>
12270 <glossdef>
12271 <para role="glossdeffirst">
12272 When set to "1", specifies to include the packagedata for
12273 all recipes in the "world" target in the extensible SDK.
12274 Including this data allows the
12275 <filename>devtool search</filename> command to find these
12276 recipes in search results, as well as allows the
12277 <filename>devtool add</filename> command to map
12278 dependencies more effectively.
12279 <note>
12280 Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>
12281 variable significantly increases build time because
12282 all of world needs to be built.
12283 Enabling the variable also slightly increases the size
12284 of the extensible SDK.
12285 </note>
12286 </para>
12287 </glossdef>
12288 </glossentry>
12289
12290 <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>
12291 <info>
12292 SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."
12293 </info>
12294 <glossdef>
12295 <para role="glossdeffirst">
12296 When set to "1", specifies to include the toolchain in the
12297 extensible SDK.
12298 Including the toolchain is useful particularly when
12299 <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>
12300 is set to "minimal" to keep the SDK reasonably small
12301 but you still want to provide a usable toolchain.
12302 For example, suppose you want to use the toolchain from an
12303 IDE or from other tools and you do not
12304 want to perform additional steps to install the toolchain.
12305 </para>
12306
12307 <para>
12308 The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable
12309 defaults to "0" if <filename>SDK_EXT_TYPE</filename>
12310 is set to "minimal", and defaults to "1" if
12311 <filename>SDK_EXT_TYPE</filename> is set to "full".
12312 </para>
12313 </glossdef>
12314 </glossentry>
12315
12316 <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>
12317 <info>
12318 SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."
12319 </info>
12320 <glossdef>
12321 <para role="glossdeffirst">
12322 A list of classes to remove from the
12323 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
12324 value globally within the extensible SDK configuration.
12325 The
12326 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12327 class sets the default value:
12328 <literallayout class='monospaced'>
12329 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
12330 </literallayout>
12331 </para>
12332
12333 <para>
12334 Some classes are not generally applicable within
12335 the extensible SDK context.
12336 You can use this variable to disable those classes.
12337 </para>
12338
12339 <para>
12340 For additional information on how to customize the
12341 extensible SDK's configuration, see the
12342 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12343 section in the Yocto Project Application Development and
12344 the Extensible Software Development Kit (eSDK) manual.
12345 </para>
12346 </glossdef>
12347 </glossentry>
12348
12349 <glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>
12350 <info>
12351 SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."
12352 </info>
12353 <glossdef>
12354 <para role="glossdeffirst">
12355 A list of variables not allowed through from the
12356 OpenEmbedded build system configuration into the extensible
12357 SDK configuration.
12358 Usually, these are variables that are specific to the
12359 machine on which the build system is running and thus
12360 would be potentially problematic within the extensible SDK.
12361 </para>
12362
12363 <para>By default,
12364 <filename>SDK_LOCAL_CONF_BLACKLIST</filename> is set in the
12365 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12366 class and excludes the following variables:
12367 <literallayout class='monospaced'>
12368 <link linkend='var-CONF_VERSION'>CONF_VERSION</link>
12369 <link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
12370 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'>BB_NUMBER_PARSE_THREADS</ulink>
12371 <link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link>
12372 <link linkend='var-PRSERV_HOST'>PRSERV_HOST</link>
12373 <link linkend='var-SSTATE_MIRRORS'>SSTATE_MIRRORS</link>
12374 <link linkend='var-DL_DIR'>DL_DIR</link>
12375 <link linkend='var-SSTATE_DIR'>SSTATE_DIR</link>
12376 <link linkend='var-TMPDIR'>TMPDIR</link>
12377 <link linkend='var-BB_SERVER_TIMEOUT'>BB_SERVER_TIMEOUT</link>
12378 </literallayout>
12379 </para>
12380
12381 <para>
12382 For additional information on how to customize the
12383 extensible SDK's configuration, see the
12384 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12385 section in the Yocto Project Application Development and
12386 the Extensible Software Development Kit (eSDK) manual.
12387 </para>
12388
12389 </glossdef>
12390 </glossentry>
12391
12392 <glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>
12393 <info>
12394 SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."
12395 </info>
12396 <glossdef>
12397 <para role="glossdeffirst">
12398 A list of variables allowed through from the OpenEmbedded
12399 build system configuration into the extensible SDK
12400 configuration.
12401 By default, the list of variables is empty and is set in
12402 the
12403 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12404 class.
12405 </para>
12406
12407 <para>
12408 This list overrides the variables specified using the
12409 <link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>
12410 variable as well as any variables identified by automatic
12411 blacklisting due to the "/" character being found at the
12412 start of the value, which is usually indicative of being a
12413 path and thus might not be valid on the system where the
12414 SDK is installed.
12415 </para>
12416
12417 <para>
12418 For additional information on how to customize the
12419 extensible SDK's configuration, see the
12420 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12421 section in the Yocto Project Application Development and
12422 the Extensible Software Development Kit (eSDK) manual.
12423 </para>
12424 </glossdef>
12425 </glossentry>
12426
12427 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
12428 <info>
12429 SDK_NAME[doc] = "The base name for SDK output files."
12430 </info>
12431 <glossdef>
12432 <para role="glossdeffirst">
12433 The base name for SDK output files.
12434 The name is derived from the
12435 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
12436 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
12437 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12438 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
12439 and
12440 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
12441 variables:
12442 <literallayout class='monospaced'>
12443 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
12444 </literallayout>
12445 </para>
12446 </glossdef>
12447 </glossentry>
12448
12449 <glossentry id='var-SDK_OS'><glossterm>SDK_OS</glossterm>
12450 <info>
12451 SDK_OS[doc] = "The operating system for which the SDK will be built."
12452 </info>
12453 <glossdef>
12454 <para role="glossdeffirst">
12455 Specifies the operating system for which the SDK
12456 will be built.
12457 The default value is the value of
12458 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
12459 </para>
12460 </glossdef>
12461 </glossentry>
12462
12463 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
12464 <info>
12465 SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."
12466 </info>
12467 <glossdef>
12468 <para role="glossdeffirst">
12469 The location used by the OpenEmbedded build system when
12470 creating SDK output.
12471 The
12472 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12473 class defines the variable as follows:
12474 <literallayout class='monospaced'>
12475 SDK_DIR = "${WORKDIR}/sdk"
12476 SDK_OUTPUT = "${SDK_DIR}/image"
12477 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
12478 </literallayout>
12479 <note>
12480 The <filename>SDK_OUTPUT</filename> directory is a
12481 temporary directory as it is part of
12482 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
12483 by way of
12484 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>.
12485 The final output directory is
12486 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12487 </note>
12488 </para>
12489 </glossdef>
12490 </glossentry>
12491
12492 <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
12493 <info>
12494 SDK_PACKAGE_ARCHS[doc] = "Specifies a list of architectures compatible with the SDK machine. This variable is set automatically and should not normally be hand-edited."
12495 </info>
12496 <glossdef>
12497 <para role="glossdeffirst">
12498 Specifies a list of architectures compatible with
12499 the SDK machine.
12500 This variable is set automatically and should not
12501 normally be hand-edited.
12502 Entries are separated using spaces and listed in order
12503 of priority.
12504 The default value for
12505 <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
12506 ${SDK_ARCH}-${SDKPKGSUFFIX}".
12507 </para>
12508 </glossdef>
12509 </glossentry>
12510
12511 <glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
12512 <info>
12513 SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the SDK."
12514 </info>
12515 <glossdef>
12516 <para role="glossdeffirst">
12517 Specifies a list of functions to call once the
12518 OpenEmbedded build system creates the SDK.
12519 You can specify functions separated by semicolons:
12520 <literallayout class='monospaced'>
12521 SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12522 </literallayout>
12523 </para>
12524
12525 <para>
12526 If you need to pass an SDK path to a command within a
12527 function, you can use
12528 <filename>${SDK_DIR}</filename>, which points to
12529 the parent directory used by the OpenEmbedded build system
12530 when creating SDK output.
12531 See the
12532 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
12533 variable for more information.
12534 </para>
12535 </glossdef>
12536 </glossentry>
12537
12538 <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>
12539 <info>
12540 SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."
12541 </info>
12542 <glossdef>
12543 <para role="glossdeffirst">
12544 The toolchain binary prefix used for
12545 <filename>nativesdk</filename> recipes.
12546 The OpenEmbedded build system uses the
12547 <filename>SDK_PREFIX</filename> value to set the
12548 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
12549 when building <filename>nativesdk</filename> recipes.
12550 The default value is "${SDK_SYS}-".
12551 </para>
12552 </glossdef>
12553 </glossentry>
12554
12555 <glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>
12556 <info>
12557 SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."
12558 </info>
12559 <glossdef>
12560 <para role="glossdeffirst">
12561 A list of shared state tasks added to the extensible SDK.
12562 By default, the following tasks are added:
12563 <literallayout class='monospaced'>
12564 do_populate_lic
12565 do_package_qa
12566 do_populate_sysroot
12567 do_deploy
12568 </literallayout>
12569 Despite the default value of "" for the
12570 <filename>SDK_RECRDEP_TASKS</filename> variable, the
12571 above four tasks are always added to the SDK.
12572 To specify tasks beyond these four, you need to use
12573 the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.
12574 you are defining additional tasks that are needed in
12575 order to build
12576 <link linkend='var-SDK_TARGETS'><filename>SDK_TARGETS</filename></link>).
12577 </para>
12578 </glossdef>
12579 </glossentry>
12580
12581 <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm>
12582 <info>
12583 SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."
12584 </info>
12585 <glossdef>
12586 <para role="glossdeffirst">
12587 Specifies the system, including the architecture and the
12588 operating system, for which the SDK will be built.
12589 </para>
12590
12591 <para>
12592 The OpenEmbedded build system automatically sets this
12593 variable based on
12594 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12595 <link linkend='var-SDK_VENDOR'><filename>SDK_VENDOR</filename></link>,
12596 and
12597 <link linkend='var-SDK_OS'><filename>SDK_OS</filename></link>.
12598 You do not need to set the <filename>SDK_SYS</filename>
12599 variable yourself.
12600 </para>
12601 </glossdef>
12602 </glossentry>
12603
12604 <glossentry id='var-SDK_TARGET_MANIFEST'><glossterm>SDK_TARGET_MANIFEST</glossterm>
12605 <info>
12606 SDK_TARGET_MANIFEST[doc] = "The manifest file for the target part of the SDK. This file lists all the installed packages that make up the target part of the SDK."
12607 </info>
12608 <glossdef>
12609 <para role="glossdeffirst">
12610 The manifest file for the target part of the SDK.
12611 This file lists all the installed packages that make up
12612 the target part of the SDK.
12613 The file contains package information on a line-per-package
12614 basis as follows:
12615 <literallayout class='monospaced'>
12616 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12617 </literallayout>
12618 </para>
12619
12620 <para>
12621 The
12622 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12623 class defines the manifest file as follows:
12624 <literallayout class='monospaced'>
12625 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
12626 </literallayout>
12627 The location is derived using the
12628 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12629 and
12630 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12631 variables.
12632 </para>
12633 </glossdef>
12634 </glossentry>
12635
12636 <glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>
12637 <info>
12638 SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."
12639 </info>
12640 <glossdef>
12641 <para role="glossdeffirst">
12642 A list of targets to install from shared state as part of
12643 the standard or extensible SDK installation.
12644 The default value is "${PN}" (i.e. the image from which
12645 the SDK is built).
12646 </para>
12647
12648 <para>
12649 The <filename>SDK_TARGETS</filename> variable is an
12650 internal variable and typically would not be changed.
12651 </para>
12652 </glossdef>
12653 </glossentry>
12654
12655 <glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>
12656 <info>
12657 SDK_TITLE[doc] = "The title to be printed when running the SDK installer."
12658 </info>
12659 <glossdef>
12660 <para role="glossdeffirst">
12661 The title to be printed when running the SDK installer.
12662 By default, this title is based on the
12663 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
12664 or
12665 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
12666 variable and is set in the
12667 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12668 class as follows:
12669 <literallayout class='monospaced'>
12670 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
12671 </literallayout>
12672 For the default distribution "poky",
12673 <filename>SDK_TITLE</filename> is set to
12674 "Poky (Yocto Project Reference Distro)".
12675 </para>
12676
12677 <para>
12678 For information on how to change this default title,
12679 see the
12680 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title'>Changing the Extensible SDK Installer Title</ulink>"
12681 section in the Yocto Project Application Development and
12682 the Extensible Software Development Kit (eSDK) manual.
12683 </para>
12684 </glossdef>
12685 </glossentry>
12686
12687 <glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>
12688 <info>
12689 SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."
12690 </info>
12691 <glossdef>
12692 <para role="glossdeffirst">
12693 An optional URL for an update server for the extensible
12694 SDK.
12695 If set, the value is used as the default update server when
12696 running <filename>devtool sdk-update</filename> within the
12697 extensible SDK.
12698 </para>
12699 </glossdef>
12700 </glossentry>
12701
12702 <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>
12703 <info>
12704 SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."
12705 </info>
12706 <glossdef>
12707 <para role="glossdeffirst">
12708 Specifies the name of the SDK vendor.
12709 </para>
12710 </glossdef>
12711 </glossentry>
12712
12713 <glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>
12714 <info>
12715 SDK_VERSION[doc] = "Specifies the version for the SDK."
12716 </info>
12717 <glossdef>
12718 <para role="glossdeffirst">
12719 Specifies the version of the SDK.
12720 The distribution configuration file (e.g.
12721 <filename>/meta-poky/conf/distro/poky.conf</filename>)
12722 defines the <filename>SDK_VERSION</filename> as follows:
12723 <literallayout class='monospaced'>
12724 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
12725 </literallayout>
12726 </para>
12727
12728 <para>
12729 For additional information, see the
12730 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
12731 and
12732 <link linkend='var-DATE'><filename>DATE</filename></link>
12733 variables.
12734 </para>
12735 </glossdef>
12736 </glossentry>
12737
12738 <glossentry id='var-SDKEXTPATH'><glossterm>SDKEXTPATH</glossterm>
12739 <info>
12740 SDKEXTPATH[doc] = "The default installation directory for the extensible SDK."
12741 </info>
12742 <glossdef>
12743 <para role="glossdeffirst">
12744 The default installation directory for the Extensible SDK.
12745 By default, this directory is based on the
12746 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
12747 variable and is set in the
12748 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12749 class as follows:
12750 <literallayout class='monospaced'>
12751 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
12752 </literallayout>
12753 For the default distribution "poky", the
12754 <filename>SDKEXTPATH</filename> is set to "poky_sdk".
12755 </para>
12756
12757 <para>
12758 For information on how to change this default directory,
12759 see the
12760 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory'>Changing the Default SDK Installation Directory</ulink>"
12761 section in the Yocto Project Application Development and
12762 the Extensible Software Development Kit (eSDK) manual.
12763 </para>
12764 </glossdef>
12765 </glossentry>
12766
12767 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
12768 <info>
12769 SDKIMAGE_FEATURES[doc] = "Equivalent to IMAGE_FEATURES. However, this variable applies to the SDK generated from an image using the command 'bitbake -c populate_sdk imagename'."
12770 </info>
12771 <glossdef>
12772 <para role="glossdeffirst">
12773 Equivalent to
12774 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
12775 However, this variable applies to the SDK generated from an
12776 image using the following command:
12777 <literallayout class='monospaced'>
12778 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
12779 </literallayout>
12780 </para>
12781 </glossdef>
12782 </glossentry>
12783
12784 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
12785 <info>
12786 SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."
12787 </info>
12788 <glossdef>
12789 <para role="glossdeffirst">
12790 The machine for which the SDK is built.
12791 In other words, the SDK is built such that it
12792 runs on the target you specify with the
12793 <filename>SDKMACHINE</filename> value.
12794 The value points to a corresponding
12795 <filename>.conf</filename> file under
12796 <filename>conf/machine-sdk/</filename>.
12797 </para>
12798
12799 <para>
12800 You can use "i686" and "x86_64" as possible values
12801 for this variable. The variable defaults to "i686"
12802 and is set in the local.conf file in the Build Directory.
12803 <literallayout class='monospaced'>
12804 SDKMACHINE ?= "i686"
12805 </literallayout>
12806 <note>
12807 You cannot set the <filename>SDKMACHINE</filename>
12808 variable in your distribution configuration file.
12809 If you do, the configuration will not take affect.
12810 </note>
12811 </para>
12812 </glossdef>
12813 </glossentry>
12814
12815 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
12816 <info>
12817 SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."
12818 </info>
12819 <glossdef>
12820 <para role="glossdeffirst">
12821 Defines the path offered to the user for installation
12822 of the SDK that is generated by the OpenEmbedded build
12823 system.
12824 The path appears as the default location for installing
12825 the SDK when you run the SDK's installation script.
12826 You can override the offered path when you run the
12827 script.
12828 </para>
12829 </glossdef>
12830 </glossentry>
12831
12832 <glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>
12833 <info>
12834 SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH."
12835 </info>
12836 <glossdef>
12837 <para role="glossdeffirst">
12838 The full path to the sysroot used for cross-compilation
12839 within an SDK as it will be when installed into the
12840 default
12841 <link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>.
12842 </para>
12843 </glossdef>
12844 </glossentry>
12845
12846 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
12847 <info>
12848 SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."
12849 </info>
12850 <glossdef>
12851 <para role="glossdeffirst">
12852 The section in which packages should be categorized.
12853 Package management utilities can make use of this variable.
12854 </para>
12855 </glossdef>
12856 </glossentry>
12857
12858 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
12859 <info>
12860 SELECTED_OPTIMIZATION[doc] = "The variable takes the value of FULL_OPTIMIZATION unless DEBUG_BUILD = '1'. In this case, the value of DEBUG_OPTIMIZATION is used."
12861 </info>
12862 <glossdef>
12863 <para role="glossdeffirst">
12864 Specifies the optimization flags passed to the C compiler
12865 when building for the target.
12866 The flags are passed through the default value of the
12867 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
12868 variable.
12869 </para>
12870
12871 <para>
12872 The <filename>SELECTED_OPTIMIZATION</filename> variable
12873 takes the value of
12874 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
12875 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
12876 If that is the case, the value of
12877 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
12878 </para>
12879 </glossdef>
12880 </glossentry>
12881
12882 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
12883 <info>
12884 SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."
12885 </info>
12886 <glossdef>
12887 <para role="glossdeffirst">
12888 Defines a serial console (TTY) to enable using
12889 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
12890 Provide a value that specifies the baud rate followed by
12891 the TTY device name separated by a space.
12892 You cannot specify more than one TTY device:
12893 <literallayout class='monospaced'>
12894 SERIAL_CONSOLE = "115200 ttyS0"
12895 </literallayout>
12896 <note>
12897 The <filename>SERIAL_CONSOLE</filename> variable
12898 is deprecated.
12899 Please use the
12900 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
12901 variable.
12902 </note>
12903 </para>
12904 </glossdef>
12905 </glossentry>
12906
12907 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
12908 <info>
12909 SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."
12910 </info>
12911 <glossdef>
12912 <para role="glossdeffirst">
12913 Defines a serial console (TTY) to enable using
12914 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
12915 Provide a value that specifies the baud rate followed by
12916 the TTY device name separated by a semicolon.
12917 Use spaces to separate multiple devices:
12918 <literallayout class='monospaced'>
12919 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
12920 </literallayout>
12921 </para>
12922 </glossdef>
12923 </glossentry>
12924
12925 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
12926 <info>
12927 SERIAL_CONSOLES_CHECK[doc] = "Selected SERIAL_CONSOLES to check against /proc/console before enabling using getty. Supported only by SysVinit."
12928 </info>
12929 <glossdef>
12930 <para role="glossdeffirst">
12931 Specifies serial consoles, which must be listed in
12932 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>,
12933 to check against <filename>/proc/console</filename>
12934 before enabling them using getty.
12935 This variable allows aliasing in the format:
12936 &lt;device&gt;:&lt;alias&gt;.
12937 If a device was listed as "sclp_line0"
12938 in <filename>/dev/</filename> and "ttyS0" was listed
12939 in <filename>/proc/console</filename>, you would do the
12940 following:
12941 <literallayout class='monospaced'>
12942 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
12943 </literallayout>
12944 This variable is currently only supported with SysVinit
12945 (i.e. not with systemd).
12946 </para>
12947 </glossdef>
12948 </glossentry>
12949
12950 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
12951 <info>
12952 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS[doc] = "A list of recipe dependencies that should not be used to determine signatures of tasks from one recipe when they depend on tasks from another recipe."
12953 </info>
12954 <glossdef>
12955 <para role="glossdeffirst">
12956 A list of recipe dependencies that should not be used to
12957 determine signatures of tasks from one recipe when they
12958 depend on tasks from another recipe.
12959 For example:
12960 <literallayout class='monospaced'>
12961 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
12962 </literallayout>
12963 </para>
12964
12965 <para>
12966 In the previous example, <filename>intone</filename>
12967 depends on <filename>mplayer2</filename>.
12968 </para>
12969
12970 <para>
12971 You can use the special token <filename>"*"</filename> on
12972 the left-hand side of the dependency to match all
12973 recipes except the one on the right-hand side.
12974 Here is an example:
12975 <literallayout class='monospaced'>
12976 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
12977 </literallayout>
12978 </para>
12979
12980 <para>
12981 In the previous example, all recipes except
12982 <filename>quilt-native</filename> ignore task
12983 signatures from the <filename>quilt-native</filename>
12984 recipe when determining their task signatures.
12985 </para>
12986
12987 <para>
12988 Use of this variable is one mechanism to remove dependencies
12989 that affect task signatures and thus force rebuilds when a
12990 recipe changes.
12991 <note><title>Caution</title>
12992 If you add an inappropriate dependency for a recipe
12993 relationship, the software might break during
12994 runtime if the interface of the second recipe was
12995 changed after the first recipe had been built.
12996 </note>
12997 </para>
12998 </glossdef>
12999 </glossentry>
13000
13001 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
13002 <info>
13003 SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."
13004 </info>
13005 <glossdef>
13006 <para role="glossdeffirst">
13007 A list of recipes that are completely stable and will
13008 never change.
13009 The ABI for the recipes in the list are presented by
13010 output from the tasks run to build the recipe.
13011 Use of this variable is one way to remove dependencies from
13012 one recipe on another that affect task signatures and
13013 thus force rebuilds when the recipe changes.
13014 <note><title>Caution</title>
13015 If you add an inappropriate variable to this list,
13016 the software might break at runtime if the
13017 interface of the recipe was changed after the other
13018 had been built.
13019 </note>
13020 </para>
13021 </glossdef>
13022 </glossentry>
13023
13024 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
13025 <info>
13026 SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."
13027 </info>
13028 <glossdef>
13029 <para role="glossdeffirst">
13030 Specifies the number of bits for the target system CPU.
13031 The value should be either "32" or "64".
13032 </para>
13033 </glossdef>
13034 </glossentry>
13035
13036 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
13037 <info>
13038 SITEINFO_ENDIANNESS[doc] = "Specifies the endian byte order of the target system. The value should be either 'le' for 'little-endian' or 'be' for 'big-endian'."
13039 </info>
13040 <glossdef>
13041 <para role="glossdeffirst">
13042 Specifies the endian byte order of the target system.
13043 The value should be either "le" for little-endian or "be" for big-endian.
13044 </para>
13045 </glossdef>
13046 </glossentry>
13047
13048 <glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>
13049 <info>
13050 SKIP_FILEDEPS[doc] = "Enables you to remove all files from the 'Provides' section of an RPM package."
13051 </info>
13052 <glossdef>
13053 <para role="glossdeffirst">
13054 Enables removal of all files from the "Provides" section of
13055 an RPM package.
13056 Removal of these files is required for packages containing
13057 prebuilt binaries and libraries such as
13058 <filename>libstdc++</filename> and
13059 <filename>glibc</filename>.
13060 </para>
13061
13062 <para>
13063 To enable file removal, set the variable to "1" in your
13064 <filename>conf/local.conf</filename> configuration file
13065 in your:
13066 <link linkend='build-directory'>Build Directory</link>.
13067 <literallayout class='monospaced'>
13068 SKIP_FILEDEPS = "1"
13069 </literallayout>
13070 </para>
13071 </glossdef>
13072 </glossentry>
13073
13074 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
13075 <info>
13076 SOC_FAMILY[doc] = "Groups together machines based upon the same family of SOC (System On Chip). You typically set this variable in a common .inc file that you include in the configuration files of all the machines."
13077 </info>
13078 <glossdef>
13079 <para role="glossdeffirst">
13080 Groups together machines based upon the same family
13081 of SOC (System On Chip).
13082 You typically set this variable in a common
13083 <filename>.inc</filename> file that you include in the
13084 configuration files of all the machines.
13085 <note>
13086 You must include
13087 <filename>conf/machine/include/soc-family.inc</filename>
13088 for this variable to appear in
13089 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
13090 </note>
13091 </para>
13092 </glossdef>
13093 </glossentry>
13094
13095 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
13096 <info>
13097 SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."
13098 </info>
13099 <glossdef>
13100 <para role="glossdeffirst">
13101 Defines the suffix for shared libraries used on the
13102 target platform.
13103 By default, this suffix is ".so.*" for all Linux-based
13104 systems and is defined in the
13105 <filename>meta/conf/bitbake.conf</filename> configuration
13106 file.
13107 </para>
13108
13109 <para>
13110 You will see this variable referenced in the default values
13111 of <filename>FILES_${PN}</filename>.
13112 </para>
13113 </glossdef>
13114 </glossentry>
13115
13116 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
13117 <info>
13118 SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."
13119 </info>
13120 <glossdef>
13121 <para role="glossdeffirst">
13122 Defines the suffix for the development symbolic link
13123 (symlink) for shared libraries on the target platform.
13124 By default, this suffix is ".so" for Linux-based
13125 systems and is defined in the
13126 <filename>meta/conf/bitbake.conf</filename> configuration
13127 file.
13128 </para>
13129
13130 <para>
13131 You will see this variable referenced in the default values
13132 of <filename>FILES_${PN}-dev</filename>.
13133 </para>
13134 </glossdef>
13135 </glossentry>
13136
13137 <glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>
13138 <info>
13139 SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."
13140 </info>
13141 <glossdef>
13142 <para role="glossdeffirst">
13143 When you are fetching files to create a mirror of sources
13144 (i.e. creating a source mirror), setting
13145 <filename>SOURCE_MIRROR_FETCH</filename> to "1" in your
13146 <filename>local.conf</filename> configuration file ensures
13147 the source for all recipes are fetched regardless of
13148 whether or not a recipe is compatible with the
13149 configuration.
13150 A recipe is considered incompatible with the currently
13151 configured machine when either or both the
13152 <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link>
13153 variable and
13154 <link linkend='var-COMPATIBLE_HOST'><filename>COMPATIBLE_HOST</filename></link>
13155 variables specify compatibility with a machine other
13156 than that of the current machine or host.
13157 <note><title>Warning</title>
13158 Do not set the
13159 <filename>SOURCE_MIRROR_FETCH</filename> variable
13160 unless you are creating a source mirror.
13161 In other words, do not set the variable during a
13162 normal build.
13163 </note>
13164 </para>
13165 </glossdef>
13166 </glossentry>
13167
13168 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
13169 <info>
13170 SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."
13171 </info>
13172 <glossdef>
13173 <para role="glossdeffirst">
13174 Defines your own
13175 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13176 from which to first fetch source before attempting to fetch
13177 from the upstream specified in
13178 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
13179 </para>
13180
13181 <para>
13182 To use this variable, you must globally inherit the
13183 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
13184 class and then provide the URL to your mirrors.
13185 Here is the general syntax:
13186 <literallayout class='monospaced'>
13187 INHERIT += "own-mirrors"
13188 SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"
13189 </literallayout>
13190 <note>
13191 You can specify only a single URL in
13192 <filename>SOURCE_MIRROR_URL</filename>.
13193 </note>
13194 </para>
13195 </glossdef>
13196 </glossentry>
13197
13198 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
13199 <info>
13200 SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."
13201 </info>
13202 <glossdef>
13203 <para role="glossdeffirst">
13204 Maps commonly used license names to their SPDX counterparts
13205 found in <filename>meta/files/common-licenses/</filename>.
13206 For the default <filename>SPDXLICENSEMAP</filename>
13207 mappings, see the
13208 <filename>meta/conf/licenses.conf</filename> file.
13209 </para>
13210
13211 <para>
13212 For additional information, see the
13213 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
13214 variable.
13215 </para>
13216 </glossdef>
13217 </glossentry>
13218
13219 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
13220 <info>
13221 SPECIAL_PKGSUFFIX[doc] = "A list of prefixes for PN used by the OpenEmbedded build system to create variants of recipes or packages. The list specifies the prefixes to strip off during certain circumstances such as the generation of the BPN variable."
13222 </info>
13223 <glossdef>
13224 <para role="glossdeffirst">
13225 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
13226 OpenEmbedded build system to create variants of recipes or packages.
13227 The list specifies the prefixes to strip off during certain circumstances
13228 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
13229 </para>
13230 </glossdef>
13231 </glossentry>
13232
13233 <glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>
13234 <info>
13235 SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."
13236 </info>
13237 <glossdef>
13238 <para role="glossdeffirst">
13239 The file type for the Secondary Program Loader (SPL).
13240 Some devices use an SPL from which to boot (e.g. the
13241 BeagleBone development board).
13242 For such cases, you can declare the file type of the
13243 SPL binary in the <filename>u-boot.inc</filename> include
13244 file, which is used in the U-Boot recipe.
13245 </para>
13246
13247 <para>
13248 The SPL file type is set to "null" by default in the
13249 <filename>u-boot.inc</filename> file as follows:
13250 <literallayout class='monospaced'>
13251 # Some versions of u-boot build an SPL (Second Program Loader) image that
13252 # should be packaged along with the u-boot binary as well as placed in the
13253 # deploy directory. For those versions they can set the following variables
13254 # to allow packaging the SPL.
13255 SPL_BINARY ?= ""
13256 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
13257 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
13258 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
13259 </literallayout>
13260 The <filename>SPL_BINARY</filename> variable helps form
13261 various <filename>SPL_*</filename> variables used by
13262 the OpenEmbedded build system.
13263 </para>
13264
13265 <para>
13266 See the BeagleBone machine configuration example in the
13267 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
13268 section in the Yocto Project Board Support Package
13269 Developer's Guide for additional information.
13270 </para>
13271 </glossdef>
13272 </glossentry>
13273
13274 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
13275 <info>
13276 SRC_URI[doc] = "The list of source files - local or remote. This variable tells the OpenEmbedded build system what bits to pull in for the build and how to pull them in."
13277 </info>
13278 <glossdef>
13279 <para role="glossdeffirst">
13280 The list of source files - local or remote.
13281 This variable tells the OpenEmbedded build system which bits
13282 to pull in for the build and how to pull them in.
13283 For example, if the recipe or append file only needs to
13284 fetch a tarball from the Internet, the recipe or
13285 append file uses a single <filename>SRC_URI</filename>
13286 entry.
13287 On the other hand, if the recipe or append file needs to
13288 fetch a tarball, apply two patches, and include a custom
13289 file, the recipe or append file would include four
13290 instances of the variable.
13291 </para>
13292
13293 <para>
13294 The following list explains the available URI protocols.
13295 URI protocols are highly dependent on particular BitBake
13296 Fetcher submodules.
13297 Depending on the fetcher BitBake uses, various URL
13298 parameters are employed.
13299 For specifics on the supported Fetchers, see the
13300 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
13301 section in the BitBake User Manual.
13302 <itemizedlist>
13303 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
13304 Fetches files, which are usually files shipped with
13305 the
13306 <link linkend='metadata'>Metadata</link>,
13307 from the local machine (e.g.
13308 <ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>patch</ulink>
13309 files).
13310 The path is relative to the
13311 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
13312 variable.
13313 Thus, the build system searches, in order, from the
13314 following directories, which are assumed to be a
13315 subdirectories of the directory in which the
13316 recipe file (<filename>.bb</filename>) or
13317 append file (<filename>.bbappend</filename>)
13318 resides:
13319 <itemizedlist>
13320 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
13321 The base recipe name without any special
13322 suffix or version numbers.
13323 </para></listitem>
13324 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
13325 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
13326 The base recipe name and version but without
13327 any special package name suffix.
13328 </para></listitem>
13329 <listitem><para><emphasis>files -</emphasis>
13330 Files within a directory, which is named
13331 <filename>files</filename> and is also
13332 alongside the recipe or append file.
13333 </para></listitem>
13334 </itemizedlist>
13335 <note>
13336 If you want the build system to pick up files
13337 specified through a
13338 <filename>SRC_URI</filename>
13339 statement from your append file, you need to be
13340 sure to extend the
13341 <filename>FILESPATH</filename>
13342 variable by also using the
13343 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
13344 variable from within your append file.
13345 </note>
13346 </para></listitem>
13347 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
13348 Bazaar revision control repository.</para></listitem>
13349 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
13350 Git revision control repository.</para></listitem>
13351 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
13352 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
13353 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
13354 a repo (Git) repository.</para></listitem>
13355 <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis>
13356 Fetches files from a ClearCase repository.
13357 </para></listitem>
13358 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
13359 the Internet using <filename>http</filename>.</para></listitem>
13360 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
13361 from the Internet using <filename>https</filename>.</para></listitem>
13362 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
13363 from the Internet using <filename>ftp</filename>.</para></listitem>
13364 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
13365 a CVS revision control repository.</para></listitem>
13366 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
13367 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
13368 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
13369 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
13370 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
13371 a secure shell.</para></listitem>
13372 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
13373 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
13374 <listitem><para><emphasis><filename>npm://</filename> -</emphasis> Fetches JavaScript
13375 modules from a registry.
13376 </para></listitem>
13377 </itemizedlist>
13378 </para>
13379
13380 <para>
13381 Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
13382 Here are standard options:
13383 <itemizedlist>
13384 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
13385 the patch or not.
13386 The default action is to apply the patch.</para></listitem>
13387 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
13388 striplevel to use when applying the patch.
13389 The default level is 1.</para></listitem>
13390 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
13391 the directory in which the patch should be applied.
13392 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
13393 </para></listitem>
13394 </itemizedlist>
13395 </para>
13396
13397 <para>
13398 Here are options specific to recipes building code from a revision control system:
13399 <itemizedlist>
13400 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
13401 Apply the patch only if
13402 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
13403 is equal to or greater than <filename>mindate</filename>.
13404 </para></listitem>
13405 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
13406 Apply the patch only if <filename>SRCDATE</filename>
13407 is not later than <filename>maxdate</filename>.
13408 </para></listitem>
13409 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
13410 Apply the patch only if <filename>SRCREV</filename>
13411 is equal to or greater than <filename>minrev</filename>.
13412 </para></listitem>
13413 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
13414 Apply the patch only if <filename>SRCREV</filename>
13415 is not later than <filename>maxrev</filename>.
13416 </para></listitem>
13417 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
13418 Apply the patch only if <filename>SRCREV</filename>
13419 is equal to <filename>rev</filename>.
13420 </para></listitem>
13421 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
13422 Apply the patch only if <filename>SRCREV</filename>
13423 is not equal to <filename>rev</filename>.
13424 </para></listitem>
13425 </itemizedlist>
13426 </para>
13427
13428 <para>
13429 Here are some additional options worth mentioning:
13430 <itemizedlist>
13431 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
13432 whether or not to unpack the file if it is an archive.
13433 The default action is to unpack the file.</para></listitem>
13434 <listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file
13435 (or extracts its contents) into the specified
13436 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
13437 when the Git fetcher is used.
13438 </para></listitem>
13439 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
13440 (or extracts its contents) into the specified
13441 subdirectory of <filename>WORKDIR</filename>
13442 when the local (<filename>file://</filename>)
13443 fetcher is used.
13444 </para></listitem>
13445 <listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
13446 (or extracts its contents) into the specified
13447 subdirectory of <filename>WORKDIR</filename> when
13448 the CVS fetcher is used.
13449 </para></listitem>
13450 <listitem><para><emphasis><filename>subpath</filename> -</emphasis>
13451 Limits the checkout to a specific subpath of the
13452 tree when using the Git fetcher is used.
13453 </para></listitem>
13454 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
13455 name to be used for association with <filename>SRC_URI</filename> checksums
13456 when you have more than one file specified in <filename>SRC_URI</filename>.
13457 </para></listitem>
13458 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
13459 the filename used when storing the downloaded file.</para></listitem>
13460 </itemizedlist>
13461 </para>
13462 </glossdef>
13463 </glossentry>
13464
13465 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
13466 <info>
13467 SRC_URI_OVERRIDES_PACKAGE_ARCH[doc] = "By default, the OpenEmbedded build system automatically detects whether SRC_URI contains files that are machine-specific. If so, the build system automatically changes PACKAGE_ARCH. Setting this variable to '0' disables this behavior."
13468 </info>
13469 <glossdef>
13470 <para role="glossdeffirst">
13471 By default, the OpenEmbedded build system automatically detects whether
13472 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
13473 contains files that are machine-specific.
13474 If so, the build system automatically changes
13475 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
13476 Setting this variable to "0" disables this behavior.
13477 </para>
13478 </glossdef>
13479 </glossentry>
13480
13481 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
13482 <info>
13483 SRCDATE[doc] = "The date of the source code used to build the package. This variable applies only if the source was fetched from a Source Code Manager (SCM)."
13484 </info>
13485 <glossdef>
13486 <para role="glossdeffirst">
13487 The date of the source code used to build the package.
13488 This variable applies only if the source was fetched from a Source Code Manager (SCM).
13489 </para>
13490 </glossdef>
13491 </glossentry>
13492
13493 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
13494 <info>
13495 SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."
13496 </info>
13497 <glossdef>
13498 <para role="glossdeffirst">
13499 Returns the version string of the current package.
13500 This string is used to help define the value of
13501 <link linkend='var-PV'><filename>PV</filename></link>.
13502 </para>
13503
13504 <para>
13505 The <filename>SRCPV</filename> variable is defined in the
13506 <filename>meta/conf/bitbake.conf</filename> configuration
13507 file in the
13508 <link linkend='source-directory'>Source Directory</link>
13509 as follows:
13510 <literallayout class='monospaced'>
13511 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
13512 </literallayout>
13513 </para>
13514
13515 <para>
13516 Recipes that need to define <filename>PV</filename> do so
13517 with the help of the <filename>SRCPV</filename>.
13518 For example, the <filename>ofono</filename> recipe
13519 (<filename>ofono_git.bb</filename>) located in
13520 <filename>meta/recipes-connectivity</filename> in the
13521 Source Directory defines <filename>PV</filename> as
13522 follows:
13523 <literallayout class='monospaced'>
13524 PV = "0.12-git${SRCPV}"
13525 </literallayout>
13526 </para>
13527 </glossdef>
13528 </glossentry>
13529
13530 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
13531 <info>
13532 SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial, and Bazaar only."
13533 </info>
13534 <glossdef>
13535 <para role="glossdeffirst">
13536 The revision of the source code used to build the package.
13537 This variable applies to Subversion, Git, Mercurial, and
13538 Bazaar only.
13539 Note that if you want to build a fixed revision and you
13540 want to avoid performing a query on the remote repository
13541 every time BitBake parses your recipe, you should specify
13542 a <filename>SRCREV</filename> that is a
13543 full revision identifier and not just a tag.
13544 <note>
13545 For information on limitations when inheriting the
13546 latest revision of software using
13547 <filename>SRCREV</filename>, see the
13548 <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
13549 variable description and the
13550 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
13551 section, which is in the Yocto Project Development
13552 Tasks Manual.
13553 </note>
13554 </para>
13555
13556 </glossdef>
13557 </glossentry>
13558
13559 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
13560 <info>
13561 SSTATE_DIR[doc] = "The directory for the shared state cache."
13562 </info>
13563 <glossdef>
13564 <para role="glossdeffirst">
13565 The directory for the shared state cache.
13566 </para>
13567 </glossdef>
13568 </glossentry>
13569
13570 <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
13571 <info>
13572 SSTATE_MIRROR_ALLOW_NETWORK[doc] = "If set to "1", allows fetches from mirrors that are specified in SSTATE_MIRRORS to work even when fetching from the network is disabled by setting BB_NO_NETWORK to "1"."
13573 </info>
13574 <glossdef>
13575 <para role="glossdeffirst">
13576 If set to "1", allows fetches from
13577 mirrors that are specified in
13578 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
13579 to work even when fetching from the network is
13580 disabled by setting <filename>BB_NO_NETWORK</filename>
13581 to "1".
13582 Using the
13583 <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
13584 variable is useful if you have set
13585 <filename>SSTATE_MIRRORS</filename> to point to an
13586 internal server for your shared state cache, but
13587 you want to disable any other fetching from the network.
13588 </para>
13589 </glossdef>
13590 </glossentry>
13591
13592 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
13593 <info>
13594 SSTATE_MIRRORS[doc] = "Configures the OpenEmbedded build system to search other mirror locations for prebuilt cache data objects before building out the data. You can specify a filesystem directory or a remote URL such as HTTP or FTP."
13595 </info>
13596 <glossdef>
13597 <para role="glossdeffirst">
13598 Configures the OpenEmbedded build system to search other
13599 mirror locations for prebuilt cache data objects before
13600 building out the data.
13601 This variable works like fetcher
13602 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
13603 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13604 and points to the cache locations to check for the shared
13605 state (sstate) objects.
13606 </para>
13607
13608 <para>
13609 You can specify a filesystem directory or a remote URL such
13610 as HTTP or FTP.
13611 The locations you specify need to contain the shared state
13612 cache (sstate-cache) results from previous builds.
13613 The sstate-cache you point to can also be from builds on
13614 other machines.
13615 </para>
13616
13617 <para>
13618 When pointing to sstate build artifacts on another machine
13619 that uses a different GCC version for native builds,
13620 you must configure <filename>SSTATE_MIRRORS</filename>
13621 with a regular expression that maps local search paths
13622 to server paths.
13623 The paths need to take into account
13624 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
13625 set by the
13626 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
13627 class.
13628 For example, the following maps the local search path
13629 <filename>universal-4.9</filename> to the server-provided
13630 path <replaceable>server_url_sstate_path</replaceable>:
13631 <literallayout class='monospaced'>
13632 SSTATE_MIRRORS ?= file://universal-4.9/(.*) http://<replaceable>server_url_sstate_path</replaceable>/universal-4.8/\1 \n
13633 </literallayout>
13634 </para>
13635
13636 <para>
13637 If a mirror uses the same structure as
13638 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
13639 you need to add
13640 "PATH" at the end as shown in the examples below.
13641 The build system substitutes the correct path within the
13642 directory structure.
13643 <literallayout class='monospaced'>
13644 SSTATE_MIRRORS ?= "\
13645 file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \
13646 file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"
13647 </literallayout>
13648 </para>
13649 </glossdef>
13650 </glossentry>
13651
13652 <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>
13653 <info>
13654 SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."
13655 </info>
13656 <glossdef>
13657 <para role="glossdeffirst">
13658 Controls the list of files the OpenEmbedded build system
13659 scans for hardcoded installation paths. The variable uses a
13660 space-separated list of filenames (not paths) with standard
13661 wildcard characters allowed.
13662 </para>
13663
13664 <para>
13665 During a build, the OpenEmbedded build system creates a
13666 shared state (sstate) object during the first stage of
13667 preparing the sysroots. That object is scanned for
13668 hardcoded paths for original installation locations.
13669 The list of files that are scanned for paths is controlled
13670 by the <filename>SSTATE_SCAN_FILES</filename> variable.
13671 Typically, recipes add files they want to be scanned to the
13672 value of <filename>SSTATE_SCAN_FILES</filename> rather than
13673 the variable being comprehensively set. The
13674 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
13675 class specifies the default list of files.
13676 </para>
13677
13678 <para>
13679 For details on the process, see the
13680 <link linkend='ref-classes-staging'><filename>staging</filename></link>
13681 class.
13682 </para>
13683 </glossdef>
13684 </glossentry>
13685
13686 <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
13687 <info>
13688 STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."
13689 </info>
13690 <glossdef>
13691 <para role="glossdeffirst">
13692 Specifies the path to the <filename>/lib</filename>
13693 subdirectory of the sysroot directory for the
13694 build host.
13695 </para>
13696 </glossdef>
13697 </glossentry>
13698
13699 <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
13700 <info>
13701 STAGING_BASELIBDIR[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
13702 </info>
13703 <glossdef>
13704 <para role="glossdeffirst">
13705 Specifies the path to the <filename>/lib</filename>
13706 subdirectory of the sysroot directory for the target
13707 for which the current recipe is being built
13708 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13709 </para>
13710 </glossdef>
13711 </glossentry>
13712
13713 <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
13714 <info>
13715 STAGING_BINDIR[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
13716 </info>
13717 <glossdef>
13718 <para role="glossdeffirst">
13719 Specifies the path to the
13720 <filename>/usr/bin</filename> subdirectory of the
13721 sysroot directory for the target for which the current
13722 recipe is being built
13723 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13724 </para>
13725 </glossdef>
13726 </glossentry>
13727
13728 <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
13729 <info>
13730 STAGING_BINDIR_CROSS[doc] = "Specifies the path to the directory containing binary configuration scripts. These scripts provide configuration information for other software that wants to make use of libraries or include files provided by the software associated with the script."
13731 </info>
13732 <glossdef>
13733 <para role="glossdeffirst">
13734 Specifies the path to the directory containing binary
13735 configuration scripts.
13736 These scripts provide configuration information for
13737 other software that wants to make use of libraries or
13738 include files provided by the software associated with
13739 the script.
13740 <note>
13741 This style of build configuration has been largely
13742 replaced by <filename>pkg-config</filename>.
13743 Consequently, if <filename>pkg-config</filename>
13744 is supported by the library to which you are linking,
13745 it is recommended you use
13746 <filename>pkg-config</filename> instead of a
13747 provided configuration script.
13748 </note>
13749 </para>
13750 </glossdef>
13751 </glossentry>
13752
13753 <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
13754 <info>
13755 STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."
13756 </info>
13757 <glossdef>
13758 <para role="glossdeffirst">
13759 Specifies the path to the
13760 <filename>/usr/bin</filename> subdirectory of the
13761 sysroot directory for the build host.
13762 </para>
13763 </glossdef>
13764 </glossentry>
13765
13766 <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
13767 <info>
13768 STAGING_DATADIR[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
13769 </info>
13770 <glossdef>
13771 <para role="glossdeffirst">
13772 Specifies the path to the <filename>/usr/share</filename>
13773 subdirectory of the sysroot directory for the target
13774 for which the current recipe is being built
13775 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13776 </para>
13777 </glossdef>
13778 </glossentry>
13779
13780 <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
13781 <info>
13782 STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."
13783 </info>
13784 <glossdef>
13785 <para role="glossdeffirst">
13786 Specifies the path to the <filename>/usr/share</filename>
13787 subdirectory of the sysroot directory for the build host.
13788 </para>
13789 </glossdef>
13790 </glossentry>
13791
13792 <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
13793 <info>
13794 STAGING_DIR[doc] = "Helps construct the recipe-sysroots directory, which is used during packaging."
13795 </info>
13796 <glossdef>
13797 <para role="glossdeffirst">
13798 Helps construct the <filename>recipe-sysroots</filename>
13799 directory, which is used during packaging.
13800 </para>
13801
13802 <para>
13803 For information on how staging for recipe-specific
13804 sysroots occurs, see the
13805 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
13806 task, the
13807 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"
13808 section in the Yocto Project Development Tasks Manual, the
13809 "<ulink url='&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment'>Configuration, Compilation, and Staging</ulink>"
13810 section in the Yocto Project Overview and Concepts Manual,
13811 and the
13812 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
13813 variable.
13814 <note>
13815 Recipes should never write files directly under
13816 the <filename>STAGING_DIR</filename> directory because
13817 the OpenEmbedded build system
13818 manages the directory automatically.
13819 Instead, files should be installed to
13820 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
13821 within your recipe's
13822 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
13823 task and then the OpenEmbedded build system will
13824 stage a subset of those files into the sysroot.
13825 </note>
13826 </para>
13827 </glossdef>
13828 </glossentry>
13829
13830 <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
13831 <info>
13832 STAGING_DIR_HOST[doc] = "Specifies the path to the sysroot directory for the system that the component is built to run on."
13833 </info>
13834 <glossdef>
13835 <para role="glossdeffirst">
13836 Specifies the path to the sysroot directory for the system
13837 on which the component is built to run (the system that
13838 hosts the component).
13839 For most recipes, this sysroot is the one in which that
13840 recipe's
13841 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
13842 task copies files.
13843 Exceptions include <filename>-native</filename> recipes,
13844 where the <filename>do_populate_sysroot</filename> task
13845 instead uses
13846 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>.
13847 Depending on the type of recipe and the build target,
13848 <filename>STAGING_DIR_HOST</filename> can have the
13849 following values:
13850 <itemizedlist>
13851 <listitem><para>
13852 For recipes building for the target machine, the
13853 value is
13854 "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".
13855 </para></listitem>
13856 <listitem><para>
13857 For native recipes building for the build host, the
13858 value is empty given the assumption that when
13859 building for the build host, the build host's own
13860 directories should be used.
13861 <note>
13862 <para><filename>-native</filename> recipes are
13863 not installed into host paths like such as
13864 <filename>/usr</filename>.
13865 Rather, these recipes are installed into
13866 <filename>STAGING_DIR_NATIVE</filename>.
13867 When compiling <filename>-native</filename>
13868 recipes, standard build environment variables
13869 such as
13870 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
13871 and
13872 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
13873 are set up so that both host paths and
13874 <filename>STAGING_DIR_NATIVE</filename> are
13875 searched for libraries and headers using, for
13876 example, GCC's <filename>-isystem</filename>
13877 option.</para>
13878
13879 <para>Thus, the emphasis is that the
13880 <filename>STAGING_DIR*</filename> variables
13881 should be viewed as input variables by tasks
13882 such as
13883 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
13884 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
13885 and
13886 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
13887 Having the real system root correspond to
13888 <filename>STAGING_DIR_HOST</filename> makes
13889 conceptual sense for
13890 <filename>-native</filename> recipes, as
13891 they make use of host headers and libraries.
13892 </para>
13893 </note>
13894 </para></listitem>
13895 </itemizedlist>
13896 </para>
13897 </glossdef>
13898 </glossentry>
13899
13900 <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
13901 <info>
13902 STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory used when building components that run on the build host itself."
13903 </info>
13904 <glossdef>
13905 <para role="glossdeffirst">
13906 Specifies the path to the sysroot directory used when
13907 building components that run on the build host itself.
13908 </para>
13909 </glossdef>
13910 </glossentry>
13911
13912 <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
13913 <info>
13914 STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot used for the system for which the component generates code."
13915 </info>
13916 <glossdef>
13917 <para role="glossdeffirst">
13918 Specifies the path to the sysroot used for the system for
13919 which the component generates code.
13920 For components that do not generate code, which is the
13921 majority, <filename>STAGING_DIR_TARGET</filename> is set
13922 to match
13923 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
13924 </para>
13925
13926 <para>
13927 Some recipes build binaries that can run on the target
13928 system but those binaries in turn generate code for
13929 another different system (e.g. cross-canadian recipes).
13930 Using terminology from GNU, the primary system is referred
13931 to as the "HOST" and the secondary, or different, system is
13932 referred to as the "TARGET".
13933 Thus, the binaries run on the "HOST" system
13934 and generate binaries for the "TARGET" system.
13935 The <filename>STAGING_DIR_HOST</filename> variable points
13936 to the sysroot used for the "HOST" system, while
13937 <filename>STAGING_DIR_TARGET</filename>
13938 points to the sysroot used for the "TARGET" system.
13939 </para>
13940 </glossdef>
13941 </glossentry>
13942
13943 <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
13944 <info>
13945 STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."
13946 </info>
13947 <glossdef>
13948 <para role="glossdeffirst">
13949 Specifies the path to the <filename>/etc</filename>
13950 subdirectory of the sysroot directory for the
13951 build host.
13952 </para>
13953 </glossdef>
13954 </glossentry>
13955
13956 <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
13957 <info>
13958 STAGING_EXECPREFIXDIR[doc] = "Specifies the path to the /usr subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
13959 </info>
13960 <glossdef>
13961 <para role="glossdeffirst">
13962 Specifies the path to the <filename>/usr</filename>
13963 subdirectory of the sysroot directory for the target
13964 for which the current recipe is being built
13965 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13966 </para>
13967 </glossdef>
13968 </glossentry>
13969
13970 <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
13971 <info>
13972 STAGING_INCDIR[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the target for which the current recipe being built (STAGING_DIR_HOST)."
13973 </info>
13974 <glossdef>
13975 <para role="glossdeffirst">
13976 Specifies the path to the
13977 <filename>/usr/include</filename> subdirectory of the
13978 sysroot directory for the target for which the current
13979 recipe being built
13980 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13981 </para>
13982 </glossdef>
13983 </glossentry>
13984
13985 <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
13986 <info>
13987 STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."
13988 </info>
13989 <glossdef>
13990 <para role="glossdeffirst">
13991 Specifies the path to the <filename>/usr/include</filename>
13992 subdirectory of the sysroot directory for the build host.
13993 </para>
13994 </glossdef>
13995 </glossentry>
13996
13997 <glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>
13998 <info>
13999 STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."
14000 </info>
14001 <glossdef>
14002 <para role="glossdeffirst">
14003 Points to the directory containing the kernel build
14004 artifacts.
14005 Recipes building software that needs to access kernel
14006 build artifacts
14007 (e.g. <filename>systemtap-uprobes</filename>) can look in
14008 the directory specified with the
14009 <filename>STAGING_KERNEL_BUILDDIR</filename> variable to
14010 find these artifacts after the kernel has been built.
14011 </para>
14012 </glossdef>
14013 </glossentry>
14014
14015 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
14016 <info>
14017 STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."
14018 </info>
14019 <glossdef>
14020 <para role="glossdeffirst">
14021 The directory with kernel headers that are required to build out-of-tree
14022 modules.
14023 </para>
14024 </glossdef>
14025 </glossentry>
14026
14027 <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
14028 <info>
14029 STAGING_LIBDIR[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
14030 </info>
14031 <glossdef>
14032 <para role="glossdeffirst">
14033 Specifies the path to the <filename>/usr/lib</filename>
14034 subdirectory of the sysroot directory for the target for
14035 which the current recipe is being built
14036 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14037 </para>
14038 </glossdef>
14039 </glossentry>
14040
14041 <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
14042 <info>
14043 STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."
14044 </info>
14045 <glossdef>
14046 <para role="glossdeffirst">
14047 Specifies the path to the <filename>/usr/lib</filename>
14048 subdirectory of the sysroot directory for the build host.
14049 </para>
14050 </glossdef>
14051 </glossentry>
14052
14053 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
14054 <info>
14055 STAMP[doc] = "Specifies the base path used to create recipe stamp files. The path to an actual stamp file is constructed by evaluating this string and then appending additional information."
14056 </info>
14057 <glossdef>
14058 <para role="glossdeffirst">
14059 Specifies the base path used to create recipe stamp files.
14060 The path to an actual stamp file is constructed by evaluating this
14061 string and then appending additional information.
14062 Currently, the default assignment for <filename>STAMP</filename>
14063 as set in the <filename>meta/conf/bitbake.conf</filename> file
14064 is:
14065 <literallayout class='monospaced'>
14066 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
14067 </literallayout>
14068 </para>
14069
14070 <para>
14071 For information on how BitBake uses stamp files to determine
14072 if a task should be rerun, see the
14073 "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
14074 section in the Yocto Project Overview and Concepts Manual.
14075 </para>
14076
14077 <para>
14078 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
14079 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
14080 <link linkend='var-PN'><filename>PN</filename></link>,
14081 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
14082 <link linkend='var-PV'><filename>PV</filename></link>, and
14083 <link linkend='var-PR'><filename>PR</filename></link> for related variable
14084 information.
14085 </para>
14086 </glossdef>
14087 </glossentry>
14088
14089 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
14090 <info>
14091 STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."
14092 </info>
14093 <glossdef>
14094 <para role="glossdeffirst">
14095 Specifies the base directory in which the OpenEmbedded
14096 build system places stamps.
14097 The default directory is
14098 <filename>${TMPDIR}/stamps</filename>.
14099 </para>
14100 </glossdef>
14101 </glossentry>
14102
14103 <glossentry id='var-STRIP'><glossterm>STRIP</glossterm>
14104 <info>
14105 STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."
14106 </info>
14107 <glossdef>
14108 <para role="glossdeffirst">
14109 The minimal command and arguments to run
14110 <filename>strip</filename>, which is used to strip
14111 symbols.
14112 </para>
14113 </glossdef>
14114 </glossentry>
14115
14116 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
14117 <info>
14118 SUMMARY[doc] = "The short (80 characters or less) summary of the binary package for packaging systems such as opkg, rpm, or dpkg. By default, SUMMARY is used to define the DESCRIPTION variable if DESCRIPTION is not set in the recipe."
14119 </info>
14120 <glossdef>
14121 <para role="glossdeffirst">
14122 The short (72 characters or less) summary of the binary package for packaging
14123 systems such as <filename>opkg</filename>, <filename>rpm</filename>, or
14124 <filename>dpkg</filename>.
14125 By default, <filename>SUMMARY</filename> is used to define
14126 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
14127 variable if <filename>DESCRIPTION</filename> is not set
14128 in the recipe.
14129 </para>
14130 </glossdef>
14131 </glossentry>
14132
14133 <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
14134 <info>
14135 SVNDIR[doc] = "The directory where Subversion checkouts are stored."
14136 </info>
14137 <glossdef>
14138 <para role="glossdeffirst">
14139 The directory in which files checked out of a Subversion
14140 system are stored.
14141 </para>
14142 </glossdef>
14143 </glossentry>
14144
14145 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
14146 <info>
14147 SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."
14148 </info>
14149 <glossdef>
14150 <para role="glossdeffirst">
14151 Specifies the kernel boot default console.
14152 If you want to use a console other than the default,
14153 set this variable in your recipe as follows where "X" is
14154 the console number you want to use:
14155 <literallayout class='monospaced'>
14156 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
14157 </literallayout>
14158 </para>
14159
14160 <para>
14161 The
14162 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14163 class initially sets this variable to null but then checks
14164 for a value later.
14165 </para>
14166 </glossdef>
14167 </glossentry>
14168
14169 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
14170 <info>
14171 SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."
14172 </info>
14173 <glossdef>
14174 <para role="glossdeffirst">
14175 Lists additional options to add to the syslinux file.
14176 You need to set this variable in your recipe.
14177 If you want to list multiple options, separate the options
14178 with a semicolon character (<filename>;</filename>).
14179 </para>
14180
14181 <para>
14182 The
14183 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14184 class uses this variable to create a set of options.
14185 </para>
14186 </glossdef>
14187 </glossentry>
14188
14189 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
14190 <info>
14191 SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."
14192 </info>
14193 <glossdef>
14194 <para role="glossdeffirst">
14195 Specifies the alternate serial port or turns it off.
14196 To turn off serial, set this variable to an empty string
14197 in your recipe.
14198 The variable's default value is set in the
14199 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14200 class as follows:
14201 <literallayout class='monospaced'>
14202 SYSLINUX_SERIAL ?= "0 115200"
14203 </literallayout>
14204 </para>
14205
14206 <para>
14207 The class checks for and uses the variable as needed.
14208 </para>
14209 </glossdef>
14210 </glossentry>
14211
14212 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
14213 <info>
14214 SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you use the boot menu."
14215 </info>
14216 <glossdef>
14217 <para role="glossdeffirst">
14218 An <filename>.LSS</filename> file used as the background
14219 for the VGA boot menu when you use the boot menu.
14220 You need to set this variable in your recipe.
14221 </para>
14222
14223 <para>
14224 The
14225 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14226 class checks for this variable and if found, the
14227 OpenEmbedded build system installs the splash screen.
14228 </para>
14229 </glossdef>
14230 </glossentry>
14231
14232 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
14233 <info>
14234 SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."
14235 </info>
14236 <glossdef>
14237 <para role="glossdeffirst">
14238 Specifies the alternate console=tty... kernel boot argument.
14239 The variable's default value is set in the
14240 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14241 class as follows:
14242 <literallayout class='monospaced'>
14243 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
14244 </literallayout>
14245 </para>
14246
14247 <para>
14248 The class checks for and uses the variable as needed.
14249 </para>
14250 </glossdef>
14251 </glossentry>
14252
14253 <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>
14254 <info>
14255 SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files populated into the sysroot are assembled during the do_populate_sysroot task."
14256 </info>
14257 <glossdef>
14258 <para role="glossdeffirst">
14259 Points to the temporary directory under the work directory
14260 (default
14261 "<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")
14262 where the files populated into the sysroot are assembled
14263 during the
14264 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14265 task.
14266 </para>
14267 </glossdef>
14268 </glossentry>
14269
14270 <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
14271 <info>
14272 SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."
14273 </info>
14274 <glossdef>
14275 <para role="glossdeffirst">
14276 Directories that are staged into the sysroot by the
14277 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14278 task.
14279 By default, the following directories are staged:
14280 <literallayout class='monospaced'>
14281 SYSROOT_DIRS = " \
14282 ${includedir} \
14283 ${libdir} \
14284 ${base_libdir} \
14285 ${nonarch_base_libdir} \
14286 ${datadir} \
14287 "
14288 </literallayout>
14289 </para>
14290 </glossdef>
14291 </glossentry>
14292
14293 <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
14294 <info>
14295 SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."
14296 </info>
14297 <glossdef>
14298 <para role="glossdeffirst">
14299 Directories that are not staged into the sysroot by the
14300 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14301 task.
14302 You can use this variable to exclude certain subdirectories
14303 of directories listed in
14304 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14305 from staging.
14306 By default, the following directories are not staged:
14307 <literallayout class='monospaced'>
14308 SYSROOT_DIRS_BLACKLIST = " \
14309 ${mandir} \
14310 ${docdir} \
14311 ${infodir} \
14312 ${datadir}/locale \
14313 ${datadir}/applications \
14314 ${datadir}/fonts \
14315 ${datadir}/pixmaps \
14316 "
14317 </literallayout>
14318 </para>
14319 </glossdef>
14320 </glossentry>
14321
14322 <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
14323 <info>
14324 SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged into the sysroot by the do_populate_sysroot task for -native recipes, in addition to those specified in SYSROOT_DIRS."
14325 </info>
14326 <glossdef>
14327 <para role="glossdeffirst">
14328 Extra directories staged into the sysroot by the
14329 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14330 task for <filename>-native</filename> recipes, in addition
14331 to those specified in
14332 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>.
14333 By default, the following extra directories are staged:
14334 <literallayout class='monospaced'>
14335 SYSROOT_DIRS_NATIVE = " \
14336 ${bindir} \
14337 ${sbindir} \
14338 ${base_bindir} \
14339 ${base_sbindir} \
14340 ${libexecdir} \
14341 ${sysconfdir} \
14342 ${localstatedir} \
14343 "
14344 </literallayout>
14345 <note>
14346 Programs built by <filename>-native</filename> recipes
14347 run directly from the sysroot
14348 (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),
14349 which is why additional directories containing program
14350 executables and supporting files need to be staged.
14351 </note>
14352 </para>
14353 </glossdef>
14354 </glossentry>
14355
14356 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
14357 <info>
14358 SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files."
14359 </info>
14360 <glossdef>
14361 <para role="glossdeffirst">
14362 A list of functions to execute after files are staged into
14363 the sysroot.
14364 These functions are usually used to apply additional
14365 processing on the staged files, or to stage additional
14366 files.
14367 </para>
14368 </glossdef>
14369 </glossentry>
14370
14371 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
14372 <info>
14373 SYSTEMD_AUTO_ENABLE[doc] = "For recipes that inherit the systemd class, this variable specifies whether the specified service in SYSTEMD_SERVICE should start automatically or not."
14374 </info>
14375 <glossdef>
14376 <para role="glossdeffirst">
14377 When inheriting the
14378 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14379 class, this variable specifies whether the specified service
14380 in
14381 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
14382 should start automatically or not.
14383 By default, the service is enabled to automatically start
14384 at boot time.
14385 The default setting is in the
14386 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14387 class as follows:
14388 <literallayout class='monospaced'>
14389 SYSTEMD_AUTO_ENABLE ??= "enable"
14390 </literallayout>
14391 </para>
14392
14393 <para>
14394 You can disable the service by setting the variable to
14395 "disable".
14396 </para>
14397 </glossdef>
14398 </glossentry>
14399
14400 <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>
14401 <info>
14402 SYSTEMD_BOOT_CFG[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_CFG variable specifies the configuration file that should be used."
14403 </info>
14404 <glossdef>
14405 <para role="glossdeffirst">
14406 When
14407 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14408 is set to "systemd-boot", the
14409 <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the
14410 configuration file that should be used.
14411 By default, the
14412 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14413 class sets the <filename>SYSTEMD_BOOT_CFG</filename> as
14414 follows:
14415 <literallayout class='monospaced'>
14416 SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"
14417 </literallayout>
14418 </para>
14419
14420 <para>
14421 For information on Systemd-boot, see the
14422 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14423 </para>
14424 </glossdef>
14425 </glossentry>
14426
14427 <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>
14428 <info>
14429 SYSTEMD_BOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_ENTRIES variable specifies a list of entry files (*.conf) to install that contain one boot entry per file."
14430 </info>
14431 <glossdef>
14432 <para role="glossdeffirst">
14433 When
14434 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14435 is set to "systemd-boot", the
14436 <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies
14437 a list of entry files
14438 (<filename>*.conf</filename>) to install that contain
14439 one boot entry per file.
14440 By default, the
14441 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14442 class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as
14443 follows:
14444 <literallayout class='monospaced'>
14445 SYSTEMD_BOOT_ENTRIES ?= ""
14446 </literallayout>
14447 </para>
14448
14449 <para>
14450 For information on Systemd-boot, see the
14451 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14452 </para>
14453 </glossdef>
14454 </glossentry>
14455
14456 <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm>
14457 <info>
14458 SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds."
14459 </info>
14460 <glossdef>
14461 <para role="glossdeffirst">
14462 When
14463 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14464 is set to "systemd-boot", the
14465 <filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies
14466 the boot menu timeout in seconds.
14467 By default, the
14468 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14469 class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as
14470 follows:
14471 <literallayout class='monospaced'>
14472 SYSTEMD_BOOT_TIMEOUT ?= "10"
14473 </literallayout>
14474 </para>
14475
14476 <para>
14477 For information on Systemd-boot, see the
14478 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14479 </para>
14480 </glossdef>
14481 </glossentry>
14482
14483 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
14484 <info>
14485 SYSTEMD_PACKAGES[doc] = "For recipes that inherit the systemd class, this variable locates the systemd unit files when they are not found in the main recipe's package."
14486 </info>
14487 <glossdef>
14488 <para role="glossdeffirst">
14489 When inheriting the
14490 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14491 class, this variable locates the systemd unit files when
14492 they are not found in the main recipe's package.
14493 By default, the
14494 <filename>SYSTEMD_PACKAGES</filename> variable is set
14495 such that the systemd unit files are assumed to reside in
14496 the recipes main package:
14497 <literallayout class='monospaced'>
14498 SYSTEMD_PACKAGES ?= "${PN}"
14499 </literallayout>
14500 </para>
14501
14502 <para>
14503 If these unit files are not in this recipe's main
14504 package, you need to use
14505 <filename>SYSTEMD_PACKAGES</filename> to list the package
14506 or packages in which the build system can find the systemd
14507 unit files.
14508 </para>
14509 </glossdef>
14510 </glossentry>
14511
14512 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
14513 <info>
14514 SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."
14515 </info>
14516 <glossdef>
14517 <para role="glossdeffirst">
14518 When inheriting the
14519 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14520 class, this variable specifies the systemd service name for
14521 a package.
14522 </para>
14523
14524 <para>
14525 When you specify this file in your recipe, use a package
14526 name override to indicate the package to which the value
14527 applies.
14528 Here is an example from the connman recipe:
14529 <literallayout class='monospaced'>
14530 SYSTEMD_SERVICE_${PN} = "connman.service"
14531 </literallayout>
14532 </para>
14533 </glossdef>
14534 </glossentry>
14535
14536 <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>
14537 <info>
14538 SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."
14539 </info>
14540 <glossdef>
14541 <para role="glossdeffirst">
14542 When using
14543 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
14544 specifies a space-separated list of the virtual terminals
14545 that should run a
14546 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
14547 (allowing login), assuming
14548 <link linkend='var-USE_VT'><filename>USE_VT</filename></link>
14549 is not set to "0".
14550 </para>
14551
14552 <para>
14553 The default value for
14554 <filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"
14555 (i.e. only run a getty on the first virtual terminal).
14556 </para>
14557 </glossdef>
14558 </glossentry>
14559
14560 </glossdiv>
14561
14562 <glossdiv id='var-glossary-t'><title>T</title>
14563
14564 <glossentry id='var-T'><glossterm>T</glossterm>
14565 <info>
14566 T[doc] = "This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a particular recipe."
14567 </info>
14568 <glossdef>
14569 <para role="glossdeffirst">
14570 This variable points to a directory were BitBake places
14571 temporary files, which consist mostly of task logs and
14572 scripts, when building a particular recipe.
14573 The variable is typically set as follows:
14574 <literallayout class='monospaced'>
14575 T = "${WORKDIR}/temp"
14576 </literallayout>
14577 </para>
14578
14579 <para>
14580 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
14581 is the directory into which BitBake unpacks and builds the
14582 recipe.
14583 The default <filename>bitbake.conf</filename> file sets this variable.</para>
14584 <para>The <filename>T</filename> variable is not to be confused with
14585 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
14586 which points to the root of the directory tree where BitBake
14587 places the output of an entire build.
14588 </para>
14589 </glossdef>
14590 </glossentry>
14591
14592 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
14593 <info>
14594 TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64."
14595 </info>
14596 <glossdef>
14597 <para role="glossdeffirst">
14598 The target machine's architecture.
14599 The OpenEmbedded build system supports many
14600 architectures.
14601 Here is an example list of architectures supported.
14602 This list is by no means complete as the architecture
14603 is configurable:
14604 <literallayout class='monospaced'>
14605 arm
14606 i586
14607 x86_64
14608 powerpc
14609 powerpc64
14610 mips
14611 mipsel
14612 </literallayout>
14613 </para>
14614
14615 <para>
14616 For additional information on machine architectures, see
14617 the
14618 <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
14619 variable.
14620 </para>
14621 </glossdef>
14622 </glossentry>
14623
14624 <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
14625 <info>
14626 TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."
14627 </info>
14628 <glossdef>
14629 <para role="glossdeffirst">
14630 Specifies architecture-specific assembler flags for the
14631 target system.
14632 <filename>TARGET_AS_ARCH</filename> is initialized from
14633 <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
14634 by default in the BitBake configuration file
14635 (<filename>meta/conf/bitbake.conf</filename>):
14636 <literallayout class='monospaced'>
14637 TARGET_AS_ARCH = "${TUNE_ASARGS}"
14638 </literallayout>
14639 </para>
14640 </glossdef>
14641 </glossentry>
14642
14643 <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
14644 <info>
14645 TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."
14646 </info>
14647 <glossdef>
14648 <para role="glossdeffirst">
14649 Specifies architecture-specific C compiler flags for the
14650 target system.
14651 <filename>TARGET_CC_ARCH</filename> is initialized from
14652 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
14653 by default.
14654 <note>
14655 It is a common workaround to append
14656 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
14657 to <filename>TARGET_CC_ARCH</filename>
14658 in recipes that build software for the target that
14659 would not otherwise respect the exported
14660 <filename>LDFLAGS</filename> variable.
14661 </note>
14662 </para>
14663 </glossdef>
14664 </glossentry>
14665
14666 <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
14667 <info>
14668 TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."
14669 </info>
14670 <glossdef>
14671 <para role="glossdeffirst">
14672 This is a specific kernel compiler flag for a CPU or
14673 Application Binary Interface (ABI) tune.
14674 The flag is used rarely and only for cases where a
14675 userspace
14676 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
14677 is not compatible with the kernel compilation.
14678 The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
14679 allows the kernel (and associated modules) to use a
14680 different configuration.
14681 See the
14682 <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
14683 file in the
14684 <link linkend='source-directory'>Source Directory</link>
14685 for an example.
14686 </para>
14687 </glossdef>
14688 </glossentry>
14689
14690 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
14691 <info>
14692 TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."
14693 </info>
14694 <glossdef>
14695 <para role="glossdeffirst">
14696 Specifies the flags to pass to the C compiler when building
14697 for the target.
14698 When building in the target context,
14699 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
14700 is set to the value of this variable by default.
14701 </para>
14702
14703 <para>
14704 Additionally, the SDK's environment setup script sets
14705 the <filename>CFLAGS</filename> variable in the environment
14706 to the <filename>TARGET_CFLAGS</filename> value so that
14707 executables built using the SDK also have the flags
14708 applied.
14709 </para>
14710 </glossdef>
14711 </glossentry>
14712
14713 <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
14714 <info>
14715 TARGET_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the target."
14716 </info>
14717 <glossdef>
14718 <para role="glossdeffirst">
14719 Specifies the flags to pass to the C pre-processor
14720 (i.e. to both the C and the C++ compilers) when building
14721 for the target.
14722 When building in the target context,
14723 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
14724 is set to the value of this variable by default.
14725 </para>
14726
14727 <para>
14728 Additionally, the SDK's environment setup script sets
14729 the <filename>CPPFLAGS</filename> variable in the
14730 environment to the <filename>TARGET_CPPFLAGS</filename>
14731 value so that executables built using the SDK also have
14732 the flags applied.
14733 </para>
14734 </glossdef>
14735 </glossentry>
14736
14737 <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
14738 <info>
14739 TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."
14740 </info>
14741 <glossdef>
14742 <para role="glossdeffirst">
14743 Specifies the flags to pass to the C++ compiler when
14744 building for the target.
14745 When building in the target context,
14746 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
14747 is set to the value of this variable by default.
14748 </para>
14749
14750 <para>
14751 Additionally, the SDK's environment setup script sets
14752 the <filename>CXXFLAGS</filename> variable in the
14753 environment to the <filename>TARGET_CXXFLAGS</filename>
14754 value so that executables built using the SDK also have
14755 the flags applied.
14756 </para>
14757 </glossdef>
14758 </glossentry>
14759
14760 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
14761 <info>
14762 TARGET_FPU[doc] = "Specifies the method for handling FPU code. For FPU-less targets, which include most ARM CPUs, the variable must be set to 'soft'. If not, the kernel emulation gets used, which results in a performance penalty."
14763 </info>
14764 <glossdef>
14765 <para role="glossdeffirst">
14766 Specifies the method for handling FPU code.
14767 For FPU-less targets, which include most ARM CPUs, the variable must be
14768 set to "soft".
14769 If not, the kernel emulation gets used, which results in a performance penalty.
14770 </para>
14771 </glossdef>
14772 </glossentry>
14773
14774 <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
14775 <info>
14776 TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."
14777 </info>
14778 <glossdef>
14779 <para role="glossdeffirst">
14780 Specifies architecture-specific linker flags for the
14781 target system.
14782 <filename>TARGET_LD_ARCH</filename> is initialized from
14783 <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
14784 by default in the BitBake configuration file
14785 (<filename>meta/conf/bitbake.conf</filename>):
14786 <literallayout class='monospaced'>
14787 TARGET_LD_ARCH = "${TUNE_LDARGS}"
14788 </literallayout>
14789 </para>
14790 </glossdef>
14791 </glossentry>
14792
14793 <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
14794 <info>
14795 TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."
14796 </info>
14797 <glossdef>
14798 <para role="glossdeffirst">
14799 Specifies the flags to pass to the linker when building
14800 for the target.
14801 When building in the target context,
14802 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
14803 is set to the value of this variable by default.
14804 </para>
14805
14806 <para>
14807 Additionally, the SDK's environment setup script sets
14808 the
14809 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
14810 variable in the environment to the
14811 <filename>TARGET_LDFLAGS</filename> value so that
14812 executables built using the SDK also have the flags
14813 applied.
14814 </para>
14815 </glossdef>
14816 </glossentry>
14817
14818 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
14819 <info>
14820 TARGET_OS[doc] = "Specifies the target's operating system."
14821 </info>
14822 <glossdef>
14823 <para role="glossdeffirst">
14824 Specifies the target's operating system.
14825 The variable can be set to "linux" for glibc-based systems
14826 (GNU C Library) and to "linux-musl" for musl libc.
14827 For ARM/EABI targets, "linux-gnueabi" and "linux-musleabi"
14828 possible values exist.
14829 </para>
14830 </glossdef>
14831 </glossentry>
14832
14833 <glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>
14834 <info>
14835 TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."
14836 </info>
14837 <glossdef>
14838 <para role="glossdeffirst">
14839 Specifies the prefix used for the toolchain binary target
14840 tools.
14841 </para>
14842
14843 <para>
14844 Depending on the type of recipe and the build target,
14845 <filename>TARGET_PREFIX</filename> is set as follows:
14846 <itemizedlist>
14847 <listitem><para>
14848 For recipes building for the target machine,
14849 the value is
14850 "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".
14851 </para></listitem>
14852 <listitem><para>
14853 For native recipes, the build system sets the
14854 variable to the value of
14855 <filename>BUILD_PREFIX</filename>.
14856 </para></listitem>
14857 <listitem><para>
14858 For native SDK recipes
14859 (<filename>nativesdk</filename>), the
14860 build system sets the variable to the value of
14861 <filename>SDK_PREFIX</filename>.
14862 </para></listitem>
14863 </itemizedlist>
14864 </para>
14865 </glossdef>
14866 </glossentry>
14867
14868 <glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>
14869 <info>
14870 TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."
14871 </info>
14872 <glossdef>
14873 <para role="glossdeffirst">
14874 Specifies the system, including the architecture and the
14875 operating system, for which the build is occurring in
14876 the context of the current recipe.
14877 </para>
14878
14879 <para>
14880 The OpenEmbedded build system automatically sets this
14881 variable based on
14882 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
14883 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>,
14884 and
14885 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
14886 variables.
14887 <note>
14888 You do not need to set the
14889 <filename>TARGET_SYS</filename> variable yourself.
14890 </note>
14891 </para>
14892
14893 <para>
14894 Consider these two examples:
14895 <itemizedlist>
14896 <listitem><para>
14897 Given a native recipe on a 32-bit, x86 machine
14898 running Linux, the value is "i686-linux".
14899 </para></listitem>
14900 <listitem><para>
14901 Given a recipe being built for a little-endian,
14902 MIPS target running Linux, the value might be
14903 "mipsel-linux".
14904 </para></listitem>
14905 </itemizedlist>
14906 </para>
14907 </glossdef>
14908 </glossentry>
14909
14910 <glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm>
14911 <info>
14912 TARGET_VENDOR[doc] = "The name of the target vendor."
14913 </info>
14914 <glossdef>
14915 <para role="glossdeffirst">
14916 Specifies the name of the target vendor.
14917 </para>
14918 </glossdef>
14919 </glossentry>
14920
14921 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
14922 <info>
14923 TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc', 'musl' or 'newlib'."
14924 </info>
14925 <glossdef>
14926 <para role="glossdeffirst">
14927 Specifies the GNU standard C library
14928 (<filename>libc</filename>) variant to use during the
14929 build process.
14930 This variable replaces <filename>POKYLIBC</filename>,
14931 which is no longer supported.
14932 </para>
14933
14934 <para>
14935 You can select "glibc", "musl", "newlib", or "baremetal"
14936 </para>
14937 </glossdef>
14938 </glossentry>
14939
14940 <glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>
14941 <info>
14942 TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."
14943 </info>
14944 <glossdef>
14945 <para role="glossdeffirst">
14946 Specifies a suffix to be appended onto the
14947 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
14948 value.
14949 The suffix identifies the <filename>libc</filename> variant
14950 for building.
14951 When you are building for multiple variants with the same
14952 <link linkend='build-directory'>Build Directory</link>,
14953 this mechanism ensures that output for different
14954 <filename>libc</filename> variants is kept separate to
14955 avoid potential conflicts.
14956 </para>
14957
14958 <para>
14959 In the <filename>defaultsetup.conf</filename> file, the
14960 default value of <filename>TCLIBCAPPEND</filename> is
14961 "-${TCLIBC}".
14962 However, distros such as poky, which normally only support
14963 one <filename>libc</filename> variant, set
14964 <filename>TCLIBCAPPEND</filename> to "" in their distro
14965 configuration file resulting in no suffix being applied.
14966 </para>
14967 </glossdef>
14968 </glossentry>
14969
14970 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
14971 <info>
14972 TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."
14973 </info>
14974 <glossdef>
14975 <para role="glossdeffirst">
14976 Specifies the toolchain selector.
14977 <filename>TCMODE</filename> controls the characteristics
14978 of the generated packages and images by telling the
14979 OpenEmbedded build system which toolchain profile to use.
14980 By default, the OpenEmbedded build system builds its own
14981 internal toolchain.
14982 The variable's default value is "default", which uses
14983 that internal toolchain.
14984 <note>
14985 If <filename>TCMODE</filename> is set to a value
14986 other than "default", then it is your responsibility
14987 to ensure that the toolchain is compatible with the
14988 default toolchain.
14989 Using older or newer versions of these components
14990 might cause build problems.
14991 See the Release Notes for the Yocto Project release
14992 for the specific components with which the toolchain
14993 must be compatible.
14994 To access the Release Notes, go to the
14995 <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
14996 page on the Yocto Project website and click on the
14997 "RELEASE INFORMATION" link for the appropriate
14998 release.
14999 </note>
15000 </para>
15001
15002 <para>
15003 The <filename>TCMODE</filename> variable is similar to
15004 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
15005 which controls the variant of the GNU standard C library
15006 (<filename>libc</filename>) used during the build process:
15007 <filename>glibc</filename> or <filename>musl</filename>.
15008 </para>
15009
15010 <para>
15011 With additional layers, it is possible to use a pre-compiled
15012 external toolchain.
15013 One example is the Sourcery G++ Toolchain.
15014 The support for this toolchain resides in the separate
15015 <trademark class='registered'>Mentor Graphics</trademark>
15016 <filename>meta-sourcery</filename> layer at
15017 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
15018 </para>
15019
15020 <para>
15021 The layer's <filename>README</filename> file contains
15022 information on how to use the Sourcery G++ Toolchain as
15023 an external toolchain.
15024 In summary, you must be sure to add the layer to your
15025 <filename>bblayers.conf</filename> file in front of the
15026 <filename>meta</filename> layer and then set the
15027 <filename>EXTERNAL_TOOLCHAIN</filename>
15028 variable in your <filename>local.conf</filename> file
15029 to the location in which you installed the toolchain.
15030 </para>
15031
15032 <para>
15033 The fundamentals used for this example apply to any
15034 external toolchain.
15035 You can use <filename>meta-sourcery</filename> as a
15036 template for adding support for other external toolchains.
15037 </para>
15038 </glossdef>
15039 </glossentry>
15040
15041 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
15042 <info>
15043 TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"."
15044 </info>
15045 <glossdef>
15046 <para role="glossdeffirst">
15047 The location the OpenEmbedded build system uses to export
15048 tests when the
15049 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
15050 variable is set to "1".
15051 </para>
15052
15053 <para>
15054 The <filename>TEST_EXPORT_DIR</filename> variable defaults
15055 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
15056 </para>
15057 </glossdef>
15058 </glossentry>
15059
15060 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
15061 <info>
15062 TEST_EXPORT_ONLY[doc] = "Specifies to export the tests only. Set this variable to "1" if you do not want to run the tests but you want them to be exported in a manner that you to run them outside of the build system."
15063 </info>
15064 <glossdef>
15065 <para role="glossdeffirst">
15066 Specifies to export the tests only.
15067 Set this variable to "1" if you do not want to run the
15068 tests but you want them to be exported in a manner that
15069 you to run them outside of the build system.
15070 </para>
15071 </glossdef>
15072 </glossentry>
15073
15074 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
15075 <info>
15076 TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The TEST_LOG_DIR variable defaults to "${WORKDIR}/testimage"."
15077 </info>
15078 <glossdef>
15079 <para role="glossdeffirst">
15080 Holds the SSH log and the boot log for QEMU machines.
15081 The <filename>TEST_LOG_DIR</filename> variable defaults
15082 to <filename>"${WORKDIR}/testimage"</filename>.
15083 <note>
15084 Actual test results reside in the task log
15085 (<filename>log.do_testimage</filename>), which is in
15086 the <filename>${WORKDIR}/temp/</filename> directory.
15087 </note>
15088 </para>
15089 </glossdef>
15090 </glossentry>
15091
15092 <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>
15093 <info>
15094 TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"
15095 </info>
15096 <glossdef>
15097 <para role="glossdeffirst">
15098 For automated hardware testing, specifies the command to
15099 use to control the power of the target machine under test.
15100 Typically, this command would point to a script that
15101 performs the appropriate action (e.g. interacting
15102 with a web-enabled power strip).
15103 The specified command should expect to receive as the last
15104 argument "off", "on" or "cycle" specifying to power off,
15105 on, or cycle (power off and then power on) the device,
15106 respectively.
15107 </para>
15108 </glossdef>
15109 </glossentry>
15110
15111 <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>
15112 <info>
15113 TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"
15114 </info>
15115 <glossdef>
15116 <para role="glossdeffirst">
15117 For automated hardware testing, specifies additional
15118 arguments to pass through to the command specified in
15119 <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>.
15120 Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
15121 is optional.
15122 You can use it if you wish, for example, to separate the
15123 machine-specific and non-machine-specific parts of the
15124 arguments.
15125 </para>
15126 </glossdef>
15127 </glossentry>
15128
15129 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
15130 <info>
15131 TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image."
15132 </info>
15133 <glossdef>
15134 <para role="glossdeffirst">
15135 The time in seconds allowed for an image to boot before
15136 automated runtime tests begin to run against an
15137 image.
15138 The default timeout period to allow the boot process to
15139 reach the login prompt is 500 seconds.
15140 You can specify a different value in the
15141 <filename>local.conf</filename> file.
15142 </para>
15143
15144 <para>
15145 For more information on testing images, see the
15146 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15147 section in the Yocto Project Development Tasks Manual.
15148 </para>
15149 </glossdef>
15150 </glossentry>
15151
15152 <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>
15153 <info>
15154 TEST_SERIALCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to connect to the serial console of the target machine under test."
15155 </info>
15156 <glossdef>
15157 <para role="glossdeffirst">
15158 For automated hardware testing, specifies the command
15159 to use to connect to the serial console of the target
15160 machine under test.
15161 This command simply needs to connect to the serial console
15162 and forward that connection to standard input and output
15163 as any normal terminal program does.
15164 </para>
15165
15166 <para>
15167 For example, to use the Picocom terminal program on
15168 serial device <filename>/dev/ttyUSB0</filename> at
15169 115200bps, you would set the variable as follows:
15170 <literallayout class='monospaced'>
15171 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
15172 </literallayout>
15173 </para>
15174 </glossdef>
15175 </glossentry>
15176
15177 <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>
15178 <info>
15179 TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."
15180 </info>
15181 <glossdef>
15182 <para role="glossdeffirst">
15183 For automated hardware testing, specifies additional
15184 arguments to pass through to the command specified in
15185 <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>.
15186 Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>
15187 is optional.
15188 You can use it if you wish, for example, to separate the
15189 machine-specific and non-machine-specific parts of the
15190 command.
15191 </para>
15192 </glossdef>
15193 </glossentry>
15194
15195 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
15196 <info>
15197 TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."
15198 </info>
15199 <glossdef>
15200 <para role="glossdeffirst">
15201 The IP address of the build machine (host machine).
15202 This IP address is usually automatically detected.
15203 However, if detection fails, this variable needs to be set
15204 to the IP address of the build machine (i.e. where
15205 the build is taking place).
15206 <note>
15207 The <filename>TEST_SERVER_IP</filename> variable
15208 is only used for a small number of tests such as
15209 the "dnf" test suite, which needs to download
15210 packages from
15211 <filename>WORKDIR/oe-rootfs-repo</filename>.
15212 </note>
15213 </para>
15214 </glossdef>
15215 </glossentry>
15216
15217 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
15218 <info>
15219 TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."
15220 </info>
15221 <glossdef>
15222 <para role="glossdeffirst">
15223 Specifies the target controller to use when running tests
15224 against a test image.
15225 The default controller to use is "qemu":
15226 <literallayout class='monospaced'>
15227 TEST_TARGET = "qemu"
15228 </literallayout>
15229 </para>
15230
15231 <para>
15232 A target controller is a class that defines how an
15233 image gets deployed on a target and how a target is started.
15234 A layer can extend the controllers by adding a module
15235 in the layer's <filename>/lib/oeqa/controllers</filename>
15236 directory and by inheriting the
15237 <filename>BaseTarget</filename> class, which is an abstract
15238 class that cannot be used as a value of
15239 <filename>TEST_TARGET</filename>.
15240 </para>
15241
15242 <para>
15243 You can provide the following arguments with
15244 <filename>TEST_TARGET</filename>:
15245 <itemizedlist>
15246 <listitem><para><emphasis>"qemu":</emphasis>
15247 Boots a QEMU image and runs the tests.
15248 See the
15249 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
15250 section in the Yocto Project Development Tasks
15251 Manual for more information.
15252 </para></listitem>
15253 <listitem><para><emphasis>"simpleremote":</emphasis>
15254 Runs the tests on target hardware that is already
15255 up and running.
15256 The hardware can be on the network or it can be
15257 a device running an image on QEMU.
15258 You must also set
15259 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
15260 when you use "simpleremote".
15261 <note>
15262 This argument is defined in
15263 <filename>meta/lib/oeqa/controllers/simpleremote.py</filename>.
15264 </note>
15265 </para></listitem>
15266 </itemizedlist>
15267 </para>
15268
15269 <para>
15270 For information on running tests on hardware, see the
15271 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
15272 section in the Yocto Project Development Tasks Manual.
15273 </para>
15274 </glossdef>
15275 </glossentry>
15276
15277 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
15278 <info>
15279 TEST_TARGET_IP[doc] = "The IP address of your hardware under test."
15280 </info>
15281 <glossdef>
15282 <para role="glossdeffirst">
15283 The IP address of your hardware under test.
15284 The <filename>TEST_TARGET_IP</filename> variable has no
15285 effect when
15286 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
15287 is set to "qemu".
15288 </para>
15289
15290 <para>
15291 When you specify the IP address, you can also include a
15292 port.
15293 Here is an example:
15294 <literallayout class='monospaced'>
15295 TEST_TARGET_IP = "192.168.1.4:2201"
15296 </literallayout>
15297 Specifying a port is useful when SSH is started on a
15298 non-standard port or in cases when your hardware under test
15299 is behind a firewall or network that is not directly
15300 accessible from your host and you need to do port address
15301 translation.
15302 </para>
15303 </glossdef>
15304 </glossentry>
15305
15306 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
15307 <info>
15308 TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."
15309 </info>
15310 <glossdef>
15311 <para role="glossdeffirst">
15312 An ordered list of tests (modules) to run against
15313 an image when performing automated runtime testing.
15314 </para>
15315
15316 <para>
15317 The OpenEmbedded build system provides a core set of tests
15318 that can be used against images.
15319 <note>
15320 Currently, there is only support for running these tests
15321 under QEMU.
15322 </note>
15323 Tests include <filename>ping</filename>,
15324 <filename>ssh</filename>, <filename>df</filename> among
15325 others.
15326 You can add your own tests to the list of tests by
15327 appending <filename>TEST_SUITES</filename> as follows:
15328 <literallayout class='monospaced'>
15329 TEST_SUITES_append = " <replaceable>mytest</replaceable>"
15330 </literallayout>
15331 Alternatively, you can provide the "auto" option to
15332 have all applicable tests run against the image.
15333 <literallayout class='monospaced'>
15334 TEST_SUITES_append = " auto"
15335 </literallayout>
15336 Using this option causes the build system to automatically
15337 run tests that are applicable to the image.
15338 Tests that are not applicable are skipped.
15339 </para>
15340
15341 <para>
15342 The order in which tests are run is important.
15343 Tests that depend on another test must appear later in the
15344 list than the test on which they depend.
15345 For example, if you append the list of tests with two
15346 tests (<filename>test_A</filename> and
15347 <filename>test_B</filename>) where
15348 <filename>test_B</filename> is dependent on
15349 <filename>test_A</filename>, then you must order the tests
15350 as follows:
15351 <literallayout class='monospaced'>
15352 TEST_SUITES = " test_A test_B"
15353 </literallayout>
15354 </para>
15355
15356 <para>
15357 For more information on testing images, see the
15358 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15359 section in the Yocto Project Development Tasks Manual.
15360 </para>
15361 </glossdef>
15362 </glossentry>
15363
15364 <glossentry id='var-TESTIMAGE_AUTO'><glossterm>TESTIMAGE_AUTO</glossterm>
15365 <info>
15366 TESTIMAGE_AUTO[doc] = "Enables automatic testing of an image once it is built."
15367 </info>
15368 <glossdef>
15369 <para role="glossdeffirst">
15370 Automatically runs the series of automated tests for
15371 images when an image is successfully built.
15372 Setting <filename>TESTIMAGE_AUTO</filename> to "1"
15373 causes any image that successfully builds to automatically
15374 boot under QEMU.
15375 Using the variable also adds in dependencies so that any
15376 SDK for which testing is requested is automatically built
15377 first.
15378 </para>
15379
15380 <para>
15381 These tests are written in Python making use of the
15382 <filename>unittest</filename> module, and the majority of
15383 them run commands on the target system over
15384 <filename>ssh</filename>.
15385 You can set this variable to "1" in your
15386 <filename>local.conf</filename> file in the
15387 <link linkend='build-directory'>Build Directory</link>
15388 to have the OpenEmbedded build system automatically run
15389 these tests after an image successfully builds:
15390 <literallayout class='monospaced'>
15391 TESTIMAGE_AUTO = "1"
15392 </literallayout>
15393 For more information on enabling, running, and writing
15394 these tests, see the
15395 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15396 section in the Yocto Project Development Tasks Manual and
15397 the
15398 "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
15399 section.
15400 </para>
15401 </glossdef>
15402 </glossentry>
15403
15404 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
15405 <info>
15406 THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."
15407 </info>
15408 <glossdef>
15409 <para role="glossdeffirst">
15410 The directory in which the file BitBake is currently
15411 parsing is located.
15412 Do not manually set this variable.
15413 </para>
15414 </glossdef>
15415 </glossentry>
15416
15417 <glossentry id='var-TIME'><glossterm>TIME</glossterm>
15418 <info>
15419 TIME[doc] = "The time the build was started using HMS format."
15420 </info>
15421 <glossdef>
15422 <para role="glossdeffirst">
15423 The time the build was started.
15424 Times appear using the hour, minute, and second (HMS)
15425 format (e.g. "140159" for one minute and fifty-nine
15426 seconds past 1400 hours).
15427 </para>
15428 </glossdef>
15429 </glossentry>
15430
15431 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
15432 <info>
15433 TMPDIR[doc] = "The temporary directory the OpenEmbedded build system uses when it does its work building images. By default, the TMPDIR variable is named tmp within the Build Directory."
15434 </info>
15435 <glossdef>
15436 <para role="glossdeffirst">
15437 This variable is the base directory the OpenEmbedded
15438 build system uses for all build output and intermediate
15439 files (other than the shared state cache).
15440 By default, the <filename>TMPDIR</filename> variable points
15441 to <filename>tmp</filename> within the
15442 <link linkend='build-directory'>Build Directory</link>.
15443 </para>
15444
15445 <para>
15446 If you want to establish this directory in a location other
15447 than the default, you can uncomment and edit the following
15448 statement in the
15449 <filename>conf/local.conf</filename> file in the
15450 <link linkend='source-directory'>Source Directory</link>:
15451 <literallayout class='monospaced'>
15452 #TMPDIR = "${TOPDIR}/tmp"
15453 </literallayout>
15454 An example use for this scenario is to set
15455 <filename>TMPDIR</filename> to a local disk, which does
15456 not use NFS, while having the Build Directory use NFS.
15457 </para>
15458
15459 <para>
15460 The filesystem used by <filename>TMPDIR</filename> must
15461 have standard filesystem semantics (i.e. mixed-case files
15462 are unique, POSIX file locking, and persistent inodes).
15463 Due to various issues with NFS and bugs in some
15464 implementations, NFS does not meet this minimum
15465 requirement.
15466 Consequently, <filename>TMPDIR</filename> cannot be on
15467 NFS.
15468 </para>
15469 </glossdef>
15470 </glossentry>
15471
15472 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
15473 <info>
15474 TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."
15475 </info>
15476 <glossdef>
15477 <para role="glossdeffirst">
15478 This variable lists packages the OpenEmbedded build system
15479 uses when building an SDK, which contains a
15480 cross-development environment.
15481 The packages specified by this variable are part of the
15482 toolchain set that runs on the
15483 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
15484 and each package should usually have the prefix
15485 <filename>nativesdk-</filename>.
15486 For example, consider the following command when
15487 building an SDK:
15488 <literallayout class='monospaced'>
15489 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
15490 </literallayout>
15491 In this case, a default list of packages is set in this
15492 variable, but you can add additional packages to the list.
15493 See the
15494 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"
15495 section in the Yocto Project Application Development and
15496 the Extensible Software Development Kit (eSDK) manual
15497 for more information.
15498 </para>
15499
15500 <para>
15501 For background information on cross-development toolchains
15502 in the Yocto Project development environment, see the
15503 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15504 section in the Yocto Project Overview and Concepts Manual.
15505 For information on setting up a cross-development
15506 environment, see the
15507 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15508 manual.
15509 </para>
15510 </glossdef>
15511 </glossentry>
15512
15513 <glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>
15514 <info>
15515 TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."
15516 </info>
15517 <glossdef>
15518 <para role="glossdeffirst">
15519 This variable defines the name used for the toolchain
15520 output.
15521 The
15522 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
15523 class sets the
15524 <filename>TOOLCHAIN_OUTPUTNAME</filename> variable as
15525 follows:
15526 <literallayout class='monospaced'>
15527 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
15528 </literallayout>
15529 See the
15530 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
15531 and
15532 <link linkend='var-SDK_VERSION'><filename>SDK_VERSION</filename></link>
15533 variables for additional information.
15534 </para>
15535 </glossdef>
15536 </glossentry>
15537
15538 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
15539 <info>
15540 TOOLCHAIN_TARGET_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when it creates the target part of an SDK, which includes libraries and headers."
15541 </info>
15542 <glossdef>
15543 <para role="glossdeffirst">
15544 This variable lists packages the OpenEmbedded build system
15545 uses when it creates the target part of an SDK
15546 (i.e. the part built for the target hardware), which
15547 includes libraries and headers.
15548 Use this variable to add individual packages to the
15549 part of the SDK that runs on the target.
15550 See the
15551 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"
15552 section in the Yocto Project Application Development and
15553 the Extensible Software Development Kit (eSDK) manual for
15554 more information.
15555 </para>
15556
15557 <para>
15558 For background information on cross-development toolchains
15559 in the Yocto Project development environment, see the
15560 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15561 section in the Yocto Project Overview and Concepts Manual.
15562 For information on setting up a cross-development
15563 environment, see the
15564 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15565 manual.
15566 </para>
15567 </glossdef>
15568 </glossentry>
15569
15570 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
15571 <info>
15572 TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."
15573 </info>
15574 <glossdef>
15575 <para role="glossdeffirst">
15576 The top-level
15577 <link linkend='build-directory'>Build Directory</link>.
15578 BitBake automatically sets this variable when you
15579 initialize your build environment using
15580 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
15581 </para>
15582 </glossdef>
15583 </glossentry>
15584
15585 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
15586 <info>
15587 TRANSLATED_TARGET_ARCH[doc] = "A sanitized version of TARGET_ARCH. This variable is used where the architecture is needed in a value where underscores are not allowed."
15588 </info>
15589 <glossdef>
15590 <para role="glossdeffirst">
15591 A sanitized version of
15592 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
15593 This variable is used where the architecture is needed in
15594 a value where underscores are not allowed, for example
15595 within package filenames.
15596 In this case, dash characters replace any underscore
15597 characters used in <filename>TARGET_ARCH</filename>.
15598 </para>
15599
15600 <para>
15601 Do not edit this variable.
15602 </para>
15603 </glossdef>
15604 </glossentry>
15605
15606 <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
15607 <info>
15608 TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)."
15609 </info>
15610 <glossdef>
15611 <para role="glossdeffirst">
15612 The GNU canonical architecture for a specific architecture
15613 (i.e. <filename>arm</filename>,
15614 <filename>armeb</filename>,
15615 <filename>mips</filename>,
15616 <filename>mips64</filename>, and so forth).
15617 BitBake uses this value to setup configuration.
15618 </para>
15619
15620 <para>
15621 <filename>TUNE_ARCH</filename> definitions are specific to
15622 a given architecture.
15623 The definitions can be a single static definition, or
15624 can be dynamically adjusted.
15625 You can see details for a given CPU family by looking at
15626 the architecture's <filename>README</filename> file.
15627 For example, the
15628 <filename>meta/conf/machine/include/mips/README</filename>
15629 file in the
15630 <link linkend='source-directory'>Source Directory</link>
15631 provides information for <filename>TUNE_ARCH</filename>
15632 specific to the <filename>mips</filename> architecture.
15633 </para>
15634
15635 <para>
15636 <filename>TUNE_ARCH</filename> is tied closely to
15637 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
15638 which defines the target machine's architecture.
15639 The BitBake configuration file
15640 (<filename>meta/conf/bitbake.conf</filename>) sets
15641 <filename>TARGET_ARCH</filename> as follows:
15642 <literallayout class='monospaced'>
15643 TARGET_ARCH = "${TUNE_ARCH}"
15644 </literallayout>
15645 </para>
15646
15647 <para>
15648 The following list, which is by no means complete since
15649 architectures are configurable, shows supported machine
15650 architectures:
15651 <literallayout class='monospaced'>
15652 arm
15653 i586
15654 x86_64
15655 powerpc
15656 powerpc64
15657 mips
15658 mipsel
15659 </literallayout>
15660 </para>
15661 </glossdef>
15662 </glossentry>
15663
15664 <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
15665 <info>
15666 TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."
15667 </info>
15668 <glossdef>
15669 <para role="glossdeffirst">
15670 Specifies architecture-specific assembler flags for
15671 the target system.
15672 The set of flags is based on the selected tune features.
15673 <filename>TUNE_ASARGS</filename> is set using
15674 the tune include files, which are typically under
15675 <filename>meta/conf/machine/include/</filename> and are
15676 influenced through
15677 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
15678 For example, the
15679 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
15680 file defines the flags for the x86 architecture as follows:
15681 <literallayout class='monospaced'>
15682 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
15683 </literallayout>
15684 <note>
15685 Board Support Packages (BSPs) select the tune.
15686 The selected tune, in turn, affects the tune variables
15687 themselves (i.e. the tune can supply its own
15688 set of flags).
15689 </note>
15690 </para>
15691 </glossdef>
15692 </glossentry>
15693
15694 <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
15695 <info>
15696 TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."
15697 </info>
15698 <glossdef>
15699 <para role="glossdeffirst">
15700 Specifies architecture-specific C compiler flags for
15701 the target system.
15702 The set of flags is based on the selected tune features.
15703 <filename>TUNE_CCARGS</filename> is set using
15704 the tune include files, which are typically under
15705 <filename>meta/conf/machine/include/</filename> and are
15706 influenced through
15707 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
15708 <note>
15709 Board Support Packages (BSPs) select the tune.
15710 The selected tune, in turn, affects the tune variables
15711 themselves (i.e. the tune can supply its own
15712 set of flags).
15713 </note>
15714 </para>
15715 </glossdef>
15716 </glossentry>
15717
15718 <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
15719 <info>
15720 TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."
15721 </info>
15722 <glossdef>
15723 <para role="glossdeffirst">
15724 Specifies architecture-specific linker flags for
15725 the target system.
15726 The set of flags is based on the selected tune features.
15727 <filename>TUNE_LDARGS</filename> is set using
15728 the tune include files, which are typically under
15729 <filename>meta/conf/machine/include/</filename> and are
15730 influenced through
15731 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
15732 For example, the
15733 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
15734 file defines the flags for the x86 architecture as follows:
15735 <literallayout class='monospaced'>
15736 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
15737 </literallayout>
15738 <note>
15739 Board Support Packages (BSPs) select the tune.
15740 The selected tune, in turn, affects the tune variables
15741 themselves (i.e. the tune can supply its own
15742 set of flags).
15743 </note>
15744 </para>
15745 </glossdef>
15746 </glossentry>
15747
15748 <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
15749 <info>
15750 TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."
15751 </info>
15752 <glossdef>
15753 <para role="glossdeffirst">
15754 Features used to "tune" a compiler for optimal use
15755 given a specific processor.
15756 The features are defined within the tune files and allow
15757 arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
15758 dynamically generated based on the features.
15759 </para>
15760
15761 <para>
15762 The OpenEmbedded build system verifies the features
15763 to be sure they are not conflicting and that they are
15764 supported.
15765 </para>
15766
15767 <para>
15768 The BitBake configuration file
15769 (<filename>meta/conf/bitbake.conf</filename>) defines
15770 <filename>TUNE_FEATURES</filename> as follows:
15771 <literallayout class='monospaced'>
15772 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
15773 </literallayout>
15774 See the
15775 <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
15776 variable for more information.
15777 </para>
15778 </glossdef>
15779 </glossentry>
15780
15781 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
15782 <info>
15783 TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."
15784 </info>
15785 <glossdef>
15786 <para role="glossdeffirst">
15787 The package architecture understood by the packaging
15788 system to define the architecture, ABI, and tuning of
15789 output packages.
15790 The specific tune is defined using the "_tune" override
15791 as follows:
15792 <literallayout class='monospaced'>
15793 TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"
15794 </literallayout>
15795 </para>
15796
15797 <para>
15798 These tune-specific package architectures are defined in
15799 the machine include files.
15800 Here is an example of the "core2-32" tuning as used
15801 in the
15802 <filename>meta/conf/machine/include/tune-core2.inc</filename>
15803 file:
15804 <literallayout class='monospaced'>
15805 TUNE_PKGARCH_tune-core2-32 = "core2-32"
15806 </literallayout>
15807 </para>
15808 </glossdef>
15809 </glossentry>
15810
15811 <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
15812 <info>
15813 TUNEABI[doc] = "An underlying ABI used by a particular tuning in a given toolchain layer. This feature allows providers using prebuilt libraries to check compatibility of a tuning against their selection of libraries."
15814 </info>
15815 <glossdef>
15816 <para role="glossdeffirst">
15817 An underlying Application Binary Interface (ABI) used by
15818 a particular tuning in a given toolchain layer.
15819 Providers that use prebuilt libraries can use the
15820 <filename>TUNEABI</filename>,
15821 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
15822 and
15823 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
15824 variables to check compatibility of tunings against their
15825 selection of libraries.
15826 </para>
15827
15828 <para>
15829 If <filename>TUNEABI</filename> is undefined, then every
15830 tuning is allowed.
15831 See the
15832 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
15833 class to see how the variable is used.
15834 </para>
15835 </glossdef>
15836 </glossentry>
15837
15838 <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
15839 <info>
15840 TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."
15841 </info>
15842 <glossdef>
15843 <para role="glossdeffirst">
15844 If set, the OpenEmbedded system ignores the
15845 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
15846 variable.
15847 Providers that use prebuilt libraries can use the
15848 <filename>TUNEABI_OVERRIDE</filename>,
15849 <filename>TUNEABI_WHITELIST</filename>,
15850 and
15851 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
15852 variables to check compatibility of a tuning against their
15853 selection of libraries.
15854 </para>
15855
15856 <para>
15857 See the
15858 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
15859 class to see how the variable is used.
15860 </para>
15861 </glossdef>
15862 </glossentry>
15863
15864 <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
15865 <info>
15866 TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."
15867 </info>
15868 <glossdef>
15869 <para role="glossdeffirst">
15870 A whitelist of permissible
15871 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
15872 values.
15873 If <filename>TUNEABI_WHITELIST</filename> is not set,
15874 all tunes are allowed.
15875 Providers that use prebuilt libraries can use the
15876 <filename>TUNEABI_WHITELIST</filename>,
15877 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
15878 and <filename>TUNEABI</filename> variables to check
15879 compatibility of a tuning against their selection of
15880 libraries.
15881 </para>
15882
15883 <para>
15884 See the
15885 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
15886 class to see how the variable is used.
15887 </para>
15888 </glossdef>
15889 </glossentry>
15890
15891 <glossentry id='var-TUNECONFLICTS'><glossterm>TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm>
15892 <info>
15893 TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."
15894 </info>
15895 <glossdef>
15896 <para role="glossdeffirst">
15897 Specifies CPU or Application Binary Interface (ABI)
15898 tuning features that conflict with <replaceable>feature</replaceable>.
15899 </para>
15900
15901 <para>
15902 Known tuning conflicts are specified in the machine include
15903 files in the
15904 <link linkend='source-directory'>Source Directory</link>.
15905 Here is an example from the
15906 <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
15907 include file that lists the "o32" and "n64" features as
15908 conflicting with the "n32" feature:
15909 <literallayout class='monospaced'>
15910 TUNECONFLICTS[n32] = "o32 n64"
15911 </literallayout>
15912 </para>
15913 </glossdef>
15914 </glossentry>
15915
15916 <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>
15917 <info>
15918 TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."
15919 </info>
15920 <glossdef>
15921 <para role="glossdeffirst">
15922 Specifies a valid CPU or Application Binary Interface (ABI)
15923 tuning feature.
15924 The specified feature is stored as a flag.
15925 Valid features are specified in the machine include files
15926 (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
15927 Here is an example from that file:
15928 <literallayout class='monospaced'>
15929 TUNEVALID[bigendian] = "Enable big-endian mode."
15930 </literallayout>
15931 </para>
15932
15933 <para>
15934 See the machine include files in the
15935 <link linkend='source-directory'>Source Directory</link>
15936 for these features.
15937 </para>
15938 </glossdef>
15939 </glossentry>
15940
15941 </glossdiv>
15942
15943 <glossdiv id='var-glossary-u'><title>U</title>
15944
15945 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
15946 <info>
15947 UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases."
15948 </info>
15949 <glossdef>
15950 <para role="glossdeffirst">
15951 Configures the
15952 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
15953 and can also define
15954 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
15955 for individual cases.
15956 </para>
15957
15958 <para>
15959 Following is an example from the
15960 <filename>meta-fsl-arm</filename> layer.
15961 <literallayout class='monospaced'>
15962 UBOOT_CONFIG ??= "sd"
15963 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
15964 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
15965 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
15966 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
15967 </literallayout>
15968 In this example, "sd" is selected as the configuration
15969 of the possible four for the
15970 <filename>UBOOT_MACHINE</filename>.
15971 The "sd" configuration defines "mx6qsabreauto_config"
15972 as the value for <filename>UBOOT_MACHINE</filename>, while
15973 the "sdcard" specifies the
15974 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
15975 image.
15976 </para>
15977
15978 <para>
15979 For more information on how the
15980 <filename>UBOOT_CONFIG</filename> is handled, see the
15981 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
15982 class.
15983 </para>
15984 </glossdef>
15985 </glossentry>
15986
15987 <glossentry id='var-UBOOT_DTB_LOADADDRESS'><glossterm>UBOOT_DTB_LOADADDRESS</glossterm>
15988 <info>
15989 UBOOT_DTB_LOADADDRESS[doc] = "Specifies the load address for the dtb."
15990 </info>
15991 <glossdef>
15992 <para role="glossdeffirst">
15993 Specifies the load address for the dtb image used by U-boot.
15994 During FIT image creation, the
15995 <filename>UBOOT_DTB_LOADADDRESS</filename> variable is used
15996 in <filename>kernel-fitimage</filename> class to specify the
15997 load address to be used in creating the dtb sections of
15998 Image Tree Source for the FIT image.
15999 </para>
16000 </glossdef>
16001 </glossentry>
16002
16003 <glossentry id='var-UBOOT_DTBO_LOADADDRESS'><glossterm>UBOOT_DTBO_LOADADDRESS</glossterm>
16004 <info>
16005 UBOOT_DTBO_LOADADDRESS[doc] = "Specifies the load address for the dtbo."
16006 </info>
16007 <glossdef>
16008 <para role="glossdeffirst">
16009 Specifies the load address for the dtbo image used by U-boot.
16010 During FIT image creation, the
16011 <filename>UBOOT_DTBO_LOADADDRESS</filename> variable is used
16012 in <filename>kernel-fitimage</filename> class to specify the
16013 load address to be used in creating the dtbo sections of
16014 Image Tree Source for the FIT image.
16015 </para>
16016 </glossdef>
16017 </glossentry>
16018
16019 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
16020 <info>
16021 UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."
16022 </info>
16023 <glossdef>
16024 <para role="glossdeffirst">
16025 Specifies the entry point for the U-Boot image.
16026 During U-Boot image creation, the
16027 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
16028 as a command-line parameter to the
16029 <filename>uboot-mkimage</filename> utility.
16030 </para>
16031 </glossdef>
16032 </glossentry>
16033
16034 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
16035 <info>
16036 UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."
16037 </info>
16038 <glossdef>
16039 <para role="glossdeffirst">
16040 Specifies the load address for the U-Boot image.
16041 During U-Boot image creation, the
16042 <filename>UBOOT_LOADADDRESS</filename> variable is passed
16043 as a command-line parameter to the
16044 <filename>uboot-mkimage</filename> utility.
16045 </para>
16046 </glossdef>
16047 </glossentry>
16048
16049 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
16050 <info>
16051 UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."
16052 </info>
16053 <glossdef>
16054 <para role="glossdeffirst">
16055 Appends a string to the name of the local version of the
16056 U-Boot image.
16057 For example, assuming the version of the U-Boot image
16058 built was "2013.10", the full version string reported by
16059 U-Boot would be "2013.10-yocto" given the following
16060 statement:
16061 <literallayout class='monospaced'>
16062 UBOOT_LOCALVERSION = "-yocto"
16063 </literallayout>
16064 </para>
16065 </glossdef>
16066 </glossentry>
16067
16068 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
16069 <info>
16070 UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."
16071 </info>
16072 <glossdef>
16073 <para role="glossdeffirst">
16074 Specifies the value passed on the
16075 <filename>make</filename> command line when building
16076 a U-Boot image.
16077 The value indicates the target platform configuration.
16078 You typically set this variable from the machine
16079 configuration file (i.e.
16080 <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).
16081 </para>
16082
16083 <para>
16084 Please see the "Selection of Processor Architecture and
16085 Board Type" section in the U-Boot README for valid values
16086 for this variable.
16087 </para>
16088 </glossdef>
16089 </glossentry>
16090
16091 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
16092 <info>
16093 UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."
16094 </info>
16095 <glossdef>
16096 <para role="glossdeffirst">
16097 Specifies the target called in the
16098 <filename>Makefile</filename>.
16099 The default target is "all".
16100 </para>
16101 </glossdef>
16102 </glossentry>
16103
16104 <glossentry id='var-UBOOT_MKIMAGE_DTCOPTS'><glossterm>UBOOT_MKIMAGE_DTCOPTS</glossterm>
16105 <info>
16106 UBOOT_MKIMAGE_DTCOPTS[doc] = "Options for the device tree compiler passed to mkimage '-D' feature."
16107 </info>
16108 <glossdef>
16109 <para role="glossdeffirst">
16110 Options for the device tree compiler passed to mkimage '-D'
16111 feature while creating FIT image in
16112 <filename>kernel-fitimage</filename> class.
16113 </para>
16114 </glossdef>
16115 </glossentry>
16116
16117 <glossentry id='var-UBOOT_RD_LOADADDRESS'><glossterm>UBOOT_RD_LOADADDRESS</glossterm>
16118 <info>
16119 UBOOT_RD_LOADADDRESS[doc] = "Specifies the load address for the ramdisk image."
16120 </info>
16121 <glossdef>
16122 <para role="glossdeffirst">
16123 Specifies the load address for the RAM disk image.
16124 During FIT image creation, the
16125 <filename>UBOOT_RD_LOADADDRESS</filename> variable is used
16126 in <filename>kernel-fitimage</filename> class to specify the
16127 load address to be used in creating the Image Tree Source for
16128 the FIT image.
16129 </para>
16130 </glossdef>
16131 </glossentry>
16132
16133 <glossentry id='var-UBOOT_RD_ENTRYPOINT'><glossterm>UBOOT_RD_ENTRYPOINT</glossterm>
16134 <info>
16135 UBOOT_RD_ENTRYPOINT[doc] = "Specifies the entrypoint for the ramdisk image."
16136 </info>
16137 <glossdef>
16138 <para role="glossdeffirst">
16139 Specifies the entrypoint for the RAM disk image.
16140 During FIT image creation, the
16141 <filename>UBOOT_RD_ENTRYPOINT</filename> variable is used
16142 in <filename>kernel-fitimage</filename> class to specify the
16143 entrypoint to be used in creating the Image Tree Source for
16144 the FIT image.
16145 </para>
16146 </glossdef>
16147 </glossentry>
16148
16149 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
16150 <info>
16151 UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."
16152 </info>
16153 <glossdef>
16154 <para role="glossdeffirst">
16155 Points to the generated U-Boot extension.
16156 For example, <filename>u-boot.sb</filename> has a
16157 <filename>.sb</filename> extension.
16158 </para>
16159
16160 <para>
16161 The default U-Boot extension is
16162 <filename>.bin</filename>
16163 </para>
16164 </glossdef>
16165 </glossentry>
16166
16167 <glossentry id='var-UBOOT_SIGN_ENABLE'><glossterm>UBOOT_SIGN_ENABLE</glossterm>
16168 <info>
16169 UBOOT_SIGN_KEYDIR[doc] = "Enable signing of FIT image."
16170 </info>
16171 <glossdef>
16172 <para role="glossdeffirst">
16173 Enable signing of FIT image. The default value is "0".
16174 </para>
16175 </glossdef>
16176 </glossentry>
16177
16178 <glossentry id='var-UBOOT_SIGN_KEYDIR'><glossterm>UBOOT_SIGN_KEYDIR</glossterm>
16179 <info>
16180 UBOOT_SIGN_KEYDIR[doc] = "Location of the directory containing the RSA key and certificate used for signing FIT image."
16181 </info>
16182 <glossdef>
16183 <para role="glossdeffirst">
16184 Location of the directory containing the RSA key and
16185 certificate used for signing FIT image.
16186 </para>
16187 </glossdef>
16188 </glossentry>
16189
16190 <glossentry id='var-UBOOT_SIGN_KEYNAME'><glossterm>UBOOT_SIGN_KEYNAME</glossterm>
16191 <info>
16192 UBOOT_SIGN_KEYNAME[doc] = "The name of keys used for signing U-boot FIT image"
16193 </info>
16194 <glossdef>
16195 <para role="glossdeffirst">
16196 The name of keys used for signing U-boot FIT image stored in
16197 <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>
16198 directory. For e.g. dev.key key and dev.crt certificate
16199 stored in
16200 <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>
16201 directory will have
16202 <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename>
16203 set to "dev".
16204 </para>
16205 </glossdef>
16206 </glossentry>
16207
16208 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
16209 <info>
16210 UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."
16211 </info>
16212 <glossdef>
16213 <para role="glossdeffirst">
16214 Specifies the target used for building U-Boot.
16215 The target is passed directly as part of the "make" command
16216 (e.g. SPL and AIS).
16217 If you do not specifically set this variable, the
16218 OpenEmbedded build process passes and uses "all" for the
16219 target during the U-Boot building process.
16220 </para>
16221 </glossdef>
16222 </glossentry>
16223
16224 <glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>
16225 <info>
16226 UNKNOWN_CONFIGURE_WHITELIST[doc] = "Specifies a list of options that, if reported by the configure script as being invalid, should not generate a warning during the do_configure task."
16227 </info>
16228 <glossdef>
16229 <para role="glossdeffirst">
16230 Specifies a list of options that, if reported by the
16231 configure script as being invalid, should not generate a
16232 warning during the
16233 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
16234 task.
16235 Normally, invalid configure options are simply not passed
16236 to the configure script (e.g. should be removed from
16237 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
16238 or
16239 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>).
16240 However, common options, for example, exist that are passed
16241 to all configure scripts at a class level that might not
16242 be valid for some configure scripts.
16243 It follows that no benefit exists in seeing a warning about
16244 these options.
16245 For these cases, the options are added to
16246 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.
16247 </para>
16248
16249 <para>
16250 The configure arguments check that uses
16251 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part
16252 of the
16253 <link linkend='ref-classes-insane'><filename>insane</filename></link>
16254 class and is only enabled if the recipe inherits the
16255 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
16256 class.
16257 </para>
16258 </glossdef>
16259 </glossentry>
16260
16261 <glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>
16262 <info>
16263 UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."
16264 </info>
16265 <glossdef>
16266 <para role="glossdeffirst">
16267 For recipes inheriting the
16268 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
16269 class, <filename>UPDATERCPN</filename> specifies
16270 the package that contains the initscript that is
16271 enabled.
16272 </para>
16273
16274 <para>
16275 The default value is "${PN}".
16276 Given that almost all recipes that install initscripts
16277 package them in the main package for the recipe, you
16278 rarely need to set this variable in individual recipes.
16279 </para>
16280 </glossdef>
16281 </glossentry>
16282
16283 <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>
16284 <info>
16285 UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."
16286 </info>
16287 <glossdef>
16288 <para role="glossdeffirst">
16289 You can perform a per-recipe check for what the latest
16290 upstream source code version is by calling
16291 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
16292 If the recipe source code is provided from Git
16293 repositories, the OpenEmbedded build system determines the
16294 latest upstream version by picking the latest tag from the
16295 list of all repository tags.
16296 </para>
16297
16298 <para>
16299 You can use the
16300 <filename>UPSTREAM_CHECK_GITTAGREGEX</filename>
16301 variable to provide a regular expression to filter only the
16302 relevant tags should the default filter not work
16303 correctly.
16304 <literallayout class='monospaced'>
16305 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
16306 </literallayout>
16307 </para>
16308 </glossdef>
16309 </glossentry>
16310
16311 <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>
16312 <info>
16313 UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."
16314 </info>
16315 <glossdef>
16316 <para role="glossdeffirst">
16317 Use the <filename>UPSTREAM_CHECK_REGEX</filename> variable
16318 to specify a different regular expression instead of the
16319 default one when the package checking system is parsing
16320 the page found using
16321 <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>.
16322 <literallayout class='monospaced'>
16323 UPSTREAM_CHECK_REGEX = "package_regex"
16324 </literallayout>
16325 </para>
16326 </glossdef>
16327 </glossentry>
16328
16329 <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm>
16330 <info>
16331 UPSTREAM_CHECK_URI[doc] = "The URL used by the package checking system to get the latest version of the package when source files are fetched from an upstream Git repository."
16332 </info>
16333 <glossdef>
16334 <para role="glossdeffirst">
16335 You can perform a per-recipe check for what the latest
16336 upstream source code version is by calling
16337 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
16338 If the source code is provided from tarballs, the latest
16339 version is determined by fetching the directory listing
16340 where the tarball is and attempting to find a later tarball.
16341 When this approach does not work, you can use
16342 <filename>UPSTREAM_CHECK_URI</filename> to
16343 provide a different URI that contains the link to the
16344 latest tarball.
16345 <literallayout class='monospaced'>
16346 UPSTREAM_CHECK_URI = "recipe_url"
16347 </literallayout>
16348 </para>
16349 </glossdef>
16350 </glossentry>
16351
16352 <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>
16353 <info>
16354 USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."
16355 </info>
16356 <glossdef>
16357 <para role="glossdeffirst">
16358 Determines if <filename>devtmpfs</filename> is used for
16359 <filename>/dev</filename> population.
16360 The default value used for <filename>USE_DEVFS</filename>
16361 is "1" when no value is specifically set.
16362 Typically, you would set <filename>USE_DEVFS</filename>
16363 to "0" for a statically populated <filename>/dev</filename>
16364 directory.
16365 </para>
16366
16367 <para>
16368 See the
16369 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>"
16370 section in the Yocto Project Development Tasks Manual for
16371 information on how to use this variable.
16372 </para>
16373 </glossdef>
16374 </glossentry>
16375
16376 <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm>
16377 <info>
16378 USE_VT[doc] = "When using SysVinit, determines whether or not to run a getty on any virtual terminals in order to enable logging in through those terminals."
16379 </info>
16380 <glossdef>
16381 <para role="glossdeffirst">
16382 When using
16383 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
16384 determines whether or not to run a
16385 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
16386 on any virtual terminals in order to enable logging in
16387 through those terminals.
16388 </para>
16389
16390 <para>
16391 The default value used for <filename>USE_VT</filename>
16392 is "1" when no default value is specifically set.
16393 Typically, you would set <filename>USE_VT</filename>
16394 to "0" in the machine configuration file for machines
16395 that do not have a graphical display attached and
16396 therefore do not need virtual terminal functionality.
16397 </para>
16398 </glossdef>
16399 </glossentry>
16400
16401 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
16402 <info>
16403 USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."
16404 </info>
16405 <glossdef>
16406 <para role="glossdeffirst">
16407 A list of classes to globally inherit.
16408 These classes are used by the OpenEmbedded build system
16409 to enable extra features (e.g.
16410 <filename>buildstats</filename>,
16411 <filename>image-mklibs</filename>, and so forth).
16412 </para>
16413
16414 <para>
16415 The default list is set in your
16416 <filename>local.conf</filename> file:
16417 <literallayout class='monospaced'>
16418 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
16419 </literallayout>
16420 For more information, see
16421 <filename>meta-poky/conf/local.conf.sample</filename> in
16422 the
16423 <link linkend='source-directory'>Source Directory</link>.
16424 </para>
16425 </glossdef>
16426 </glossentry>
16427
16428 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
16429 <info>
16430 USERADD_ERROR_DYNAMIC[doc] = "If set to 'error', forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in any of the files listed in USERADD_UID_TABLES and USERADD_GID_TABLES. If set to 'warn', a warning will be issued instead."
16431 </info>
16432 <glossdef>
16433 <para role="glossdeffirst">
16434
16435 If set to <filename>error</filename>, forces the
16436 OpenEmbedded build system to produce an error if the user
16437 identification (<filename>uid</filename>) and group
16438 identification (<filename>gid</filename>) values are not
16439 defined in any of the files listed
16440 in <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
16441 and <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>. If
16442 set to <filename>warn</filename>, a warning will be issued
16443 instead.
16444 </para>
16445
16446 <para>
16447 The default behavior for the build system is to dynamically
16448 apply <filename>uid</filename> and
16449 <filename>gid</filename> values.
16450 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
16451 variable is by default not set.
16452 If you plan on using statically assigned
16453 <filename>gid</filename> and <filename>uid</filename>
16454 values, you should set
16455 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
16456 your <filename>local.conf</filename> file as
16457 follows:
16458 <literallayout class='monospaced'>
16459 USERADD_ERROR_DYNAMIC = "error"
16460 </literallayout>
16461 Overriding the default behavior implies you are going to
16462 also take steps to set static <filename>uid</filename> and
16463 <filename>gid</filename> values through use of the
16464 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
16465 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
16466 and
16467 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16468 variables.
16469 </para>
16470
16471 <note>
16472 There is a difference in behavior between
16473 setting <filename>USERADD_ERROR_DYNAMIC</filename>
16474 to <filename>error</filename> and setting it
16475 to <filename>warn</filename>. When it is set
16476 to <filename>warn</filename>, the build system will report a
16477 warning for every undefined <filename>uid</filename> and
16478 <filename>gid</filename> in any recipe. But when it is set
16479 to <filename>error</filename>, it will only report errors
16480 for recipes that are actually built. This saves you from
16481 having to add static IDs for recipes that you know will
16482 never be built.
16483 </note>
16484 </glossdef>
16485 </glossentry>
16486
16487 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
16488 <info>
16489 USERADD_GID_TABLES[doc] = "Specifies a password file to use for obtaining static group identification (gid) values when the OpenEmbedded build system adds a group to the system during package installation."
16490 </info>
16491 <glossdef>
16492 <para role="glossdeffirst">
16493 Specifies a password file to use for obtaining static
16494 group identification (<filename>gid</filename>) values
16495 when the OpenEmbedded build system adds a group to the
16496 system during package installation.
16497 </para>
16498
16499 <para>
16500 When applying static group identification
16501 (<filename>gid</filename>) values, the OpenEmbedded build
16502 system looks in
16503 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16504 for a <filename>files/group</filename> file and then applies
16505 those <filename>uid</filename> values.
16506 Set the variable as follows in your
16507 <filename>local.conf</filename> file:
16508 <literallayout class='monospaced'>
16509 USERADD_GID_TABLES = "files/group"
16510 </literallayout>
16511 </para>
16512
16513 <note>
16514 Setting the
16515 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16516 variable to "useradd-staticids" causes the build system
16517 to use static <filename>gid</filename> values.
16518 </note>
16519 </glossdef>
16520 </glossentry>
16521
16522 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
16523 <info>
16524 USERADD_PACKAGES[doc] = "When a recipe inherits the useradd class, this variable specifies the individual packages within the recipe that require users and/or groups to be added."
16525 </info>
16526 <glossdef>
16527 <para role="glossdeffirst">
16528 When inheriting the
16529 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16530 class, this variable
16531 specifies the individual packages within the recipe that
16532 require users and/or groups to be added.
16533 </para>
16534
16535 <para>
16536 You must set this variable if the recipe inherits the
16537 class.
16538 For example, the following enables adding a user for the
16539 main package in a recipe:
16540 <literallayout class='monospaced'>
16541 USERADD_PACKAGES = "${PN}"
16542 </literallayout>
16543 <note>
16544 It follows that if you are going to use the
16545 <filename>USERADD_PACKAGES</filename> variable,
16546 you need to set one or more of the
16547 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
16548 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
16549 or
16550 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
16551 variables.
16552 </note>
16553 </para>
16554
16555 </glossdef>
16556 </glossentry>
16557
16558 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
16559 <info>
16560 USERADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should pass to the useradd command if you add a user to the system when the package is installed."
16561 </info>
16562 <glossdef>
16563 <para role="glossdeffirst">
16564 When inheriting the
16565 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16566 class, this variable
16567 specifies for a package what parameters should pass
16568 to the <filename>useradd</filename> command
16569 if you add a user to the system when the package
16570 is installed.
16571 </para>
16572
16573 <para>
16574 Here is an example from the <filename>dbus</filename>
16575 recipe:
16576 <literallayout class='monospaced'>
16577 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
16578 --no-create-home --shell /bin/false \
16579 --user-group messagebus"
16580 </literallayout>
16581 For information on the standard Linux shell command
16582 <filename>useradd</filename>, see
16583 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
16584 </para>
16585 </glossdef>
16586 </glossentry>
16587
16588 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
16589 <info>
16590 USERADD_UID_TABLES[doc] = "Specifies a password file to use for obtaining static user identification (uid) values when the OpenEmbedded build system adds a user to the system during package installation."
16591 </info>
16592 <glossdef>
16593 <para role="glossdeffirst">
16594 Specifies a password file to use for obtaining static
16595 user identification (<filename>uid</filename>) values
16596 when the OpenEmbedded build system adds a user to the
16597 system during package installation.
16598 </para>
16599
16600 <para>
16601 When applying static user identification
16602 (<filename>uid</filename>) values, the OpenEmbedded build
16603 system looks in
16604 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16605 for a <filename>files/passwd</filename> file and then applies
16606 those <filename>uid</filename> values.
16607 Set the variable as follows in your
16608 <filename>local.conf</filename> file:
16609 <literallayout class='monospaced'>
16610 USERADD_UID_TABLES = "files/passwd"
16611 </literallayout>
16612 </para>
16613
16614 <note>
16615 Setting the
16616 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16617 variable to "useradd-staticids" causes the build system
16618 to use static <filename>uid</filename> values.
16619 </note>
16620 </glossdef>
16621 </glossentry>
16622
16623 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
16624 <info>
16625 USERADDEXTENSION[doc] = "When set to 'useradd-staticids', causes the OpenEmbedded build system to base all user and group additions on a static passwd and group files found in BBPATH."
16626 </info>
16627 <glossdef>
16628 <para role="glossdeffirst">
16629 When set to "useradd-staticids", causes the
16630 OpenEmbedded build system to base all user and group
16631 additions on a static
16632 <filename>passwd</filename> and
16633 <filename>group</filename> files found in
16634 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
16635 </para>
16636
16637 <para>
16638 To use static user identification (<filename>uid</filename>)
16639 and group identification (<filename>gid</filename>)
16640 values, set the variable
16641 as follows in your <filename>local.conf</filename> file:
16642 <literallayout class='monospaced'>
16643 USERADDEXTENSION = "useradd-staticids"
16644 </literallayout>
16645 <note>
16646 Setting this variable to use static
16647 <filename>uid</filename> and <filename>gid</filename>
16648 values causes the OpenEmbedded build system to employ
16649 the
16650 <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
16651 class.
16652 </note>
16653 </para>
16654
16655 <para>
16656 If you use static <filename>uid</filename> and
16657 <filename>gid</filename> information, you must also
16658 specify the <filename>files/passwd</filename> and
16659 <filename>files/group</filename> files by setting the
16660 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
16661 and
16662 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16663 variables.
16664 Additionally, you should also set the
16665 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
16666 variable.
16667 </para>
16668 </glossdef>
16669 </glossentry>
16670
16671 </glossdiv>
16672
16673 <glossdiv id='var-glossary-v'><title>V</title>
16674
16675 <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>
16676 <info>
16677 VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."
16678 </info>
16679 <glossdef>
16680 <para role="glossdeffirst">
16681 Specifies the persistence of the target's
16682 <filename>/var/log</filename> directory, which is used to
16683 house postinstall target log files.
16684 </para>
16685
16686 <para>
16687 By default, <filename>VOLATILE_LOG_DIR</filename> is set
16688 to "yes", which means the file is not persistent.
16689 You can override this setting by setting the
16690 variable to "no" to make the log directory persistent.
16691 </para>
16692 </glossdef>
16693 </glossentry>
16694
16695 </glossdiv>
16696
16697 <glossdiv id='var-glossary-w'><title>W</title>
16698
16699 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
16700 <info>
16701 WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system."
16702 </info>
16703 <glossdef>
16704 <para role="glossdeffirst">
16705 Specifies the quality assurance checks whose failures are
16706 reported as warnings by the OpenEmbedded build system.
16707 You set this variable in your distribution configuration
16708 file.
16709 For a list of the checks you can control with this variable,
16710 see the
16711 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
16712 section.
16713 </para>
16714 </glossdef>
16715 </glossentry>
16716
16717 <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm>
16718 <info>
16719 WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic."
16720 </info>
16721 <glossdef>
16722 <para role="glossdeffirst">
16723 When placed in the recipe that builds your image, this
16724 variable lists build-time dependencies.
16725 The <filename>WKS_FILE_DEPENDS</filename> variable is only
16726 applicable when Wic images are active (i.e. when
16727 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
16728 contains entries related to Wic).
16729 If your recipe does not create Wic images, the variable
16730 has no effect.
16731 </para>
16732
16733 <para>
16734 The <filename>WKS_FILE_DEPENDS</filename> variable is
16735 similar to the
16736 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
16737 variable.
16738 When you use the variable in your recipe that builds the
16739 Wic image, dependencies you list in the
16740 <filename>WIC_FILE_DEPENDS</filename> variable are added to
16741 the <filename>DEPENDS</filename> variable.
16742 </para>
16743
16744 <para>
16745 With the <filename>WKS_FILE_DEPENDS</filename> variable,
16746 you have the possibility to specify a list of additional
16747 dependencies (e.g. native tools, bootloaders, and so forth),
16748 that are required to build Wic images.
16749 Following is an example:
16750 <literallayout class='monospaced'>
16751 WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>"
16752 </literallayout>
16753 In the previous example,
16754 <replaceable>some-native-tool</replaceable> would be
16755 replaced with an actual native tool on which the build
16756 would depend.
16757 </para>
16758 </glossdef>
16759 </glossentry>
16760
16761 <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm>
16762 <info>
16763 WKS_FILE[doc] = "Specifies the name of the wic kickstart file."
16764 </info>
16765 <glossdef>
16766 <para role="glossdeffirst">
16767 Specifies the location of the Wic
16768 kickstart file that is used by the OpenEmbedded build
16769 system to create a partitioned image
16770 (<replaceable>image</replaceable><filename>.wic</filename>).
16771 For information on how to create a partitioned image, see
16772 the
16773 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
16774 section in the Yocto Project Development Tasks Manual.
16775 For details on the kickstart file format, see the
16776 "<link linkend='ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>"
16777 Chapter.
16778 </para>
16779 </glossdef>
16780 </glossentry>
16781
16782 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
16783 <info>
16784 WORKDIR[doc] = "The pathname of the working directory in which the OpenEmbedded build system builds a recipe. This directory is located within the TMPDIR directory structure and changes as different packages are built."
16785 </info>
16786 <glossdef>
16787 <para role="glossdeffirst">
16788 The pathname of the work directory in which the OpenEmbedded
16789 build system builds a recipe.
16790 This directory is located within the
16791 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
16792 directory structure and is specific to the recipe being
16793 built and the system for which it is being built.
16794 </para>
16795
16796 <para>
16797 The <filename>WORKDIR</filename> directory is defined as
16798 follows:
16799 <literallayout class='monospaced'>
16800 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
16801 </literallayout>
16802 The actual directory depends on several things:
16803 <itemizedlist>
16804 <listitem><filename>TMPDIR</filename>:
16805 The top-level build output directory</listitem>
16806 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
16807 The target system identifier</listitem>
16808 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
16809 The recipe name</listitem>
16810 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
16811 The epoch - (if
16812 <link linkend='var-PE'><filename>PE</filename></link>
16813 is not specified, which is usually the case for most
16814 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
16815 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
16816 The recipe version</listitem>
16817 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
16818 The recipe revision</listitem>
16819 </itemizedlist>
16820 </para>
16821
16822 <para>
16823 As an example, assume a Source Directory top-level folder
16824 name <filename>poky</filename>, a default Build Directory at
16825 <filename>poky/build</filename>, and a
16826 <filename>qemux86-poky-linux</filename> machine target
16827 system.
16828 Furthermore, suppose your recipe is named
16829 <filename>foo_1.3.0-r0.bb</filename>.
16830 In this case, the work directory the build system uses to
16831 build the package would be as follows:
16832 <literallayout class='monospaced'>
16833 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
16834 </literallayout>
16835 </para>
16836 </glossdef>
16837 </glossentry>
16838
16839 </glossdiv>
16840
16841 <glossdiv id='var-glossary-x'><title>X</title>
16842
16843 <glossentry id='var-XSERVER'><glossterm>XSERVER</glossterm>
16844 <info>
16845 XSERVER[doc] = "Specifies the packages that should be installed to provide an X server and drivers for the current machine."
16846 </info>
16847 <glossdef>
16848 <para role="glossdeffirst">
16849 Specifies the packages that should be installed to
16850 provide an X server and drivers for the current machine,
16851 assuming your image directly includes
16852 <filename>packagegroup-core-x11-xserver</filename> or,
16853 perhaps indirectly, includes "x11-base" in
16854 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
16855 </para>
16856
16857 <para>
16858 The default value of <filename>XSERVER</filename>, if not
16859 specified in the machine configuration, is
16860 "xserver-xorg xf86-video-fbdev xf86-input-evdev".
16861 </para>
16862 </glossdef>
16863 </glossentry>
16864
16865 </glossdiv>
16866
16867<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
16868<!-- </glossdiv>-->
16869
16870<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
16871<!-- </glossdiv>-->
16872
16873</glossary>
16874</chapter>
16875<!--
16876vim: expandtab tw=80 ts=4
16877-->